[bar-capsule]

Stacked on #488. Next: #495. The full stack is listed in #22.

What changed

Rock's 31 October review, asks 1 to 10 (ask 3 is in #488):

1. A gate hook that fails blocks the action, an exception that escapes is denied, and a bad ACS_HANDSHAKE_TIMEOUT_SECONDS falls back to 5 seconds with an audit record.
2. Before signing, every step replaces what RFC 8785 cannot encode (a lone surrogate becomes U+FFFD, an integer past 2^53 - 1 becomes a string), so the Guardian sees it. A step that still can't be signed is denied on a gate and withheld on a result.
3. Claude Code sends agentResponse with the model's reply, from Stop.
4. Tool output the Guardian denies or modifies is kept from the model: in Claude Code for every tool, in the shape of its own tool_response, and in Cursor for MCP results through updated_mcp_tool_output.
5. On allow, Claude Code prints nothing and Cursor answers {}, so each host's own permission prompt, and Cursor's sandbox, still apply.
6. NAT applies MODIFY in the slot NAT reads, only to fields the input declares (a scalar input included), signs values in JSON form, withholds output the Guardian did not release, and denies any other MODIFY as modify_unsupported. Tests drive allow, deny and modify through NAT's FunctionMiddlewareChain.
7. Cursor denies ask and defer on preToolUse with an audit line.
8. The wire tools quote every value and keep the settings file's link and mode; backups are 0600 with any inline secret redacted, and a settings file becomes 0600 once it holds an inline secret.
9. Spec citations name sections instead of lines, schema line citations match the schemas, and the docs match the code.

From our pre-push review:

• NAT: each root Runner is one ACS session with a fresh id; nested Runners join it, and a client's workflow-run-id header or replayed steps neither merge nor end it. A session ends once, on success, error, cancel or close(), and holds its own hook order and counts. The configured session_id and ACS_SESSION_ID are removed.
• NAT: a verdict on the workflow input blocks the run's calls, and a verdict on its output is recorded.
• Claude Code and Cursor: a host session that continues after sessionEnd gets a new ACS session; a sessionStart whose hook was killed is settled under the posture; session state follows the session across a cd.
• Failed tool results reach the Guardian (PostToolUseFailure, postToolUseFailure), and every turn ends: interrupted, error on StopFailure, and denied_at_start after a denied turnStart. Cursor's stop is wired.
• A Guardian answer missing what response-envelope.json requires is a counted malformed_response.
• SubagentHandback in auto mode turns an ask into a deny; Cursor's ACS_DISABLED prints an explicit allow; turn_id is on every in-turn step; the ClientHello declares the body size post() enforces; the wire tools expand only ~; onFailure: block is set only where a failed hook stops the action.
• Keys that collide once normalized fail closed, so the signed view never drops a value, and every decided Guardian answer is checked against response-envelope.json.
• Claude Code withholds a built-in tool's output only in that tool's own output schema (Bash, Read, Grep, Glob, WebFetch, WebSearch, Write, Edit, Agent); any other tool is blocked and recorded as unenforceable_decision. An Agent result cites no toolCallRequest.
• A host session is marked ended before its sessionEnd exchange, and both wire tools give sessionEnd 15 seconds, so a resume after a slow Guardian still opens a new ACS session.
• Settings backups redact the whole inline secret, however shlex.quote wrote it.
• Cursor answers {} when a tool gate proceeds, so Cursor's sandbox and approval still decide, and acs-claude-code-hook answers Cursor's events through the Cursor adapter when Cursor runs it from .claude/settings.json.
• NAT refuses a call of an ended or closed session before any cached decision or bypass, and each call stays in the session of the run whose context made it: NAT reports a run's end in the Runner's context, so later calls and tasks created after the run use the middleware's own session while work the run left behind stays refused, and only a workflow's own start opens or joins a run session.
• acs-claude-code-hook finds Cursor's event at the top level even when the event is too deep to parse, and the MODIFY schema exception applies only to MODIFY answers.
• A signed JSON-RPC error code written as an integral number, such as -32000.0, refuses like the integer it is.
• NAT denies a call, or withholds an output, whose keys would become one JSON key in the form the Guardian is sent, such as 1 and "1", or None and "None" inside a Pydantic model, under either posture.
• A host session whose end cannot be recorded stays open, with no sessionEnd, so the next hook continues it rather than a sealed one.
• The wire tools write --secret-file and --audit-file as absolute paths.
• Comments and docstrings are kept only where a reader needs them.

