Designing Agent Actions That Can Be Undone: A Reversibility Plan Before You Automate

Most agent safety work asks whether an action should be allowed. A reversibility plan asks a second question, before the first run: if this action is wrong, how do we get back? The answer changes the design. An agent that drafts an email can be corrected with a delete key. An agent that sends the same email cannot be corrected at all, because the message now lives in inboxes you do not control. Both actions use the same tool and similar arguments. They differ in one property that should govern permissions, preview, approval, and logging: how completely, how quickly, and at what cost the effect can be undone.

This guide is only about that property. Permissions decide who may act, and the permissions guide on this site covers that ground. Error recovery covers what to do when a run fails partway. The production harness checklist covers the wider runtime audit. Here the scope is narrower and earlier: classify every action an agent can take by its reversibility, write the way back before the way forward goes live, and scale the controls to the tier. Teams that do this work up front discover their risky actions while the stakes are still a design review. Teams that skip it discover them during an incident, when the way back has to be invented under time pressure and the prior state is no longer available to restore.

The plan has five parts, and none of them require a new tool. Classify each action into one of three tiers. Capture the prior state the reversal will need. Pre-write a compensating action for everything that cannot be restored directly. Add dry-run previews and idempotency so a run creates exactly one effect, and a reviewable one. Then set an undo window and an approval gate per tier, and record enough in the audit trail that a person who was not present can carry out the reversal days later.

Why reversibility is a design question, not a recovery question

Recovery assumes the facts you need still exist. Reversibility design makes sure they do. To reverse a file edit, you need the earlier version. To reverse a record update, you need the field values from before the update. To reverse a charge, you need the original transaction identifier and the authority to issue the compensating entry. Every one of those inputs is cheapest at the moment the action runs and most expensive, or simply absent, a week later. A system that overwrites in place and logs only that an update happened has not left reversal to chance; it has ruled reversal out.

There is a second reason to settle this early. Classification changes which automations are worth building. Some workflows look attractive until their actions are tiered in full, and then the shape changes: the agent prepares, stages, and checks, while a person releases the one irreversible step. Other workflows look risky in general terms and turn out to be mostly tier one work with a single tier three step buried in the middle. Splitting that step out makes the rest safe to automate sooner. You cannot make either call from a tool list. You make it from a reversibility table, action by action.

Tier one: freely reversible

Tier one actions can be undone completely, quickly, and by the same authority that performed them, with no third party affected in the meantime. Undoing them restores the prior state, not an approximation of it, and nobody outside the system needs to be notified, compensated, or convinced. These are the actions an agent can usually run without a gate, provided the reversal path is real and tested rather than assumed.

• Drafting an email, message, or document that has not been sent or shared. Deleting or editing the draft restores the prior state exactly, because nothing left your control.
• Editing a file where version history is turned on and retained, so the earlier version can be restored by identifier. The version history is the reversal mechanism; without it, the same edit drops to tier three.
• Creating a calendar hold, a task, or a tag that can be removed, where removal leaves no public trace and nobody has yet acted on it.
• Writing to a staging area, a draft record, or a preview environment that production readers never see.
• Reordering, labelling, or grouping items inside your own system, where the grouping carries no external meaning and can be reset.
• Generating a report or analysis file. The file can be discarded; the risk in this work sits in decisions made from a wrong report, not in the file itself.

Tier one is not a synonym for harmless. A draft that an agent treats as approved copy, or a staging change that auto-publishes on a schedule, leaves this tier the moment someone relies on it. Classify the action as it is wired in your system, not as the tool name suggests. The test is operational: perform the action in a trial run, then reverse it, then show that the system matches the state from before the trial. If you cannot run that test and show the result, the action does not belong in tier one yet.

Tier two: reversible at a cost

Tier two actions can be undone, but the reversal is a new action with its own cost, delay, or residue. Money may come back minus fees or days later. A message can be corrected, but readers saw the first version. A record can be restored, but downstream copies made in the interval keep the wrong values until they sync again. Tier two is where most production agent work lives, and it is the tier most often misclassified as tier one because a reversal feature exists in the product. The existence of a reversal feature tells you return is possible. It says nothing about what return costs or what it fails to repair.

