[FEATURE] Effect-based approval for Bash-mediated writes: run against staging, approve the computed diff

Preflight Checklist

• [ ] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

The permission system gates the Edit/Write tools with a reviewable diff — but any Bash-mediated write (sed -i, python3 - <<EOF, generated one-off scripts, external CLIs) bypasses that review entirely. #58435 documents the asymmetry: the Edit gate is "trivially circumventable from Bash, which makes its protective value low while the friction is high". Users are left approving Bash commands based on the agent's description of intent, which can be wrong or influenced by injected content the agent read.

The deeper issue: for arbitrary commands, judging intent (reading the command) is undecidable and spoofable; judging the effect (the resulting diff) is a deterministic check.

Proposed Solution

An opt-in permission mode for write-capable Bash commands, per rule or per directory:

1. Execute the command against a staging copy of the workspace (git worktree or overlayfs — the harness already manages worktrees).
2. Compute the effect: files touched/created/deleted, line counts.
3. Deterministically check the effect against the permission scope (path globs; deny-list like .env, .git/** always wins; volume budget).
4. In scope → apply atomically to the real tree. Out of scope → show the computed diff (not the command, not the agent's claim) in the standard approval prompt.

Sketch:

{ "permissions": { "effectGate": { "Bash": { "mode": "staging-diff", "allow": ["src/**"], "deny": [".env", ".git/**"], "maxFiles": 20 } } } }

Notes: read-only commands are unaffected (no writes in staging → no gate). Commands with meaningful side effects outside the FS (network, DB) are out of scope for this request — FS effect is the 90% case. This composes with, rather than replaces, the sandbox: sandbox constrains where writes can land; this reviews what they are.

Alternatives considered

• Deny Bash writes and force the Edit tool: breaks legitimate codemods/scripts; models are RL-tuned to use Bash for bulk edits.
• LLM review of the command text: probabilistic, spoofable, judged intent instead of effect.
• Our current workaround: hook-driven audit after the turn plus git discipline (branch + commit-before-apply) — catches damage late instead of preventing it. Reference: https://gist.github.com/brunox64/ffbdfb4f78fe928fce31c866c9d83aad.

Evidence of demand

#58435 (gate asymmetry, same Bash-bypass pattern in the background-session worktree gate), #54758 / #31888 (users asking to see the diff before approving on other surfaces), #64783 (approve-before-commit expectations).

Environment

Claude Code 2.1.248, Linux x86_64