Added on 4 November:

• Signing refuses an envelope with no session_id, and a response without one does not verify, instead of using a key derived from request_id (§10). A gate whose request cannot be signed sends nothing and is denied.
• The NAT tests set ACS_HANDSHAKE_TIMEOUT_SECONDS instead of patching a module-level override, and 46 noqa: E402 markers that suppressed nothing are removed.

Which issue does this implement

Part of #134

Base branch

Stacked on #488, not on integration. It lands through #22; see the stack in #22.

Type of change

• Reference implementation or adapter

I tested this

At this slice's top (fcc58fe3), with claude removed from PATH and ACS_LIVE_CLAUDE and ACS_SPEC_DIR unset: 637 passed and 3 expected skips with the NAT extra, 504 passed and 3 expected skips without it. The skips are the two opt-in live Claude Code tests and the manual Cursor procedure. CI passes on this PR, including lint-imports and the installed-wheel check on Python 3.11 and 3.12.

Checklist

• Commits are signed off with git commit -s (required by the DCO)
• Prose follows STYLE.md
• No secrets, tokens, or internal URLs in the diff

Security

A failed gate hook blocks, denied output is withheld in each supported tool's own schema, failed tool results reach the Guardian, a malformed Guardian answer is a counted decision failure, a colliding key fails closed, Cursor's sandbox and approval still decide on an allow, a workspace wired for Claude Code is governed in Cursor, and each NAT root Runner is one session that refuses calls once it ends. A signature needs the envelope's session_id, so an envelope without one is not signed and a response without one does not verify.

[drk-ram]