• Issuing a refund for a card payment. The customer is made whole in amount, eventually, but the original charge and the refund both appear, settlement and fees do not rewind, and support time is spent. Pre-write the refund path and its limits before the agent can charge.
• Sending an internal message that can be edited or deleted in the same system. Deletion removes the text, not the memory of anyone who read it, and not screenshots or notifications delivered outside the system. A correction message is usually the real compensating action.
• Cancelling an order or booking that carries a cancellation fee, a restock step, or a release delay. The cancellation works; it just is not free, and the fee rules belong in the approval prompt.
• Publishing a post or page and later taking it down. Removal stops new readers. It does not recall copies, search indexes, or shares made while it was live, which is why publishing usually needs a preview gate even though unpublishing exists.
• Changing a price, a status, or a setting that customers or partners can see and act on, then changing it back. Orders placed at the wrong price in the interval are tier two consequences that a revert does not touch; honouring or cancelling them is a compensating action with a policy behind it.
• Updating a record that other systems copy on a schedule. Your system can be restored at once; the copies converge at the next sync, and anything they did with the wrong value in between has to be handled case by case.

For tier two, the design work is to price the reversal before approving the automation. Write down what the compensating action is, who may run it, how long it takes, what it cannot fix, and what it costs in money, time, or goodwill. That written price then sets the gate: a reversal that costs a minute of staff time can sit behind a light check, while a reversal that costs fees plus a customer apology needs an approver who sees the stakes before the action runs, not after.

Tier three: irreversible

Tier three actions cannot be undone in any way that restores the prior state. Sometimes the mechanism itself offers no return path. More often, the return path closes because other people or systems now hold the effect: they read the message, settled the funds, relied on the filing, or copied the data onward. Once reliance happens, later actions can compensate, apologise, or mitigate. They cannot un-happen the event, and a plan that pretends otherwise will mislead the approver at the exact moment accuracy matters most.

• Sending a wire payment, or any payment rail where recall is not a normal feature. Recovery becomes a request to the receiving side, not an action you control.
• Sending an email or message to external recipients. Recall features, where they exist, work inside one organisation and inside a short window; forwarding, quoting, and reading happen outside both.
• Overwriting a file, record, or configuration with no earlier version retained. The prior state is not hidden or archived; it no longer exists. Restoration then means reconstruction from memory or from other sources, with gaps you may not be able to detect.
• Deleting records with no trash, backup, or export taken first. Delete is the clearest tier three action, and the one most often hidden behind a tidy interface verb like remove or clean up.
• Submitting a filing, application, bid, or signed document to a third party. Withdrawal may be possible in some processes, on their timetable and terms; submission itself changes your position as soon as it lands.
• Disclosing information to someone who should not have it. Access can be revoked going forward. Information already seen cannot be unseen, which makes sharing and permission grants to external parties tier three even when the grant itself is easy to switch off.

Classify borderline actions by the worst plausible case, not the usual case. An internal send is tier two on a quiet day and tier three the day a recipient forwards it outside. An overwrite is tier one with version history on and tier three the day retention is shortened or the file sits outside the versioned store. When the tier depends on a setting, write the setting next to the classification and treat changing that setting as a reclassification event that needs the same review as adding a new tool. That rule is borrowed from permission practice - the agent tool permissions guide makes the same point about scope - because a quiet configuration change should not silently turn a gated action into a free one, or a reversible one into a permanent one.

Compensating actions: undo is often a second action

Direct restoration works for drafts, staged changes, and versioned edits. For most tier two work, and for the damage control around tier three, reversal means a compensating action: a new, deliberate action that offsets the effect of the first. A refund compensates a charge. A correction message compensates a wrong send. A restore job compensates an update by writing the captured prior values back. A follow-up filing compensates an error in an earlier submission where the process allows one. Naming these as compensating actions, rather than calling all of them undo, keeps the plan accurate about residue: compensation can make a customer whole and still leave fees, history entries, and explanations behind.

