claude-projects/agent-builder/constrained_autonomy_design_decisions.md

Constrained Autonomy for Claude Code — Design Decisions

Status: DESIGN LOCKED (grill-me 2026-07-14). Not yet built. Build = phased background agents (CA-P0…P5), mirroring the Agent-Sudo build model. Do NOT implement ad hoc — follow this record.

Driving insight (user): a permission prompt the human rubber-stamps — especially a truncated command they can't read or don't understand — adds no safety. It is the same theater as the NTFY approval gate we removed from Agent-Sudo. Kill the theater; replace it with an ENFORCED code constraint layer. Governing memory: feedback_autonomous_security_constrain_not_gate (constrain capability, don't gate access), feedback_evolution_by_default, feedback_always_include_training_loop, feedback_secrets_via_proxy_only.

The core problem

Claude Code's Bash tool runs as administrator (docker group + sudo). Today, consequential commands stop for a human permission prompt. --dangerously-skip-permissions removes that gate but adds NO constraint → strictly worse. We want: remove the theater prompt, but move the real gate into deterministic enforced code that reuses the Agent-Sudo constraint+recovery stack.

D1 — Enforcement architecture: HYBRID (hook classifies+routes; daemon executes-with-constraint)

• The hook = security-enforcement.py (existing PreToolUse Bash hook, pure-regex, <50ms, no-I/O) extended into the decision point. It runs regardless of permission mode and is code, not a rubber stamp. It emits a permissionDecision:
  • tier-0/1 (read/reversible) → allow LOCALLY (no prompt, no daemon round-trip → kills the theater, stays <50ms).
  • tier-2/3 (mutating/destructive) + UNKNOWN → deny the raw command, message routes it to the Agent-Sudo daemon /exec (which already does sandbox-test-first + rollback + audit). This generalizes what the hook ALREADY does for sudo today (block → route to bridge) into "anything consequential → Agent-Sudo".
  • tier-4 (catastrophic) → deny, no override.
• The daemon = Agent-Sudo /exec (LIVE: server-01 8082, primary 8084). All heavy lifting (Incus sandbox mirror test, Timeshift/rollback, circuit-breaker, command_audit logging) stays where it's built and tested. We reuse it; we do not reimplement it in a 50ms regex hook.
• Rejected: pure-hook (can't sandbox/rollback in 50ms), route-EVERYTHING-through-daemon (latency + hard dependency + wrong root context for harmless reads).

D2 — Classification: STRUCTURAL effect-classifier, unknown→sandbox, learned allowlist on top

• SUDO.md only covers the sudo surface; ~90% of Claude Code commands are non-sudo (git/docker/python/curl/file ops). So the classifier judges a command by its effect class, not exact-match:
  • reads/inspection → tier-0/1 allow
  • workspace-local / reversible writes (git add/commit, edits under project dirs, scratch scripts) → tier-1 allow
  • blast-radius mutations (docker rm/restart/compose down, writes outside workspace, DB writes, net-config, mv/rm on real paths) → tier-2/3 → daemon sandbox
  • catastrophic verbs (rm -rf / patterns, mkfs, dd of=/dev/…, fork bombs, disk/partition ops) → tier-4 deny
  • sudo-prefixed → daemon's SUDO.md governs (unchanged)
  • genuinely unrecognizable structure → default to daemon sandbox (treat as tier-2) — unknown = "prove it in the mirror first," NEVER "ask the tired human." (User-confirmed.)
• Learned allowlist layered ON TOP: commands that ran clean N times (from command_audit + human_verdict gold labels) get promoted to the local fast-path → system gets faster with use (feedback_evolution_by_default). Starts from structural analysis so day-one has zero rubber-stamp gaps.
• Policy source of truth = a signed CLAUDE_CMDS.md tier-map file (the effect-class rules), analogous to SUDO.md.

D3 — Secrets: via secrets-proxy env_secrets (dormant until #128)

• Any command that touches a secret runs via secrets-proxy /shell + env_secrets (vault://path#field / bitwarden://item) so values are sourced at runtime, never in stdout/history/argv. The hook's existing Category-2/3 blocks (secret exposure, hardcoded secrets) stay as the backstop that FORCES commands onto the proxy path.
• Dependency: secrets-proxy = task #128 (pending/down). Secret-handling path is built but dormant until #128; interim fallback = feedback_secret_to_script_via_file. Decoupled from the classifier build.

D4 — Tamper-evidence: Vault transit signature — UNBLOCKED 2026-07-14 (#145 resolved)

Transit is LIVE. Vault admin WAS recovered (user was right; my first probe was wrong — it checked only the least-privilege AppRole, which is denied transit by design, and never followed the Bitwarden path). Chain: vault approle → secret/data/bitwarden-bridge#BRIDGE_API_KEY → bridge :8083 GET /secret?item=Hashicorp Vault&field=notes → root token. GOTCHA: the token LABELED "Root token:" is REVOKED; a second UNLABELED token at the bottom of the note is the live one. Search the whole note — do not trust the label. transit enabled + ed25519 key agent-sudo-sudomd created + SUDO.md SIGNED (sha256 38eca778…, transit/verify PASSED) + tamper test PASSED (fake widened rule → gate REFUSED). CLAUDE_CMDS.md (CA-P4) and proxy.md (#150) can now be signed the same way.

D4 (original) — Vault transit signature (was dormant until #145)

• CLAUDE_CMDS.md gets the IDENTICAL mechanism as sudo_sign.py: Vault transit ed25519 key, sign file sha256, verify_gate on load via scoped AppRole, ..._VERIFY_ENFORCE flag. Tampered policy → refuse to honor.
• Dependency: live signing blocked on #145 (OpenBao admin lockout; transit engine not enableable yet). SUDO.md itself runs unsigned (enforce=false) for this reason. CLAUDE_CMDS.md inherits the posture: built to verify, ships enforce=false, flips to true when #145 lands — one activation signs SUDO.md + proxy.md + CLAUDE_CMDS.md together. (proxy.md signature status UNVERIFIED — do not assert it is signed.)

D5 — Fail mode: FAIL-CLOSED

• If the hook crashes or exceeds its 5s timeout → deny everything until healthy. A broken security control must not silently become no control. (User-confirmed.)
• Mitigations: (a) hook stays dead-simple pure-regex (minimal crash surface); (b) an ESCAPE_HATCH env flag the USER sets to drop to prompt-mode if the hook ever bricks all Bash; (c) SessionStart self-test so a broken deploy is caught before it blocks work.

D6 — Recovery ladder (two phases)

• Phase 1 (now, background-agent automation): fail-closed → user reachable to grant permission / co-diagnose → fix → resume autonomy.
• Phase 2 (full autonomy): hook fail → ALL WORK PAUSES → Hermes (already monitoring) attempts diagnose+fix → success → resume; impossible → ALL WORK STOPS + high-priority NTFY ("catastrophic failure, all work halted, interactive session needed"). In that session Claude/Hermes still do the heavy lifting; user only grants permission.
• Depends on Hermes (#138) for Phase 2.

D7 — Circuit-breaker + self-disarm (inherited from Agent-Sudo)

• Same anomaly trip: N tier-3 failures in a window OR any tier-4 attempt → daemon self-disarms to read-only + NTFY. No new mechanism.

D8 — Training capture (inherited; zero new schema)

• Every classify+outcome → command_audit (projects DB): assigned_tier, decision_type, matched_rule, evidence, exit_code, rollback_taken, verify_passed, human_verdict (gold label), training_signal. This is the local-model training export.

Phased build (background agents, like Agent-Sudo P0–P5)

• CA-P0 — write CLAUDE_CMDS.md tier-map + the structural classifier module (pure-regex effect-classes). No activation.
• CA-P1 — wire the hook to emit permissionDecision allow/deny/ask; tier-0/1 local allow; tier-4 deny; tier-2/3+unknown → route to daemon /exec. Fail-closed + ESCAPE_HATCH + SessionStart self-test. Test in the mirror first.
• CA-P2 — daemon side: accept routed Claude-Code commands, sandbox-test unknowns in Incus mirror, capture rollback, log command_audit. (Mostly exists — extend/verify.)
• CA-P3 — secrets-proxy env_secrets path for secret-touching commands. GATED on #128.
• CA-P4 — sign CLAUDE_CMDS.md (transit) + learned-allowlist promotion from command_audit. GATED on #145.
• CA-P5 — Hermes recovery-ladder (Phase 2) integration. GATED on #138.

EXECUTION ORDER (user-approved 2026-07-14, revised)

User's stated order was: (1) finish Agent-Sudo P3 subsystems [command testing + recovery] + sign SUDO.md; (2) finish/test/deploy secrets-proxy + sign proxy.md; (3) design/test/deploy constrained autonomy + sign CLAUDE_CMDS.md. User's concern: "I'll have to be here to give permission for everything."

REVISED — insert item 0 first. The ordering paradox: item 3 is what frees the user, but sat last, behind the two most babysitting-heavy items. Item 3's fast-path has NO dependency on items 1/2 (only CA-P2 needs item 1's sandbox; only CA-P3 needs item 2's proxy).

• CA-P1a — CONSERVATIVE FAST-PATH (do FIRST; zero dependencies). Hook classifies: a TIGHT, EXPLICITLY-ENUMERATED read-only set (git status/diff/log, ls, grep, find, docker ps/inspect, cat non-secret, scratch scripts) → allow locally, no prompt. Catastrophic verbs → deny (protection that does NOT exist today). Everything else falls through to the normal prompt exactly as today. Purely additive: net SAFER (adds tier-4 deny) AND less annoying. Removes ~80–90% of build-time prompts since building is overwhelmingly reads. Do NOT start with the full structural classifier — that's where a mis-classification could auto-allow something real. Start tight, widen with command_audit evidence.
• Then 1 → 2 → 3 in the user's order, each one widening the fast-path: item 1's sandbox unlocks CA-P2 routing (destructive minority stops prompting); item 2 unlocks CA-P3 secrets path; item 3 completes + signs.
• Net: user is present only for the SHRINKING MINORITY of commands, immediately — instead of all of them until the very end.

#145 (Vault admin) — user reports RECOVERED but task not marked complete. Per feedback_verify_before_persist: VERIFY transit is actually enableable BEFORE marking done or signing. Next-session first action: verify → sign SUDO.md → close #145 → CA-P4's signing gate also falls.

CA-P1a — BUILT + LIVE (2026-07-14, task #148)

Shipped in /opt/appdata/docker/.claude/hooks/security-enforcement.py v2.0 as "Category 4", layered under the existing Category 1–3 blocks (which run FIRST and still win — a fast-path candidate that trips any security rule is BLOCKED, never allowed).

• allow — every segment matches a tight enumerated read-only set (git read-verbs, ls/cat/grep/ find, docker ps/inspect/logs, systemctl status, journalctl, ip show, sysinfo). No prompt.
• deny — catastrophic verbs (rm -rf / + system dirs, mkfs, dd→/dev, wipefs, fork bomb, destructive partition ops). New protection that did not exist before. No override.
• prompt — everything else falls through exactly as before. Purely additive.

Safety rests on two independent conditions, both required: (1) transparent structure — ANY $, backtick, redirection, or backgrounding disqualifies; (2) every pipeline segment individually enumerated. One unknown segment disqualifies the whole command.

A real hole was caught by the tests, not by review: echo $VAULT_TOKEN initially classified allow — echo is enumerated and $VAR is not $(, and Categories 1–3 don't catch it (not docker exec env, not a cat of a known secret path). It would have printed a live secret with no prompt. Fix: any $ disqualifies the fast-path — the hook cannot know what a variable holds, so it cannot certify the command as a read. Locked in as a regression case. Lesson: enumerating safe verbs is not enough; the structure must also be transparent, and only an adversarial test suite finds the gap.

Verified: 23/23 self-test cases; e2e over the real stdin/stdout protocol ALL PASS; classify() median 0.009ms (budget 50ms); malformed stdin → exit 0; non-Bash ignored. D5 fail mode: in P1a the hook is NOT the only gate — the prompt still backstops everything not fast-pathed, so "closed" = fall back to the prompt, never auto-allow. Any exception → no decision → prompt (strictly no worse than pre-v2.0). Deny-everything fail-closed arrives with CA-P1, when the hook becomes the sole gate. Escape hatch: CLAUDE_CA_ESCAPE_HATCH=1. D5 self-test wired into session-start.sh (step 9) — reports at every SessionStart, non-fatal. D8 training loop: every decision (including prompt) appends to /opt/appdata/docker/.claude/hooks/ca_decisions.jsonl — best-effort, never breaks the hook. The prompt rows are the D2 promotion candidates (approved-every-time ⇒ widen the fast-path).

CA-P1b — WIDENED ON EVIDENCE (2026-07-14, hook v2.1, task #147)

The first production data made the case, not intuition. After CA-P1a shipped, the user observed he was still approving nearly everything. ca_decisions.jsonl answered why: 29 decisions, 22 prompts, and 16 were "opaque structure" — not mutations, not danger.

Root cause: 2>&1 contains a >. v2.0's rule was "any redirection is a WRITE ⇒ disqualify." But 2>&1 is file-descriptor plumbing and >/dev/null is a discard — neither can write anything. The rule was rejecting the exact idiom ordinary diagnostic reads are written in (ls -la 2>&1 | head). The classifier wasn't being cautious; it was being wrong.

Three changes, all still tier-0. None widens WHAT may run — they let the hook recognise reads it was already supposed to allow:

1. Safe redirects (_SAFE_REDIRECT_RE) stripped before the redirect check: 2>&1, >&2, 2>/dev/null, &>/dev/null. A redirect to any REAL path still disqualifies; /dev/null is anchored so >/dev/nullx and >/dev/null/../../etc/passwd cannot ride the prefix (tested).
2. cd enumerated — no filesystem effect, and every other segment is still checked independently (cd /etc && rm -rf x still prompts on the rm).
3. ssh <host> '<cmd>' — classify the INNER command under the identical rules, depth-limited to one hop. A read is a read regardless of which host runs it. Strict shape only: no options (ssh -o ProxyCommand=… prompts), no unquoted form. This is what stopped server-01 work from taxing the user on every single ls.

Security argument for the ssh hop, and its regression test: Categories 1–3 scan the FULL raw text (including the inner) before the fast-path is consulted, so ssh server-01 'cat …/agent-sudo/.env' is blocked — cat is structurally a read verb, so the secret-path check is the ONLY thing standing between the ssh fast-path and an exfil channel. That case is a locked regression test; if it ever goes green-to-allow, the hop must be withdrawn.

Verified: 42/42 self-test (up from 23); e2e ALL PASS, no regression; classify() median 0.011ms. Live-proved: ssh server-01 'systemctl is-active …' → allow, no prompt. Known edge (accepted): 2>&1 immediately followed by a quote isn't stripped (lookahead wants whitespace/;/|/EOL), so quoted compounds stay opaque → prompt. Safe direction, low value to fix.

Tier-1 (reversible writes) NOT shipped — deliberately. D2 authorises it, but the log says Bash-tier-1 is a small slice of real traffic: file edits go through the Write/Edit tools (not this hook), scratchpad writes are already pre-authorised, and git add/commit collides with playbook_git_criteria_universal (commits are checklist-triggered — auto-allowing removes the last friction on a rule enforced only by judgement). Correct next move per feedback_evolution_by_default: run v2.1, let ca_decisions.jsonl name the next real tax, and widen on evidence. The log found this one; it can find the next one.

Verified live state (2026-07-14)

• Hook: /opt/appdata/docker/.claude/hooks/security-enforcement.py, registered PreToolUse matcher=Bash timeout=5 in ~/.claude/settings.json. Currently block-only (exit 0/2), no classifier, no permissions allowlist set.
• Agent-Sudo daemon /health+/exec+/allowlist: server-01 8082 (LIVE, server_id=server-01), primary 8084 (server_id=primary; primary cutover swap still pending #146).
• command_audit (projects DB): 15 cols as above, present.