Reviewed at head fcc58fe325e6ab116c5497cb6b74b95d7318a7e8 (stacked on #488, base refimpl/adapters-13-spec-alignment, which is a9727cd). This slice is 91 files, so I will say what I read line by line and what I took from tests. I am approving, with four notes.

Read line by line: client/* (_exchange.py, _handshake.py, _signing.py, _store.py, _config.py, _secrets.py), most of core/* (_canonical.py, _decision.py, _envelope.py, _signing.py), integrations/_bootstrap.py, _settings_file.py, claude_code/hook.py, the Claude Code PreToolUse and PostToolUse translation and withholding, the Cursor post-tool translation, and the NAT session model (_Session, _open, _exchange, _end_session, _json_safe). Taken from the tests: the remaining Claude Code and Cursor adapter plumbing, the NAT lifecycle and event-loop paths, the wire tools beyond the diff above, and the conformance harness. Test counts stay level: test_acs_core_conformance.py has 71 tests at both heads and test_security.py has 47, so the 478 lines removed from the conformance file are comments and docstrings, not coverage.

What checks out.

• Signing needs a session_id (§10). sign_envelope raises when the envelope has none instead of falling back to request_id, and verify_signature returns False for a response checked without one (that second part is from reading the code). I ran sign_envelope on an envelope with no session_id and got ValueError, and with one the signature carries the label from ACS_HMAC_KEY_ID. A gate whose request cannot be signed is denied through round_trip(gate=True) with posture.closed(), so it is denied even under a fail-open posture.
• Normalisation before signing (_signable): a lone surrogate becomes U+FFFD, an integer past 2^53 − 1 becomes a string, NaN and infinities become strings, and two keys that normalise to one fail closed. I called _normalize directly on a request with each of those and got what the PR describes, with an envelope_normalized audit record that counts each kind. The key-collision case raises, so the signed view can never drop a value.
• Response validation. result_problem() validates every decision against response-envelope.json's AcsResult with the bundled schemas, so a verdict that fails it is a counted malformed_response. A restrictive or unreadable verdict is Refused and is never carried out as an allow. The MODIFY-composition exception is correct, because §6.3 makes that a DENY the adapter applies. The rfc3987_syntax shortcut in _bootstrap.py is sound: the schemas use only date-time, uri and uuid formats, and I confirmed uri is still enforced with that module blocked.
• The pending startup claim from #487 is now settled. open_session resolves a session_start_incomplete under the session's own posture, counts it as observed_agent_error, and records the outcome, so a killed hook no longer refuses the session for good.
• Host-session lifecycle. current_session_id and mark_session_ended give a new ACS session to a host session that continues after sessionEnd, and the end is marked before the exchange so a cancelled hook still leaves the next one a new session. session_end_not_sent covers a marker that cannot be written.
• Allow prints nothing at the Claude Code request gate, so Claude Code's own permission rules and prompt still decide. MODIFY goes out as ask with updatedInput (documented in mapping.md), and SubagentHandback in auto mode, which cannot prompt, turns an ASK into a DENY with an audit record.
• Withholding output. _withhold replaces the output in the tool's own schema for Bash, mcp__*, Read, Grep, Glob, WebFetch, WebSearch, Write, Edit and Agent, and records unenforceable_decision for anything else. For Cursor, _post_tool_withhold uses updated_mcp_tool_output only where Cursor documents it and skips an HTTP MCP server's {"redacted": true} output.
• Settings backups. write_atomically writes a 0600 backup, keeps a symlink and the mode, and goes to 0600 when an inline secret is written. _redact_command handles values shlex.quote builds from several fragments.

Verification (Windows, Python 3.11.9, uv sync --frozen --extra nat --group test). The harness needs two edits to run on Windows, a thread-based line read in launch_guardian() and an fcntl stub in example_guardian.py. I made them in my working copy only. On fcc58fe, pytest -v gives 614 passed, 49 failed, 3 skipped. I ran the same suite with the same edits on the base of #487 (c59c00e), and on #487's head, #488's head and this head. Against that baseline, every failure on this head is either one that already fails there or sits in a test that asserts something Windows does not do: 0600 and 0700 modes, chmod 0o500 on a directory as a write barrier, symlink handling, /-style paths in test_hook_command.py, and 127.0.0.1:1 giving "connection refused" quickly (Windows reports decision_timeout after the timeout, not transport_failure). The new test_session_gate.py cases on lone surrogates reach the same refused-port behaviour, and they do record envelope_normalized before it. tests/common/test_key_id.py::ExampleGuardianLabel failed once while the machine was busy and passes on its own (17 passed, 7 subtests). No NAT test fails on this head, and the two that failed on the earlier heads (test_emission.py lifecycle and sequential-session cases) now pass. I did not run lint-imports or the installed-wheel check, which need Linux. The PR's checks show green.

Notes (non-blocking).

1. Numbers past 2^53 − 1 reach the Guardian as strings, and nothing in the envelope says so. A policy that compares a numeric argument (amount > N) is evaluated against a string, whose result depends on the engine's type rules, and a Guardian cannot tell a normalised integer from an agent that sent the same digits as a string. The audit record helps the operator afterwards and does not help the policy at decision time. A line in docs/guardian/README.md saying so, or a marker the Guardian can key on, would help. Failing closed on a gate, as the PR does for key collisions, is the stricter choice if you prefer it.
2. Backup redaction covers inline secrets in a hook command and not an env block. _redacted() rewrites any string containing ACS_HMAC_SECRET=. I ran it on a settings file with "env": {"ACS_HMAC_SECRET": "…"} and the value was written to the backup unchanged. Claude Code settings do take an env block, and the wire tools never write one, so only a hand-edited file is affected. The backup is 0600 either way. Either redact a key named ACS_HMAC_SECRET as well, or say in the docs and the PR that the redaction covers inline command values.
3. The withholding schemas are tied to Claude Code 2.1.317. The code comment and mapping.md say so, and also say that Claude Code ignores a replacement that does not match and shows the original output. If a later release changes one of those shapes, the adapter still believes it knows the shape, so it audits nothing and the result goes through. Please keep the opt-in live test (ACS_LIVE_CLAUDE) in the release checklist and say in the README which Claude Code versions it was run against.
4. Comment and docstring trimming. Roughly 1,950 source lines are removed, most of them module docstrings and rationale comments (for example in _canonical.py, _exchange.py, _secrets.py, _urls.py, _transport.py). Most of the security rationale survives in shortened form, but it made this diff hard to review. In later slices, a separate commit or PR for pure comment edits would help.

Approving fcc58fe3.

[rocklambros]

Closing this slice because PR #22 (the reference adapters for Claude Code, Cursor and NAT) merged into integration as 2630ec2, and that merge carries every slice in this stack. The top of the stack had the same files as PR #22's final commit, so nothing in this slice was left behind. Thanks, Bar, for cutting the adapters into pieces this size, because it made the review possible.