Write each compensating action before the original action is automated, in the same detail you would want at incident time. Four fields are enough. Trigger: the condition that says run it, stated so a person on call can decide without the original operator. Steps: the exact sequence, with the tool, the target identifier, and the values or source of values to use. Authority: who may run it, and who must approve it when the compensation itself moves money or contacts people. Limit: what it will not fix, written plainly, so nobody promises a full restoration that compensation cannot deliver. Then test it. Run the original action on a trial target, run the compensation, and compare the end state against the checklist. A compensating action that has never been run is a hypothesis, and incidents are a poor place to test hypotheses.

• Refund or credit for a charge: needs the original transaction id, the amount rule (full or partial), and the approver for amounts above a threshold you set.
• Correction or recall note for a message: needs the recipient list from the original send, the wrong statement quoted, and the corrected statement ready to paste, not drafted during the incident.
• Restore from prior state for an update: needs the captured before-values, the record id, and a check that no later legitimate edit will be overwritten by the restore.
• Revoke and reissue for a credential, link, or grant shared in error: needs the identifier that was shared, the revocation step, and a note of who may already have used it.
• Cancel and rebook for an order or reservation: needs the cancellation terms, the fee exposure, and the rule for who absorbs the fee.

Capture prior state before the action runs

Every reversal in the previous section consumes one input: the state from before the action. Capturing it is therefore not logging for its own sake; it is stocking the reversal. Capture needs to happen inside the same step as the action, before execution, and it needs to be tied to the action record so it can be found by action id later. A backup taken last night is a recovery asset for disasters. It is not a reversibility mechanism for a single wrong update at noon, because restoring it would also rewind every legitimate change since the backup.

• For an edit or update: the record or file identifier, the field values being changed, and the version identifier or timestamp of the version being replaced.
• For a create: the fact that the object did not exist before, plus the identifier assigned, so reversal knows deletion of that specific object is the correct offset.
• For a send: the final content as sent, the recipient list as resolved at send time, and the template or draft id it came from. Recipient lists change; the reversal needs the list as it was, not as it is now.
• For a payment or order: the amount, currency, destination, and the quote or cart state it was based on, so a discrepancy can be shown rather than argued about.
• For a delete: a complete export or copy of what will be deleted, stored outside the system being deleted from, with a retention date. If this capture cannot be made, the delete stays tier three and gated.
• For a settings or permission change: the prior setting value and the prior access list. Permission changes are easy to make and hard to reconstruct from memory a week later.

Store prior state with the same care as the data itself. It can contain the sensitive values the action touched, so it inherits their access controls and retention limits. It also needs a stated lifetime: keep it at least as long as the undo window plus the time you allow for discovering a problem, then delete it on schedule. A prior-state store that grows forever becomes its own risk, and a reversal archive nobody can search by action id fails at the moment it is needed.

Dry-run and preview modes

A dry run executes everything except the effect. The agent resolves the target, gathers inputs, applies its rules, and produces the action it would take, in full, for inspection. A preview mode does the same for a human reader: before and after values side by side, recipients resolved to names, amounts totalled, records counted. Both modes serve reversibility in two ways. They catch wrong actions while the tier is still effectively zero, because nothing has happened. They also force the system to assemble exactly the information a reversal will need later - target, inputs, prior state - which exposes capture gaps while there is still time to fix them.

Judge a dry run by whether a reviewer could sign their name to it. A preview that says three records will be updated, without saying which three or what changes, is a summary of intent, not a preview. For batch work, show the total count, the selection rule, a sample of affected items, and a way to inspect the full list. For sends, show the final text and the resolved recipients. For money movement, show amount, destination, and the source document the figures came from. If the underlying system cannot produce that preview, that limitation is a finding about the automation itself: an action that cannot be previewed can rarely be verified afterwards either, and it should be tiered and gated accordingly. The checklist before real work guide on this site makes a parallel point about trial runs - the dry run is where the classification meets a real target for the first time, and mismatches found there are the cheapest ones you will ever get.

• Preview shows the exact action: tool, target, and arguments, not a paraphrase written by the agent.
• Preview shows prior state next to proposed state for every field that will change.
• Preview names the tier, the compensating action on standby, and the approver required at that tier.
• Preview for a batch states the count and the selection rule, and the count is checked again at execution; a changed count stops the run.
• Dry-run output is saved with the run record, so what was approved can be compared with what executed.

