D1 · Agentic Architecture › Cluster 5 · Autonomy

5.4 · Reversibility as a Design Axis

Auto-run the reversible · gate the irreversible

CONCEPT Sort actions by "can I undo this?"

Reversibility is a first-class design axis for agent tools. Before wiring a tool into the loop, ask one question: if the agent does this wrong, can I cheaply undo it? The answer decides how much autonomy the tool gets. Reversible actions — read, glob, grep — can auto-run, because a mistake costs nothing but a wasted turn. Hard-to-reverse actions — send_email, delete, external POST, payments — should be gated behind confirmation (5.2), because a mistake is expensive or permanent.

ActionReversible?Blast radius on errorDesign decision
read_file / glob / grepYes — no state change~None🟢 Auto-run (fully autonomous)
list_dir / query (SELECT)Yes — read-only~None🟢 Auto-run
write_file (versioned)Mostly — undo via VCSLow–medium🔵 Auto with audit, or light gate
send_emailNo — it's out the doorHigh (reputational)🟠 Gate — human confirms
delete / DROPNo — data goneHigh🟠 Gate — human confirms
external POST / charge_cardNo — side effect on othersHighest (money, third parties)🔴 Gate — strong confirm + audit
🔑 Reversibility maps directly onto autonomy (5.1) and gating (5.2): the more irreversible an action, the more it should be gated and the less autonomy it earns.

CONCEPT Promote to a dedicated tool to gain a hook

Here's the architectural lever the exam loves: a generic bash tool hides everything. If the agent runs bash("rm -rf …"), your harness sees only "a bash call" — it can't tell a reversible ls from an irreversible rm. By promoting a dangerous action from a generic bash call to a dedicated tool (say delete_file(path)), you give your harness a typed hook it can individually gate, validate, and audit. The dedicated tool is the seam that makes fine-grained permission control possible.

Design move: don't expose raw bash for irreversible operations. Give each one a named, typed tool so the gate (5.2) can target it precisely and the audit log can name it.

DIAGRAM Reversibility routes the action

flowchart TD A["Model requests an action"] --> Q{"Reversible?"} Q -->|"yes: read / glob / grep"| AUTO["🟢 Auto-run
cheap to undo"] Q -->|"no: send / delete / POST / pay"| DED{"Dedicated typed tool?"} DED -->|"yes"| GATE["🟠 Gate: confirm + audit
(typed hook)"] DED -->|"no — hidden in bash"| BLIND["🔴 Blind spot:
harness can't gate it"] BLIND -.->|"promote to a
dedicated tool"| GATE classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class AUTO ok; class GATE gate; class BLIND bad;

CODE Routing by reversibility

Classify each tool by reversibility, auto-run the reversible, gate the rest — and note how the dedicated delete_file tool gives the harness a named hook a raw bash call never would.

# Reversible actions get a typed, dedicated tool AND auto-run.
REVERSIBLE = {"read_file", "glob", "grep", "list_dir"}

# Irreversible actions are ALSO promoted to dedicated tools — so the
# harness has a typed hook to gate & audit, instead of hiding them in bash.
IRREVERSIBLE = {"send_email", "delete_file", "http_post", "charge_card"}

def dispatch(block):
    name, args = block.name, block.input
    if name in REVERSIBLE:
        return run_tool(name, args)                 # auto — cheap to undo
    if name in IRREVERSIBLE:
        audit_log(name, args)                        # typed hook → record it
        if not confirm(f"Irreversible: {name}({args}). Approve?"):
            return f"DENIED: '{name}' is irreversible; approval refused."
        return run_tool(name, args)
    return f"DENIED: unknown tool '{name}' (deny-by-default)."  # safest default

TRADE-OFFS Generic bash vs. dedicated tools

✅ Dedicated typed tools

  • Per-action gating, validation, and audit
  • Harness can see & name what's happening
  • Reversibility can be enforced at the seam

⚠️ Generic bash for everything

  • Flexible, fewer tools to define
  • But: harness can't distinguish safe from destructive
  • No hook to gate rm vs. ls → blind spot
Keep bash for open-ended reversible exploration; carve irreversible operations out into dedicated tools so each gets its own gate and audit entry.

EXAM TRAPS

Trap: "Gate every tool." → Gating reversible reads wastes human time. Gate by reversibility: auto-run read/glob/grep, gate send/delete/POST/pay.
Trap: Running irreversible actions through a generic bash tool. → The harness can't gate what it can't distinguish. Promote to a dedicated tool to get a typed, gate-able, auditable hook.
Trap: Confusing "reversible" with "low-stakes." → Reversibility is about undo cost, not importance. A read of secret data may be sensitive yet reversible; a tiny payment is irreversible. Route by undo-ability.
Trap: Forgetting the audit trail. → Even when a human approves an irreversible action, the dedicated tool should log it — approval without a record isn't accountable.

PRACTICE

Q1 · Which of read_file, delete_file, grep, charge_card can auto-run, and why?

read_file and grep — they're reversible (no state change), so a wrong call costs only a turn. delete_file and charge_card are irreversible and must be gated behind human confirmation.

Q2 · Why promote a dangerous bash call into a dedicated tool?

It gives the harness a typed hook: the harness sees a named delete_file(path) instead of an opaque bash string, so it can gate, validate, and audit that specific action. A generic bash tool is a blind spot the gate can't target.

Q3 · How does reversibility connect to autonomy (5.1) and gating (5.2)?

It's the classifier that drives both: reversible → high autonomy, auto-run; irreversible → low autonomy, gated behind a confirmation. Reversibility is the underlying axis that tells you which actions deserve a human in the loop.