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.
| Action | Reversible? | Blast radius on error | Design decision |
|---|---|---|---|
read_file / glob / grep | Yes — no state change | ~None | 🟢 Auto-run (fully autonomous) |
list_dir / query (SELECT) | Yes — read-only | ~None | 🟢 Auto-run |
write_file (versioned) | Mostly — undo via VCS | Low–medium | 🔵 Auto with audit, or light gate |
send_email | No — it's out the door | High (reputational) | 🟠 Gate — human confirms |
delete / DROP | No — data gone | High | 🟠 Gate — human confirms |
external POST / charge_card | No — side effect on others | Highest (money, third parties) | 🔴 Gate — strong confirm + audit |
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.
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
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
rmvs.ls→ blind spot
bash for open-ended reversible exploration; carve irreversible
operations out into dedicated tools so each gets its own gate and audit entry.EXAM TRAPS
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.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.