Idempotency: a retry must not double-apply

Reversibility plans fail quietly at the retry. A tool call times out after it succeeded. A run is resumed after a crash. A queue delivers the same instruction twice. In each case the agent, acting reasonably on the information it has, performs the action again: a second charge, a duplicate order, a repeated send. Now the reversal problem has doubled, and the second effect may have spread further than the first. Idempotency is the property that applying the same intended action more than once leaves the world as if it had been applied once. Designing for it is part of reversibility because it controls how many effects a reversal has to cover.

The working pattern has three parts. First, assign each intended action a stable action id and, where the receiving system supports it, pass an idempotency key derived from that id, so a repeated submission is recognised as the same request rather than a new one. Second, record completion durably before the run moves to its next step: which action id executed, against which target, with what result identifier. Third, check before executing: a step that finds a completion record for its action id reads the recorded result and moves on instead of executing again. Check-then-write, a recorded key, or a native idempotent operation - the mechanism varies by system, and the production harness checklist works through the repeat classes in detail. What does not vary is the test: run the same instruction twice in a trial environment and count the effects. One effect passes. Two effects mean the action is not ready to run unattended, whatever its tier, because an ordinary timeout can now manufacture an incident.

• One action id per intended effect, generated before execution and used in the tool call, the log, and the prior-state record.
• A completion record written before the next step starts, so a resumed run can tell done from not done.
• A pre-execution check for an existing completion or an in-flight marker with the same key.
• Retries bounded and classified, so a permanent error is not retried into a second attempt at an action that already failed for a reason.
• A double-run test in the trial environment for every write action, with the effect count recorded next to its tier.

Approval gates that scale with the tier

A gate that treats every action alike will be tuned for the common case and wrong for the dangerous one. Scale the gate to the tier. Tier one actions run without approval, with the reversal path tested and the audit record written; sampling a few runs for review is usually enough. Tier two actions run with a preview and either a lightweight approval or a post-action review inside the undo window, depending on the priced cost of compensation. Tier three actions stop for a named human approver who sees the full arguments, the prior state, and the statement of what cannot be undone, and who approves that specific action rather than a batch of them.

• Tier one: no per-action gate. Controls are the tested reversal, the audit record, and periodic sampling. Adding approval here buys little and teaches approvers to click through, which weakens the gates that matter.
• Tier two: preview required, approval required above thresholds you set by amount, recipient count, or audience. Below the threshold, run and review inside the undo window while compensation is still cheap.
• Tier three: approval required every time, from a named role, showing arguments, prior state, and the no-return statement. No auto-approval on repetition, no approval carried over from a similar earlier action.
• Any tier: an action whose preview cannot be produced, whose prior state cannot be captured, or whose target changed since approval goes back to the gate. Approval attaches to an action as specified, not to the agent in general.

Approval quality is the weak point, and it degrades by volume. If approvers face dozens of low-risk prompts a day, attention per prompt falls, and the tier three prompt in the same queue gets the same hurried treatment. Keep the queue short by keeping tier one out of it entirely, batching tier two reviews where the priced risk allows, and reserving interruptive approval for tier three. When a tier three action is so frequent that the gate becomes routine, redesign the workflow instead of normalising the click: stage the work in tier one or two form, and let the human perform or release only the final step. The handoff guide on this site covers the human side of that split - who owns the decision, what context they receive, and how the transfer is recorded - and a reversibility plan should name that owner per tier three action rather than leaving it as whoever is around.

The undo window

Every action has a period during which reversal is still practical, and the plan should state it instead of leaving it to be discovered. For some actions the window is created deliberately: a send held in a queue for a short delay, an order staged before fulfilment, a change applied to a preview audience before general release. A holding delay is the strongest form of undo window because reversal inside it is prevention - the effect never lands. Use holds wherever the receiving process tolerates them, and size the hold to the review you actually perform in it. A hold nobody looks at is just latency.

