Undo & Reversibility

Sort by cost of reversal, not by scariness.

Take the tool list from a shipped agent and mark each entry with what an approval gate is actually buying. Deleting a row from a table you snapshot hourly is loud and cheap. Sending an email is quiet and, once it lands in somebody's inbox, permanent. Most teams gate the first and not the second, because danger is judged by how destructive the verb sounds rather than by whether the effect can be withdrawn.

• Reversibility is a property of the effect, not of the verb. delete_draft and delete_customer share a word and nothing else. Two tools with the same name in different systems belong in different tiers.
• The system boundary is the cliff edge. Anything that stays inside infrastructure you control is usually recoverable. Anything that crosses out — an email, a Slack post, a webhook, a payment, a public API write, a notification to a third party — leaves a copy you cannot reach. That boundary, not the destructiveness of the operation, is where the tiers actually separate.
• Autonomy is priced in reversal cost. The autonomy ladder is usually presented as a trust question. It is cheaper to treat it as an engineering one: an agent may act unsupervised exactly as far as its actions can be withdrawn at acceptable cost. Buy reversibility for a tool and you have bought a rung, without asking anyone to trust the model more.
• The irreversible set is smaller than it looks, and it never gets audited. Most teams can name three irreversible actions in their agent. Most agents have a dozen — usually hiding behind a generic HTTP tool, an MCP server nobody read the tool list of, or a shell that can do anything. Enumerate it once, in writing, per tool.

Three grades of undo, and the fourth that is not one.

"Undo" is one word covering mechanisms with very different guarantees. Naming them separately keeps you from promising the strongest and shipping the weakest.

• Rollback — the prior state is restored exactly. Available when you own the store and captured a snapshot or a versioned write. This is the only grade where "undone" is literally true.
• Compensation — a second action offsets the first. The refund against the charge, the reverting commit, the follow-up correction. The state is acceptable again; the history shows both events, and any observer in between saw the intermediate state. Most real-world undo is this, and it is the grade to design for.
• Mitigation — you cannot offset it, only reduce the damage. Retracting a message people have already read, apologising for a wrong email, notifying a customer that an incorrect statement was sent. Mitigation is a communications plan wearing an engineering label.
• None — the action is final. Money to an external account, a deletion past its retention window, an irrevocable API call, anything with a legal effect. This tier must be explicitly enumerated rather than discovered.

The design consequence is direct: reserve human approval for grades three and four. Grades one and two do not need a gate, they need a visible, working undo affordance — which is a much cheaper thing to build and a much better thing to use.

Reversibility has a half-life, and observers are what kills it.

The mistake that survives even a careful tiering exercise is treating reversibility as a fixed attribute. It is a decaying one. A Slack message deleted three seconds after posting is a rollback. The same deletion four minutes later, after two people have read it and one has replied, is mitigation. Nothing about the API changed; the audience did.

• The clock starts at the effect, not at the call. An email queued for delivery is reversible until it is delivered. A record written is reversible until something else reads it. Instrument the moment of exposure, because that is when your tier changes.
• Buy time deliberately. A thirty-second hold on outbound actions is the highest-leverage single change in this entire playbook. It converts a whole class of grade-three actions into grade-one, costs the user nothing they notice, and gives both the human and your own guardrails a window to intervene. Every mail client shipped this decades ago; agent products keep forgetting it.
• Batch the hold, do not stack it. Ten held actions with ten separate timers produce ten notifications and one annoyed user. Hold the run's outbound effects together and present them as one reviewable set, in the spirit of progressive disclosure.
• Watch for the second observer you forgot. Webhooks, sync jobs, search indexers, analytics pipelines and other agents all read your writes. An action can be socially reversible and technically irreversible because a downstream consumer already fired — the failure mode described in idempotency and retries, arriving from the other direction.

Build the mechanism, and make each tool declare its own.

Reversibility is not a property you can add at the harness layer, because the harness does not know what a tool did. It has to be declared by the tool and carried by the run.

• Every mutating tool returns a revert handle. Not a boolean "reversible: true" but the actual thing needed to undo it: the prior version id, the message timestamp, the transaction reference, the snapshot key. A tool that mutates and returns only "ok" has made your undo impossible at the moment it was cheapest to preserve. This belongs in the contract, alongside the rules in tool schemas and contracts.
• Prefer staged effects to direct ones. Draft rather than send, branch rather than push, proposed-change rather than applied-change. Staging turns approval from an interruption into an artifact the human can read at their own pace — the single biggest reason coding agents feel safe at autonomy levels that would be alarming elsewhere.
• Snapshot before the write, in the same step as the write. A snapshot taken by a nightly job is a backup, not an undo. Undo needs the prior state captured at the moment of change and addressable by run id.
• Make the revert path a tool the agent can call. If undo only exists as an operator runbook, it will not be used during the ninety seconds when it would have helped. Give the agent — and the kill switch, and the human — the same callable revert. See kill switches for the stop half of this pair; undo is the part that runs after the stop.
• Test the revert path on the same schedule as the forward path. Untested undo is the disaster-recovery plan of agent design: everyone has one, and it first executes during an incident. A weekly job that performs an action and reverts it is cheap and finds the broken handles before your users do.

The interface: undo has to be reachable by the person who is surprised.

A working revert path that nobody can find is not reversibility, it is a support ticket. The UX requirement is narrow and specific.

• Undo lives next to the effect, not in a settings page. On the message that announced the action, in the artifact the action produced, in the notification the user actually received. One click, no navigation, no administrator.
• Say what will happen, in the grade's honest language. "Undo" for a rollback. "Send a correction" for a compensation. "This cannot be undone — here is who to contact" for mitigation. A button labelled "Undo" that quietly performs a compensation is how users learn not to believe your interface.
• Show the window, and let it be paused. If the action goes out in thirty seconds, show the thirty seconds counting. A visible timer is more reassuring than a confirmation dialog and requires no decision from a person who has nothing to object to.
• Stop paying for confirmations you can retire. Every gate you remove because the action became reversible is attention returned to the user, and attention is the scarce resource that makes the remaining gates work. A user who clicks through nine harmless dialogs a day will click through the tenth — this is the mechanism behind the fatigue documented in approval and confirmation UX, and reversibility is the only cure that does not rely on people being careful.
• In a shared space, undo needs the same attribution as the act. Who reverted what, visible to everyone who saw the original — otherwise the room remembers the action and not the correction. See shared and multi-user agents.

What to measure, and what the numbers will tell you.

Reversibility is unusual among UX properties in that it produces clean quantitative signals, and those signals are the evidence you need to raise autonomy without arguing about it.

• Coverage: share of mutating tool calls with a working revert handle. The single number to put on the wall. It should climb, and every new tool should be born with one.
• Undo rate per tool. A tool users revert 15% of the time is telling you about a prompt or a schema defect, not about undo. High undo rate is a quality signal pointing somewhere else entirely.
• Time-to-undo distribution. If most reverts happen within a minute, your hold window is correctly sized. If they cluster at hours, your users are discovering errors from downstream effects and your notifications are late.
• Gates removed per quarter. Track it as a product metric. A confirmation dialog retired because the action became reversible is a real improvement; one retired because it was annoying is a regression wearing the same clothes.
• Failed reverts. Rare, and each one is an incident: the user was promised something the system could not deliver. Treat them the way incident response for agents treats a silent failure, because that is what it is.

Related: progressive autonomy for how to spend the rungs reversibility buys you, designing for failure for what to show when the revert itself fails, durable state and resumability for the state machinery underneath, and decision receipts for the record that makes a revert reconstructable weeks later.