feat(agentfw): daemon + Claude Code hook collector (phase 09)

[carbon-evolution]

Phase 09 turns the phase-08 library into a running daemon wired into Claude Code's native hooks.

It ships in shadow mode. Every verdict is computed and written to the audit log; nothing is blocked until enforce: true is set deliberately. A lab measurement found 7 of 15 benign follow-up commands tainting — learning the real rate by having live sessions interrupted is the expensive way.

Verified end to end

The same attack, run twice. Enforcing:

{"event":"pre_tool_use","rule":"deny-tainted-privilege","verdict":"deny","shadow":false,
 "taint":{"source":"network:blog.example.com","seq":1},
 "egress_hosts":["exfil.example.com"],"tool":"Bash"}

Shadow mode:

{"event":"pre_tool_use","rule":"deny-tainted-privilege","verdict":"deny","shadow":true,
 "taint":{"source":"network:blog.example.com","seq":1},
 "egress_hosts":["exfil.example.com"],"tool":"Bash"}

A poisoned page arrives via WebFetch at seq 1; the tracker links a later Bash command back to it; the egress host is extracted; the rule fires. Enforcing returns deny. Shadow returns nothing while logging the identical would-have-been verdict. That pair is the phase.

The correction this phase exists around

permissionDecision has four values, not three. allow approves a call into the normal permission flow; defer leaves the operator's own rules to decide. Mapping our Allow verdict onto allow would auto-approve tool calls the operator would otherwise have been prompted about — installing a security tool would weaken existing protection. Allow maps to defer, pinned by a test asserting both the positive and the negative.

A measurement that settled the architecture

The docs describe failure semantics for command hooks; we chose http hooks. Measured with the endpoint pointed at a dead port: the tool call proceeds after honouring the timeout (real 7.39s against a 5s timeout). Fails open, does not hang — so no shim binary and no Unix socket are needed.

Cost, recorded rather than glossed: a stopped daemon charges the full timeout per tool call. Nothing breaks, but it reads as "Claude Code is slow" rather than "agentfw isn't running", so install and the README both say so explicitly.

What's here

crates/agentfw — the only crate doing I/O for the agent layer. It maps, calls, records, and translates; it decides nothing. All verdict logic stays in crates/agent.

• agentfw serve — axum daemon, loopback-only, bearer-token authenticated with constant-time comparison
• agentfw install — prints the hook block for all five events; the token goes in by env var and is never written to the settings file
• agentfw replay — the interruption rate and which rules fired, which is what decides whether enforcement is safe

Defects review found in already-green code

• Token file was written then chmod'd, leaving a window at the process umask. Now created 0600.
• session_id was required to be present but not non-empty; an empty one would have collapsed every session into one shared taint bucket.
• A relative file_path yielded LocalSystem instead of LocalProject, mislabelling the audit log that phases 10 and 12 both depend on.
• The audit log claimed truncated: false when content had in fact been cut.
• The audit event name was derived from Rust's Debug, making a forensic log's on-disk schema depend on variant names. Now an explicit mapping.

Known scope limits, stated rather than hidden

• Subagent authority containment is not covered. No hook exposes a subagent's granted tools, so Authority stays dormant until the API/MCP collectors in phase 11.
• No result rewriting. updatedToolOutput exists and is deliberately unused; this phase detects and gates, it does not alter what the model reads.
• install prints only. It never edits your settings file.

Verification

• 336 workspace tests passing, 0 failing (87 new in agentfw; 249 pre-existing, none broken)
• cargo clippy --workspace --all-targets -- -D warnings clean
• cargo fmt --all --check clean
• cargo check --all --all-features clean, including the candle/ML path
• No changes to core, proxy, bench, or agent public APIs

Design: docs/superpowers/specs/2026-07-29-agent-firewall-09-daemon-hooks-design.md
Plan: docs/superpowers/plans/2026-07-29-agent-firewall-09-daemon-hooks.md

🤖 Generated with Claude Code