For actions with no hold, the window is set by spread. State what closes it: a sync to a downstream system, a settlement time, a recipient opening a message, a retention job deleting prior state. Then align three things to that closing event. Detection has to happen inside the window, which means the run is reviewed or monitored before the window closes, not on a weekly schedule after it. Prior state has to survive at least until the window closes. And the person authorised to run the compensating action has to be reachable inside it. A window that closes at a nightly sync, paired with a review that happens weekly, is not a window at all; it is a date after which you will explain a problem you can no longer fix. Write the window per action in the checklist, in time or in the closing event, and treat a missed review inside an open window as an incident in miniature: close the gap in scheduling before widening anything.

What the audit record must contain

Reversal is usually performed later, by someone reconstructing what happened from the record. That sets the record's contents. A log line saying an update succeeded supports neither reversal nor an argument about whether reversal is needed. The record for each action needs to carry the inputs, the prior state, and the identifiers that connect the effect to its compensation. The error recovery guide on this site treats the run record as the basis for resuming work; for reversibility it is also the basis for unwinding work, and the fields below serve both.

• Action id and idempotency key, so the effect, its completion record, and any compensation all reference the same identifier.
• Run id, agent or workflow name, and the instruction or task reference that authorised the action.
• Timestamp of approval and of execution, with the approver identity for gated actions.
• Tool name and the full arguments as executed, redacted only for secrets, never for the values the reversal needs.
• Target identifier and the captured prior state, or a durable reference to where it is stored.
• Result as returned by the system, including external identifiers such as a transaction id, message id, or new version id.
• Tier assigned to the action, the undo window and its closing event, and the compensating action named in the plan.
• Reversal status: not needed, available until a stated time, performed with its own action id, or expired with the reason.

Two properties make this record usable rather than decorative. It is written at execution time by the system performing the action, not reconstructed afterwards from chat transcripts or summaries the agent wrote about itself. And it can be searched by action id, by target, and by run, because incidents arrive phrased as a customer, a record, or a payment - rarely as the identifier you filed the log under. Test the record the same way you test the reversal: pick a trial action at random and ask a teammate who did not run it to state, from the record alone, what happened, what the prior state was, and how they would reverse it. Any question they cannot answer is a field to add.

The pre-flight reversibility checklist

The checklist below is the asset to copy. One row per action the agent can take, filled in before that action is automated, and reviewed whenever a tool, a setting, or a workflow changes. The columns force the five decisions this guide covers: the tier, the prior-state capture, the compensating action, and the approver who matches the tier. An empty cell is a finding, not a detail to fill in later, because each empty cell names a reversal that currently depends on improvisation.

Action | Tier | Prior-state capture | Compensating action | Approver
Draft a customer email | 1 - freely reversible | Draft id and source notes | Delete or edit the draft | None - sampled review
Edit a versioned project file | 1 - freely reversible | Version id before the edit | Restore the prior version | None - sampled review
Send a customer email | 3 - irreversible | Final text and resolved recipient list | Correction email - cannot recall the original | Named approver per send
Update a customer record | 2 - reversible at a cost | Field values before the update | Restore prior values by record id | Review inside undo window
Issue a refund | 2 - reversible at a cost | Original transaction id and amount | Re-charge only with customer agreement | Approver above set threshold
Pay an invoice by wire | 3 - irreversible | Invoice, amount, destination as approved | Recovery request to receiving bank - not in your control | Named approver every time
Delete inactive records | 3 - irreversible | Full export stored outside the system | Restore from the export, if still retained | Named approver per batch
Publish a help-centre article | 2 - reversible at a cost | Prior version or unpublished state | Unpublish plus correction note if it was wrong | Preview approver

Fill in your own rows at the level of individual actions, not tools. One tool often spans all three tiers: a mail tool drafts at tier one, sends internally at tier two, and sends externally at tier three, and a single row for the tool would hide exactly the distinctions the gate needs. Expect the first pass to move a few actions you assumed were safe into tier two, usually where a sync, a notification, or a public copy sits between you and a clean restore. Those moves are the value of the exercise. Each one either earns a stronger control or gets redesigned into a staged form where the agent stops one step earlier, which is often the better outcome: a staged send with a human release is tier one preparation plus a manual tier three step, and it keeps the automation for everything except the moment of no return.

A worked example: staging a payment run

Consider a hypothetical workflow, invented to show the method: an agent that prepares a weekly payment run for a small business. The naive version reads approved invoices, pays each one, and reports a total. Tier the steps and the design changes. Reading invoices and matching them to records is read-only, outside the tiers entirely. Drafting the payment batch, with amounts and destinations filled in, is tier one: the batch can be discarded and nothing has moved. Checking the batch against invoice totals and flagging mismatches is also tier one, and it is where the agent earns its keep. Submitting the batch is tier three for wire payments and tier two, at best, for payment types with a working refund path, because fees, timing, and counterparty reliance differ by rail. So the submitted design splits there: the agent stages the batch, produces a preview showing each payment beside its invoice and the account details on file, captures the pre-run balances and the batch contents as prior state, and stops. A named approver reviews the preview and releases the batch. Each payment carries an action id and an idempotency key, so a resubmission of the batch after a network failure cannot pay an invoice twice.

Now run the failure that this design exists for. A supplier's bank details on an invoice differ from the details on file, and the agent, following the invoice, stages the new destination. The preview makes the difference visible in one line, because destination is shown beside the record value rather than buried in a total. The approver catches it, edits that line back to the verified destination, and releases. In the naive version the same error is discovered after settlement, the recovery is a request to a bank and a supplier, and the timeline is theirs. Nothing in the agent improved between the two versions. The classification, the preview, the capture, and the split at the irreversible step did all the work, and every one of those decisions was available before the first real run.

Where reversibility plans fail in practice

• Classifying the tool instead of the action, so one row hides a draft, a send, and a delete behind a single friendly name.
• Calling an action reversible because a reversal feature exists, without pricing the fees, delay, and residue the reversal leaves behind.
• Capturing prior state in the same place the action can overwrite, so the reversal input is destroyed by the event it was meant to repair.
• Writing compensating actions during an incident, when the identifiers, authority, and calm needed to write them well are all in short supply.
• Letting retries and resumes re-execute completed steps, doubling the effect before anyone starts reversing it.
• Flooding the approval queue with tier one prompts until approvers stop reading, then routing a tier three action through the same queue.
• Keeping prior state forever, or deleting it before the undo window closes. Both errors look tidy; both break the plan, one by exposure and one by absence.
• Treating a setting change - version history off, retention shortened, a hold removed - as routine maintenance when it silently reclassifies every action that depended on it.

Notice that none of these failures require a bad model or a wrong answer. Each one is a property of the workflow around the model, set at design time and visible in a design review. That is the encouraging reading of the list: the failures are cheap to prevent and expensive only when discovered late, which is the standard argument for doing this classification early and redoing it whenever the tool set changes.

How this fits with the rest of your controls

Reversibility is one layer among several, and it works best when it is kept distinct from its neighbours. The agent tool permissions guide decides which tools and scopes an agent may reach at all; the reversibility tier then decides, within that reach, which actions need preview, capture, and a gate. The production harness checklist audits the runtime those decisions run in - validation, timeouts, logs, resume behaviour - and a reversibility table gives that audit sharper questions to ask about write tools. The checklist before AI agent real work helps decide whether a task should be delegated in the first place; a task whose core action is tier three with no staging point is a strong candidate for staying manual, however well the agent performs it in trials. When something still goes wrong, the agent error recovery guide covers stopping, resuming, and cleaning up a failed run, and the agent handoff to human teams guide covers who takes over and with what context. Reversibility feeds both: the tier table tells recovery how much unwinding a failure needs, and the audit record is the context a human needs to take the reversal over without starting from a blank page.

Start small. Take the actions of one existing workflow, fill in the checklist, run the double-run and reversal tests on the tier one and two rows, and move one misclassified action to its proper gate. That single pass usually changes a workflow more than a month of general caution, because it replaces a feeling about risk with a table the team can argue with, test against, and update. Automation earns trust action by action. A reversibility plan is how you know, for each action, exactly what that trust costs if it is misplaced - and how you get back.