Add adapters/ with Claude Code, Cursor, and NAT reference implementations

[bar-capsule]

Summary

Introduces a top-level adapters/ directory holding reference implementations that wire popular agent frameworks to an ACS Guardian through configuration only, with no agent code changes. Ships three working adapters with passing tests for each.

What lands

Adapter	Status	Mapping	Working adapter	Tests	Live verification
adapters/claude-code/	Reference implementation	✓	✓	13 unit + 2 automated live tests	✓ Automated: real claude --print round-trip, ALLOW + DENY paths (test_live_claude_code.py)
adapters/nat/	Reference implementation	✓	✓	7 integration + 5 live workflow tests	✓ Automated: exercises real function_middleware_invoke against nvidia-nat-core 1.7.0 (test_live_nat_workflow.py)
adapters/cursor/	Reference implementation	✓	✓	13 unit tests	✓ Manual reproduction procedure in tests/live_verification.md (Cursor is a desktop app with no documented headless mode)
adapters/example-guardian/	Shared test fixture	n/a	n/a	n/a	Used by all three adapters' integration tests

Total: 40 automated tests + 1 documented manual verification procedure, all passing.

The adapter pattern

ACS-Core specifies what a hook event looks like on the wire and what the Guardian's decision looks like coming back. It does not dictate how a framework physically wires the interception in. Each adapter demonstrates the boundary choice for its framework:

Adapter	Interception mechanism	Event dispatch	Block mechanism
Claude Code	Shell command per hook (settings.json)	Event type in stdin JSON	hookSpecificOutput.permissionDecision
Cursor	Shell command per hook (hooks.json)	Event type as argv[1]	permission (top-level, per-event) + exit code 2
NAT	In-process Python FunctionMiddleware class	NAT's middleware pipeline	Raise ACSGuardianDenied (NAT 1.7.0) or InvocationAction.SKIP (NAT dev)

All three send the same ACS JSON-RPC shape to the Guardian. The example Guardian (adapters/example-guardian/example_guardian.py) is shared across all adapters — same wire format regardless of which framework emits the event.

The top-level adapters/README.md contains a step-by-step walkthrough with concrete JSON payloads at each step, a cross-adapter comparison table, and a flow diagram. Read that first.

Claude Code adapter

Wire it up by editing ~/.claude/settings.json (see settings.json.example); no code changes to your agent.

Live verification: tests/test_live_claude_code.py spawns claude --print in a sub-process with a project-level settings.json wiring the adapter into PreToolUse. Tests both:

• ALLOW path: benign echo command runs and the marker string appears in Claude Code's output.
• DENY path: Guardian's destructive-Bash policy denies; Claude Code's response surfaces the block.

Both passing in ~18s.

Schema corrections discovered via the live test (real Claude Code differs from public docs):

• PreToolUse output uses hookSpecificOutput.permissionDecision = "deny", NOT top-level decision: "block".
• PostToolUse field is tool_response (object), NOT tool_output (string).
• Real payloads include tool_use_id, effort, duration_ms not mentioned in public docs.

NAT adapter (NVIDIA Agent Toolkit)

Real NAT middleware class. Installs via pip install nvidia-nat-core, configured in NAT workflow YAML:

middleware:
  acs:
    _type: acs_guardian
    guardian_url: http://127.0.0.1:8787/acs
    default_deny: true

workflow:
  _type: react_agent
  middleware: [acs]

Live verification: tests/test_live_nat_workflow.py exercises NAT's actual orchestration method (FunctionMiddleware.function_middleware_invoke) — the same code path NAT's runtime calls when a function with middleware is invoked. Tests prove the load-bearing property: when the Guardian denies, the target function does not execute (the test's side-effect counter stays at 0).

Covers: allow / deny / fail-closed / fail-open. 5/5 passing against nvidia-nat-core 1.7.0.

Schema corrections discovered while building:

• InvocationAction.SKIP is on the NAT dev branch, NOT in 1.7.0. Block by raising. Adapter feature-detects and prefers action-based path when available.
• Middleware configs must inherit FunctionMiddlewareBaseConfig with name= class kwarg (NAT's TypedBaseModel registration). Plain Pydantic BaseModel fails on @register_middleware.

Cursor adapter

Real Cursor schema sourced from Cursor's own bundled ~/.cursor/skills-cursor/create-hook/SKILL.md. Maps all 20 documented Cursor hook events to ACS steps/* methods.

Cursor is a desktop application without a documented headless mode, so live verification is a documented manual procedure in tests/live_verification.md. The procedure has been run end-to-end (5+ hooks flowed through the adapter, zero adapter errors); captured payloads from that reproduction are not committed because Cursor's events include session-identifying fields. Anyone with Cursor installed can reproduce.

Why in-spec adapters/ and not separate repos

Single repo for spec + reference implementations on the first batch makes the spec evolve alongside the adapters that exercise it (the live tests on this PR found several real schema gaps between docs and actual behavior — that feedback loop is what makes the spec text trustworthy). When the pattern stabilizes and individual adapters need their own release cycle, splitting to separate repos is straightforward.

What this PR does NOT do

• Does not modify any normative spec text. Adapters are reference implementations, not spec.
• Does not introduce new profiles. The adapters exercise ACS-Core; profile-tier adapters (acs-audit, acs-crypto, etc.) layer on later.
• Does not address ACS signing the outbound traffic. That's a deployment concern handled at the transport layer for these minimal adapters.

Running the tests

# Claude Code (requires `claude` CLI on PATH for the live tests)
cd adapters/claude-code && python3 -m unittest tests -v

# Cursor (unit tests only; manual reproduction per tests/live_verification.md)
cd adapters/cursor && python3 -m unittest tests -v

# NAT (requires pip install nvidia-nat-core)
cd adapters/nat && python -m unittest tests -v

🤖 Generated with Claude Code

[rocklambros]

@bar-capsule I went deep on this branch before writing anything. Checked it out, ran the three suites, read each adapter against the v0.1.0 schemas. The config-only pattern is the right call, and the per-adapter docs are honest about what's deferred. I want to flag a gap before "reference implementation" sticks, because people copy reference adapters line for line, and a few of these would ride along into their deployments. Marking this request-changes so the wire-format and fail-open items get a look before merge, not as a veto on the direction.

I checked all of this against the open issues first (#10 through #19). Those are spec-level: capability resolution, HMAC key management, the conformance program. Nothing below is a dupe. This is adapter-implementation ground. Three of mine have a protocol-level twin and I'll point those out.

The one that matters most: the adapters don't emit the v0.1.0 wire format. In claude-code/acs_adapter.py the request puts acs_version, request_id, timestamp, and metadata at the top level, but request-envelope.json wants them inside params and sets additionalProperties: false. A schema-validating Guardian rejects every request. timestamp goes out as epoch millis (int(time.time() * 1000)) where the schema asks for an ISO-8601 string. The payload uses tool / name / arguments where the hook schema wants the payload wrapper with arguments as {value, provenance}. Same shape in the cursor and nat adapters. The tests stay green because example_guardian.py reads params.get("tool") too, so both sides agree with each other and disagree with the spec. Nothing validates an emitted envelope against acs_schema.json. One test that does would have caught all of it, and it's the highest-leverage thing you can add here.

The deny path fails open on anything it doesn't recognize. In translate_response, an unknown or empty decision returns {}, which Claude Code and Cursor both read as "proceed." ACS_DEFAULT_DENY only kicks in on an exception (Guardian unreachable), not on a Guardian that answers with a verdict the map doesn't know. So a v0.2 disposition, a typo, even a trailing space surviving .lower(), all proceed. NAT already does the right thing and blocks under default_deny. The other two should match it. One line each.

No signing at all (this one's adjacent to #11, not the same). The adapters don't HMAC the envelope, and the example Guardian neither verifies a signature nor checks for replays. The READMEs call this "deferred to transport," but conformance.md:28 lists the baseline signature as a Core MUST, and :67 says transport doesn't satisfy it. #11 is about key distribution and rotation once you're signing. This is the step before: the reference ships with no signing, so every copy starts from an unauthenticated channel. The default http://127.0.0.1:8787/acs in the config keeps that invisible until someone repoints the URL at another host.

Delegation walks around the gate. SubagentStart isn't in HOOK_MAP, Claude Code can't block on it anyway, and example_guardian.py allows Task by default. A subagent spawn isn't evaluated before it acts. That's the adapter-level version of #16, and it lands on the exact confused-deputy path the subagent hooks were promoted to cover. At minimum I'd surface it in mapping.md's "not mapped" list instead of leaving it silent.

On the tests: "40 tests, all passing" is true on your machine, not in CI. NAT's 12 tests skip when nvidia-nat-core isn't installed (I got Ran 12 tests in 0.000s, OK (skipped=12)), Cursor's live test is a skip placeholder, and no workflow runs the adapter tests at all (only sync_version.yml). Skips read as passes, so a regression that lets a denied call through lands green. There's no requirements.txt under adapters/, and the NAT install is unpinned (pip install nvidia-nat-core, no ==). The NAT deny test also catches ACSGuardianDenied and returns without asserting the call was actually aborted, so it passes as long as something raised. This cluster worries me second-most, because green tests on a security control are worse than no tests. Pin the dep, run the unit tests in CI, and have the deny tests assert a real side effect didn't happen (the file wasn't written, the counter stayed at 0).

Smaller stuff, and I'm less sure these are worth blocking on:

• example_guardian.py's regex misses rm -fr /, rm --recursive --force /, rm -rf ~, and find / -delete. It's labeled illustrative so I won't die on this hill, but it's the only thing a newcomer can run on day one, so I'd make it harder to fool or louder about being a toy.
• A PostToolUse deny can't undo a side effect that already ran (Claude Code's own hook docs say PostToolUse can't block the action). Cursor's beforeReadFile returns {}, so a denied file read still happens. The pre-hooks are the only real gate, and the docs should say so plainly.
• NAT's _build_request isn't inside the try/except, so a non-serializable kwarg throws before default_deny can catch it. And post_invoke ignores a result-side deny.
• mapping.md and the code disagree on the deny shape for non-PreToolUse hooks. The doc says {"continue": false, "stopReason": ...}, the code emits {"decision": "block", "reason": ...}. One is wrong against Claude Code's contract.

None of this changes my read on the direction. I like where this is going, and the cross-adapter table in the README is genuinely useful. I'd hold the "reference implementation" label until the envelope matches the schema and the deny paths fail closed, since those are the parts people copy without reading the footnotes. Happy to send a PR with the schema-validation test, or pair on the envelope fix if that's faster.

Tracking: I cross-linked the delegation gap onto #16 and the no-signing gap onto #11 so the protocol-level and adapter-level views sit together. The rest of the findings here are adapter-specific with no matching issue.

(cc @afogel since the envelope and signing points touch conformance.md.)

[rocklambros]

Merge-order note: this should land after #21, and after the change-request items above are addressed.

• The adapters' conformance posture marks system/ping and Wrapped MCP as "not implemented." That story only holds once Slim ACS-Core: relax MODIFY, system/ping, and wrapped MCP to SHOULD #21 relaxes those to SHOULD; before that the floor lists them as MUST, so the reference would be claiming conformance against a floor it doesn't meet.
• This PR has changes requested (wire format and the fail-open deny path), so it shouldn't merge until those are resolved regardless of ordering.

No git conflict with #20 or #21 (this only touches adapters/), so the sequencing is about consistency, not rebasing. Overall order I'd suggest: #21, then #20, then #22. @bar-capsule

[bar-capsule]

Thanks @rocklambros for the thorough review! every item addressed.

Wire format vs request-envelope.json - Every emitted envelope is schema-validated against canonical request-envelope.json from $ACS_SPEC_DIR (not against fixtures, not against the example Guardian's shape). params wrapper, ISO-8601 timestamps, payload + {value, provenance} arg wrapping - all to spec.

Deny fails open on unknown - _fail(cause=…) taxonomy across all three adapters covering transport, adapter exception, signature failure, and 7 JSON-RPC error codes via shared guardian_error_cause(). Unknown disposition + ACS_DEFAULT_DENY=1 → block; otherwise an ACS_AUDIT fail_open_bypass event with the cause label.

Signing - HMAC-SHA256 across all three adapters via adapters/_common/. Every envelope signed; every response verified. SIGNATURE_INVALID / REPLAY_DETECTED / TIMESTAMP_OUT_OF_WINDOW each map to a distinct audit cause.

Subagent delegation - example_guardian gates Task by default (subagent_gated); opt-in via ACS_ALLOW_SUBAGENT=1. Each adapter's mapping.md lists where delegation hooks aren't honorable by the framework.

Tests on tests - Deny tests now assert the real side effect didn't happen, the way you described — counter checks plus, for NAT, a canary-file pattern (if rm -rf runs despite the deny, the canary file vanishes regardless of what the counter says). A real Vertex/Gemini react_agent run surfaced silent-bypass bugs the synthetic tests would have shipped; all have regression tests.

CI workflow - Pinned nvidia-nat-core==1.7.0 + nvidia-nat-langchain==1.7.0, Python 3.12, runs the per-adapter + conformance suites on every push to adapters/ or specification/, hard-fails on any skipped NAT or conformance test.

Smaller items: rm regex hardened (-rfv, -fr, --recursive --force, --no-preserve-root). READMEs say plainly that pre-hooks are the gate; post-hooks redact via output=None + audit. NAT _build_request moved inside try; post_invoke result-side deny propagates. mapping.md and code now agree on deny shape.

Would appreciate re-review when you have a window.

[niv-capsule]

I dont really think Notification is an important hook I would replace it with Stop maybe, which is when the agent stops after finishing what he was tasked with

[niv-capsule]

Maybe you should wire the managed-settings file instead, in case the user is managing its hooks, the managed-settings is more isolated.

[niv-capsule]

Everything is python which is not native on windows, if you want a wider support a followup PR with ps1 files is needed IMO

[niv-capsule]

Maybe add that its not needed but could help in case its not working.
Some people might not want to close their sessions

[niv-capsule]

I dont think we need smoke tests in the readme, its not relevant

[niv-capsule]

I think this should be under tests

[niv-capsule]

from the name it seems like it should be under tests and if not lets rename it to something that does not include the word test it in.

[niv-capsule]

Are we fine with these exceptions?
if they are important for the functionality of the hooks why are we catching them and not letting them raise and fail the operation?

[niv-capsule]

why do we have imports in the middle of a function?

[niv-capsule]

the PR is too long so my chrome search might not be working so I cant tell if we use it, but I'm not sure why we need ping if we already have handshake?
If we ping every time its way too much of a overhead IMO, we need to remember that every thing that takes time is accumulative and if the time it takes to handle these hooks takes more then a few ms a top a sec it would make the experience bad, you need to remember that claude uses tons of tools for example so for every Pre/Post Tool takes a sec for 20 tool calls the user have to wait 40 secs extra, it might not sound like much but overtime its an issue

[rocklambros]

@bar-capsule

I ran this rather than just reading it, and the first thing I hit is that the CI job can't fail. Everything else I found is downstream of that in one way or another, so I'll start there.

This is a long comment because it's a 14,515-line PR that turns a docs repo into a code repo. The work is real and the threat model in adapters/SECURITY.md is better than most projects ship. That's precisely why the gaps matter, since a reader will trust this by default.

The CI gate reports success when the tests fail

Both test steps pipe into tee:

python -m unittest test_acs_core_conformance -v 2>&1 | tee out.log   # line 39
python -m unittest discover -v tests 2>&1 | tee out.log              # line 83

GitHub's implicit shell for run: is bash -e {0}, and pipefail only gets added when you write shell: bash explicitly. The workflow has no shell: key anywhere, so the pipeline's exit status is tee's, which is always 0.

I checked rather than assuming:

$ printf 'false 2>&1 | tee /dev/null\n' > v1.sh
$ bash -e v1.sh;           echo $?    # 0
$ bash -eo pipefail v1.sh; echo $?    # 1

The header comment says the workflow "addresses the 'skips read as passes' failure mode," and the skip grep at lines 41 and 91 does work. So right now the job catches "a test didn't run" and misses "a test ran and failed," which I'd argue is worse than no workflow, because the badge certifies something false.

shell: bash on both steps fixes it. Then re-run, because I think the suite is currently red (next item) and the green is hiding it.

The conformance suite can't run from a fresh clone

ACS_SPEC_DIR defaults to /tmp/acs-spec-source/specification/v0.1.0 in ten-plus places, including test_acs_core_conformance.py:66, _common/test_harness.py:148, example_guardian.py:97, three test_envelope_schema.py files, and all three e2e_check.py scripts. That path doesn't exist, and the canonical schemas ship in this repo at specification/v0.1.0/, one directory up from adapters/.

Running the documented command from adapters/README.md:22-25 gives Ran 6 tests ... FAILED (failures=1, errors=9). Pointing ACS_SPEC_DIR at the in-repo schemas gives Ran 48 tests ... OK.

Two things make this worse than a broken default. The documented remedy in claude-code/README.md:114-116 is git clone https://github.com/Agent-Control-Standard/ACS.git /tmp/acs-spec-source, which pins conformance to whatever's on remote main rather than the schemas in the PR under review. And in example_guardian.py, the missing directory leaves _SPEC_VALIDATION_AVAILABLE = False, so the Guardian silently skips envelope validation with no warning. Since check_replay and check_skew both return early on a falsy request_id or timestamp, an envelope that just omits both then sails past replay and freshness protection.

Path(__file__).resolve().parents[N] / "specification" / "v0.1.0" as the default, env var as override, and log loudly when validation is unavailable.

The Claude Code adapter drops subagent events entirely

I said something wrong about this earlier and want to correct it. mapping.md:17 documents a SubagentStop mapping, and I initially took that at face value. The code doesn't do it. HOOK_MAP at lines 64 to 72 has seven entries and contains neither subagent hook:

HOOK_MAP: dict[str, str] = {
    "SessionStart": ..., "SessionEnd": ..., "UserPromptSubmit": ...,
    "PreToolUse": ..., "PostToolUse": ..., "Notification": ..., "Stop": ...,
}

SubagentStop shows up only at line 77 in BLOCK_RESPONSE_HOOKS and line 358 in _TRANSLATORS, and both are unreachable because main() gates on HOOK_MAP first:

if hook_name not in HOOK_MAP:
    return 0

Feeding it a SubagentStop event with ACS_DEFAULT_DENY=1 and a dead Guardian gives exit 0, empty stdout, empty stderr. Not even a _fail() audit line. The dead entries are the part I'd flag hardest, because they make the file read as if the hook is handled, so anyone skimming for coverage gets a false yes.

Cursor has the mirror-image problem. acs_adapter.py:78-85 omits subagentStop deliberately and says why, which I think is honest and right given final_chain_hash is genuinely unknowable there. But hooks.json.example:54-58 still wires it, so the shipped config invokes a path that drops the event silently and skips ACS_DEFAULT_DENY=1 on the way out.

NAT's mapping.md:20 claims sub-workflows map to subagentStart/subagentStop. grep -i subagent nat/acs_adapter.py returns nothing, and line 23 of the same file quietly retracts it ("The minimal adapter ... emits steps/toolCallRequest and steps/toolCallResult for every wrapped function call"). Rows 17, 18, and 19 for knowledgeRetrieval, memoryContextRetrieval, and memoryStore are in the same position.

And even if all three emitted, example_guardian.py:157-164 puts both hooks in INFORMATIONAL_METHODS and returns allow unconditionally, so a spawn declaring intent_derivation: "fresh" from a constrained parent gets waved through. This matters a lot for #21, which promotes both hooks to MUST on confused-deputy grounds. I've left a longer note there about the spec side.

mapping.md inverts the fail posture

claude-code/mapping.md:43:

Decision honoring: the adapter's _fail() posture is deny by default (ACS_DEFAULT_DENY=1)

claude-code/acs_adapter.py:58:

DEFAULT_DENY = os.environ.get("ACS_DEFAULT_DENY", "0") == "1"

The default is fail-open. The doc says fail-closed. This is the row an adopter porting to a fourth framework reads to decide their own default, so it's wrong in the direction that overstates safety.

Five more in the same file, all verifiable against a line of code: :42 says baseline integrity isn't implemented (:259 calls sign_envelope), :38 says no handshake happens (:263-283 performs one), :27 and :28 document response shapes the code doesn't emit, and :40 describes a session-id derivation the adapter doesn't use. nat/mapping.md:84 and cursor/mapping.md:100 carry the same false "integrity deferred to transport layer" claim.

Nothing tests any mapping.md, so this drift is invisible to a green suite.

settings.json.example wires five hooks, not six

Wired: SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PostToolUse. Missing: Notification, which is the only event mapped to steps/agentResponse.

So the config an adopter copy-pastes fails even the pre-#21 six-hook minimum, while claude-code/README.md:280 claims all six and adapters/README.md:27 says "the 6 minimum hooks, all 5 dispositions."

The annoying part is that wire.py would have caught this. Line 319 emits NOTE: wiring a SUBSET of ACS-Core's 6 mandatory hooks. Missing: [...]. The checked-in example just wasn't produced by it. Also worth noting ACS_DEFAULT_DENY: "1" appears only on the PreToolUse block, while wire.py:101 classifies UserPromptSubmit as a gate hook too, so the two shipped wiring paths disagree about which hooks may fail open.

The e2e scripts print a conformance verdict they haven't earned

All three end with a variant of:

report.summary("YOUR CLAUDE CODE INSTALL IS ACS-CONFORMANT", width=68)

The suite's own docstring at lines 12 to 14 says a pass means conformant "minus full Wrapped MCP." claude-code/README.md:290 marks Wrapped MCP "✗ not implemented" in its own table. The banner carries neither caveat, and it's the artifact that ends up in a screenshot.

I'd scope it to what actually ran, something like ACS-CORE SMOKE PASS (4/4 scenarios; not a conformance certification), and reserve "conformant" for an instrument that enumerates the requirement set.

Signing has a canonicalization mismatch that resolves to fail-open

_common/acs_common.py:81-85 falls back to json.dumps(..., sort_keys=True, separators=(",", ":")) when rfc8785 is absent, and the docstring at 76 to 78 says that's "JCS-equivalent for all JSON shapes ACS envelopes carry." It isn't, for any float:

{"duration_ms": 1.0}    rfc8785: {"duration_ms":1}      fallback: {"duration_ms":1.0}
{"duration_ms": 1e16}   rfc8785: ...10000000000000000}  fallback: ...1e+16}
{"duration_ms": -0.0}   rfc8785: ...0}                  fallback: ...-0.0}

Key ordering diverges too. json.dumps sorts U+FFFF before U+10000, while RFC 8785 §3.2.3 sorts by UTF-16 code units and puts U+10000 first.

This is reachable, not theoretical. claude-code/acs_adapter.py:178-179 puts framework-supplied duration_ms straight into the signed payload. And the provisioning asymmetry is the default: nat/requirements.txt lists only nvidia-nat-core and ruamel.yaml, with rfc8785 appearing only in requirements-test.txt. So an adapter without it signs 1.0, a Guardian with it verifies 1, you get -32004, and per the next item that's a fail-open on every PostToolUse.

specification.md:290 says "Alternative canonicalization is not permitted in v0.1," so I'd delete the fallback and raise at import, make rfc8785 a hard runtime dependency everywhere, and add floats, -0.0, exponents, and a non-BMP key to the sample set. The current test skips itself when the divergence condition is present (test_edge_cases.py:60-63), which is the one case you want it to run.

Guardian rejection and Guardian failure are the same thing to the adapter

claude-code/acs_adapter.py:433-447 routes any "error" in response through _fail, and _common/acs_common.py:317-325 maps -32004 (bad signature), -32005 (replay), and -32600 (malformed envelope) into that same posture. Under the default ACS_DEFAULT_DENY=0 that means allow.

example_guardian.py:665-669 returns -32600 for any body over 1 MiB, before any policy code runs. So a prompt-injected agent issues Write with a 2 MB content argument, the envelope blows the cap, and the write proceeds ungoverned. Same primitive via -32005 by reusing a request_id, which acs_adapter.py:150 makes deterministic and guessable with uuid5(NAMESPACE_URL, f"claude-code:tool_use:{tool_use_id}").

SECURITY.md T6 frames the 1 MiB cap as DoS mitigation. It's also a policy-bypass primitive, because it sits upstream of evaluate_step.

The adapter is arguably conformant here, since §6.4 says an error without a decision follows the failure posture. I think that's a spec gap as much as a code one: ACS doesn't distinguish "the Guardian couldn't reach a verdict" from "the Guardian refused your envelope," and only the second is attacker-reachable. Codes that mean "alive and refused you" should fail closed regardless of posture.

The audit trail has nowhere to land

_common/acs_common.py:378 writes ACS_AUDIT <json> to sys.stderr. SECURITY.md:24 lists the audit log as an in-scope component. None of the three example configs route adapter stderr anywhere, and Claude Code doesn't surface hook stderr outside debug mode.

So when the Guardian dies, each hook invocation gets connection-refused, writes one line to a stream nobody collects, and exits 0. ping() exists at acs_common.py:508 and no adapter calls it, so nothing detects the outage either.

§6.4 offers a control-for-audit trade under disruption, and it's only a trade if the audit half lands somewhere durable. Right now it's control-for-nothing. ACS_AUDIT_FILE (append, 0600) plus setting it in all three example configs would close it.

Responses aren't bound to their requests

No adapter compares response["id"] to request["id"], or result["request_id"] to the one it sent. example_guardian.py:522-530 populates the field, so the binding is on the wire and just unread.

The signature is per-session, so a captured signed ALLOW for a benign ls verifies fine when replayed against rm -rf ~/. hmac.compare_digest is correct here and irrelevant, because the signature is genuine.

SECURITY.md T3 covers replay in the request direction only. Two lines per adapter, failing closed on mismatch.

Related and cheaper to hit: no ACS_HMAC_SECRET appears in either example config. With no secret, sign_envelope returns the envelope unsigned (acs_common.py:240-241) and verify_signature returns True (:274-276), so any local process that binds 127.0.0.1:8787 first becomes the Guardian and allows everything. That's an authentication failure rather than a confidentiality one, so SECURITY.md O1's "plaintext HTTP is a deployment concern" doesn't quite cover it.

Performance numbers

adapters/README.md:146 says "The whole round-trip is ~10 ms. The agent doesn't know any of this happened."

Seven runs of the real adapter with the Guardian port closed, so effectively zero network time, warm cache: median 93.9 ms, range 86.4 to 105.9. That's interpreter start plus the imports at lines 31 to 54, before the Guardian does anything. README.md:167 describes the spawn-per-event model correctly, so the model is right and the number just doesn't include it.

The slow-Guardian case is worse. Against a listener that accepts and never responds, three consecutive events measured 10.10s, 10.12s, 10.13s. That's the 5s handshake plus the 5s decision call, and it repeats every event because acs_common.py:491 guards the cache write behind if server_hello:, so a failed handshake never gets cached. There's no retry, no backoff, no circuit breaker (grep -rE "retry|backoff|circuit" on non-test adapter code is empty), and both timeouts are hardcoded.

Combine that with ACS_DEFAULT_DENY: "1" on PreToolUse in the example and a degraded Guardian means ten seconds of dead air followed by a denial, on every Read, every Bash, every Edit. There's no ACS_DISABLED check anywhere in main(), so recovery is hand-editing ~/.claude/settings.json mid-incident, per machine.

I'd replace the README number with a measured breakdown under stated conditions, note that NAT runs in-process and doesn't pay the spawn cost, and add an ACS_DISABLED early return documented as the incident procedure.

The conformance suite's central tests can't fail

A few of these, since the suite is the thing adopters are told to trust:

test_each_minimum_hook_returns_known_disposition (:437-449) asserts the decision is one of the five legal values. A Guardian that does return {"decision": "allow"} passes. The class docstring at 385 to 388 correctly identifies this risk and says the contradiction check catches it, but that check (:451-461) validates the broken payload locally via _validate_hook_payload and never sends it anywhere. So it tests that hooks/*.json constrains shape, which is a fine test of the schemas and no test of any Guardian.

Core04 drives two dispositions live and hand-synthesizes the other three. Line 545 says so directly: "Guardian doesn't emit modify in our example, so we construct one manually and validate it." That proves the wire can express MODIFY, not that anything implements it. Meanwhile the three adapters document three mutually incompatible substitutions (NAT sends ASK and DEFER to DENY, Cursor sends DEFER to ASK, Claude Code blocks both), none of which the suite covers.

Core10's MCP assertion is satisfied by example_guardian.py:576-577 denying protocols/MCP/* as an unknown method. Also, adapters/README.md:29 says MCP requests are "routed through the standard steps/toolCallRequest path" at the Guardian, and the test file at 1281 says the Guardian "falls through to unknown-method deny." The test file matches the code.

Core08 hardcodes HERE / "claude-code" / "acs_adapter.py" in five places, so Cursor and NAT have zero adapter coverage in the suite.

The load-bearing consequence: if you update the HOOKS list to eight for #21, both tests pass instantly and vacuously, because the Guardian returns allow from INFORMATIONAL_METHODS and the malformed check never leaves the process. The suite stays green and all three adapters stay non-conformant.

Spec citations by line number

The docstrings cite conformance.md by line (:4 says "lines 13-26", then :195, :255, :376, :465, :592, :694, :781, :871, :1209, :1276).

#21 is a same-line-count edit. Both files are 89 lines and the diff is exactly 19,20c19,20 and 25,26c25,26. So every citation stays numerically valid while four of them start quoting text that no longer exists, and a reviewer spot-checking "is conformance.md:19 still the hook-taxonomy bullet?" gets yes and moves on.

Compounding it, adapter_tests.yml triggers on adapters/**, specification/**, and itself. docs/** isn't there, so merging #21 runs zero tests.

Two fixes, both cheap. Add docs/spec/** to the trigger paths. Then add a test that pulls each docstring's quoted fragment and asserts it's a substring of the live conformance.md line. That's maybe thirty lines and it turns this whole class of drift into a red build.

Smaller things, grouped

NAT's post_invoke ignores default_deny. All three failure paths at nat/acs_adapter.py:680-711 return None with no posture check, while workflow.yml.example:10 sets default_deny: true. pre_invoke gets this right at :618-629 for the identical condition. So the output-redaction gate is unconditionally fail-open in the config you ship as the example. The audit type is also post_invoke_unreachable rather than fail_open_bypass, so any rule written against the documented label misses it.

An unknown or missing disposition allows with no audit in all three adapters. specification.md:158 says "Every step that proceeds without a decision MUST be recorded as an audit event," and the fail-open branch (which is the shipped default) has no coverage.

Observation-only hooks are advertised as enforceable. All three put them in methods_implemented, and example_guardian.py:488 echoes that straight back as methods_evaluated. A policy author writes a DENY rule on steps/agentResponse to stop exfiltration in an assistant message, and it silently never fires. The mapping.md files are honest about this in prose, but the handshake is what a Guardian reads at runtime and it has no way to mark a method observation-only.

The handshake is fetched, never verified, cached for an hour, and never read. ensure_session_handshake (acs_common.py:484-503) writes the ServerHello to disk without calling verify_signature, and every adapter discards the return value. So the Guardian's on_decision_failure, timeout_config, skew_window_ms, and profiles_accepted all have no effect, and the posture comes from a local env var instead. SECURITY.md T11 argues the advisory handshake prevents a signing-downgrade attack, and that reasoning is right for signing and backwards for posture: signing should be governed by whoever holds the key, and posture by whoever enforces policy.

A readable-but-unopenable secret file silently downgrades both ends to unsigned. acs_common.py:150-154 catches OSError and returns b"", sign_envelope then returns the envelope unsigned with no warning, and the Guardian's check_signature returns early in "local-dev mode." A volume that fails to mount turns off the only integrity control ACS-Core mandates, on both sides, silently. The startup guard at example_guardian.py:722 runs once and won't catch a mid-life loss.

The replay cache never shrinks. evict_old_request_ids deletes from st.seen_request_ids, then persist() at :287-290 merges from disk and re-adds exactly what was deleted. _load() re-parses the whole file per request, so cost grows quadratically until it trips the 5s timeout, which is a transport failure, which is a fail-open.

A renamed upstream hook silently disables enforcement. acs_adapter.py:404-405 and cursor/acs_adapter.py:542-543 both return 0 with no audit event. Every other bypass in those files emits one. Cursor renames beforeShellExecution, the adapter goes quiet, and the Guardian's chain looks like a quiet session rather than an ungoverned one. One audit_event("unmapped_hook_event", ...) line plus a KNOWN_UNMAPPED set to keep the intentional ones quiet.

defer passes through raw on the one hook that gates. PRETOOL_PERMISSION_MAP at :87-89 maps "defer": "defer", and I don't believe Claude Code's permissionDecision accepts that value. Worth verifying against the current hook schema rather than taking my word for it. Note the asymmetry inside the same file: _translate_posttool:330-332 and _translate_user_prompt:341 both convert defer to a block, and Cursor maps it to ask at cursor/acs_adapter.py:119 with the comment "no native defer," which looks like the right shape.

Dependencies float despite the header saying otherwise. adapter_tests.yml:5 says "Pinned dependencies," and four of six are ranges (jsonschema>=4.20,<5, rfc8785>=0.1,<1, rfc3339-validator>=0.1,<1, ruamel.yaml>=0.17). Both actions use mutable major tags rather than SHAs. The comment at 66 to 73 reasons carefully about why NAT must be pinned and then doesn't generalize it. There's also no permissions: block, unlike the sibling sync_version.yml which declares one.

free_port() is a bind-then-release race. _common/test_harness.py:60-64 closes the socket before returning, so the port is free between the return and the Guardian's bind. It'll flake under runner contention and surface as server not up on ..., which reads like a startup bug. The workflow also sets no timeout-minutes, so a hang burns the 360-minute default across five matrix jobs.

Disclosure path and ownership

adapters/SECURITY.md:227-230 says to "Open an issue ... with the security label, or email the maintainers listed in CODEOWNERS." CONTRIBUTING.md:65 says "Do not file public issues for security vulnerabilities." And there's no CODEOWNERS at root or in .github/.

So a researcher who finds a bypass in an adapter that's shell-spawned and holds the HMAC secret follows the nearest instruction file and posts a public zero-day. I'd delete that paragraph, point at CONTRIBUTING.md:65, and add a root SECURITY.md so GitHub surfaces the private path in the Security tab. The file is a threat model rather than a VDP, so THREAT_MODEL.md might be the more honest name.

On ownership: there's no CODEOWNERS, no .github/dependabot.yml, and the adapter dependencies live in loose requirements*.txt files outside pyproject.toml, so uv.lock covers none of them. nvidia-nat-core==1.7.0 pulls the LangChain tree, and when a CVE lands there nothing notifies anyone. CONTRIBUTING.md's Local Development section still lists three mkdocs commands and doesn't mention the test suite at all, so a new contributor won't know it exists.

There's also no version stamp on any adapter (grep -rn "__version__\|ADAPTER_VERSION" on adapters/ is empty) and no changelog. Since distribution is copy-paste, a defect here is an incident you can't scope: no way to ask an adopter what version they have, no way for them to find out, and no artifact to roll back to. acs_common.py:653-657 keeps a back-compat alias "so out-of-tree adapter forks aren't broken by the rename," so forks are clearly anticipated, and there's no mechanism to identify or update them.

Ordering

#21 rewrites the four conformance.md lines this suite cites, so I'd let that land first and update the citations here as part of the rebase. I've left notes on #21 and #20 with the details.

If it helps, the sequence I'd suggest is: fix the CI pipefail and ACS_SPEC_DIR first so the suite tells the truth about the rest, then re-run and see what's actually red before working through anything else here.

Last procedural note: CONTRIBUTING.md:42 asks for git commit -s and none of the 21 commits here have a sign-off. Probably worth a DCO check in CI rather than asking three PRs to rebase separately.

[afogel]

Five findings from running the branch , with four of the five are one mistake in different places.

1. A Guardian DENY with a trailing space executes the tool call. §6.4:158 says an arrived decision must be honored regardless of posture, and §6.3:146 already rules that an unusable one is a DENY.
2. Failing closed on Stop and SubagentStop emits {"decision":"block"}, which Claude Code reads as "do not stop, continue". subagent-stop.json:5 marks both hooks not decision-eligible.
3. settings.json.example passes all four settings through a per-hook "env" object that Claude Code does not implement, so a copied config runs unsigned, fail-open, with no audit sink. The test guarding that file asserts the same discarded field.
4. Without rfc8785 the adapter exits 1 with empty stdout, which Claude Code treats as non-blocking, so the tool runs with no audit event and no regard for ACS_DEFAULT_DENY.
5. The cached ServerHello is read without verifying its signature, so the observed agent flips its own fail posture by editing one word in a predictable path, or by touching an empty .failed marker.

The tests have a similar blind spot. The suite covers a Guardian that says nothing, thoroughly, across all three adapters. It does not cover a Guardian that says something unusable, or a framework that ignores what the config tried to say. §6.4:156 and §6.4:158 draw exactly that line, and the suggested expectations put it under test.

Two notes on scope, neither one a code comment.

§6.4:156 lists "malformed response" among the transport failures, which is where treating an unreadable decision as a decision failure finds cover. Line 158 then says an arrived decision must be honored regardless of posture. Those rub against each other for the case in finding 1. A clarifying sentence in §6.4 would turn that comment from an argument into a bug report, and settle the same question for whoever writes a fourth adapter. It fits with #32 rather than this PR.

This branch also carries three normative schema edits: subagent-stop.json drops final_chain_hash from required, response-envelope.json adds a signature to the error object, and otel-mapping.json moves an attribute to optional. The reasoning behind each looks sound. The PR description still says the change set touches no normative spec text. They want their own PR and a spec-owner decision, especially with #21, #31 and #32 open on adjacent ground.

[afogel]

A DENY with a trailing space executes the tool call.

translate_response normalizes the Guardian's verdict with .lower() and no .strip(). "deny " misses KNOWN_DECISIONS, gets an audit line, then falls through to the fail-open branch and returns {}. Empty stdout means Claude Code applies no decision and runs the tool.

Two lines in your own Core04b class reproduce it:

with self._scripted_guardian({"decision": "deny ", "reasoning": "policy hit"}) as g:
    r = self._run_claude(g)      # r["out"] == {}: no verdict, tool proceeds

Any disposition ACS adds after v0.1 behaves the same way, as does a "deny" that picked up whitespace crossing a proxy or a queue. Same code at cursor/acs_adapter.py:592, nat/acs_adapter.py:724 and nat/acs_adapter.py:830, where the event name is unknown_disposition and should move with the fix.

What the spec says

The three clauses that decide this, at the lines they live on.

docs/spec/instrument/specification.md:156, where the fail-open posture comes from:

A step suffers a decision failure when no usable decision arrives within the negotiated timeout: the Guardian stays silent, the transport fails (connection refused, TLS failure, malformed response), or the Guardian returns an error instead of a decision. All three resolve the same way: the Observed Agent applies the deployment's failure posture, declared as on_decision_failure in the handshake (§4) and defaulting to proceed (fail-open) so that a slow, erroring, or unreachable Guardian does not halt production.

docs/spec/instrument/specification.md:158, the next paragraph:

Every step that proceeds without a decision MUST be recorded as an audit event, so the bypass is visible rather than silent. When a decision does arrive within the timeout, the agent MUST honor it regardless of the posture.

docs/spec/instrument/specification.md:146 already settles what to do with a verdict that arrived and cannot be used. It is written about a malformed modifications object:

A Guardian MUST NOT emit a modifications object that violates either rule. An Observed Agent that receives one cannot determine the Guardian's intent and MUST fail closed, treating the decision as DENY, and SHOULD record an audit event.

Where the implementation parts ways

A decision arrived, inside the timeout, correctly signed. Line 158 forbids the posture from deciding what happens to it, and this code lets the posture decide. The adapter has widened line 156's "no usable decision arrives" to cover "a decision I could not parse", which turns a Guardian that is talking into a Guardian that is silent.

Line 146 gives the rule for the arrived-and-unusable case, and the answer there is DENY with an audit event, with no mention of posture. An unreadable decision string is that case with a different field name, so the fix needs no new spec text.

Suggested change

	decision = (result.get("decision") or "").lower()
	reasoning = result.get("reasoning", "")
	modifications = result.get("modifications", {})
	# Unknown or missing disposition: ALWAYS audited — the fail-open
	# branch is the shipped default and §6.4 says every step that
	# proceeds without a decision MUST be recorded (PR #22 review:
	# previously the fail-open path here allowed with no audit event).
	if decision not in KNOWN_DECISIONS:
	audit_event("unknown_disposition",
	disposition=decision or "(missing)", hook=hook_event,
	posture="deny" if _effective_default_deny() else "proceed")
	if _effective_default_deny():
	reason = f"unknown Guardian disposition '{decision}' (default-deny)"
	if hook_event == "PreToolUse":
	return _pretool_response("deny", reason)
	if hook_event in BLOCK_RESPONSE_HOOKS:
	return _block_response(reason)
	decision = (result.get("decision") or "").strip().lower()
	reasoning = result.get("reasoning", "")
	modifications = result.get("modifications", {})
	# The decision ARRIVED and cannot be read. That is not a §6.4:156
	# decision failure, and §6.4:158 says an arrived decision MUST be
	# honored regardless of posture, so the fail posture does not apply.
	# §6.3:146 gives the rule for the same situation in `modifications`:
	# fail closed as DENY, record an audit event. Applied here.
	if decision not in KNOWN_DECISIONS:
	audit_event("unusable_disposition",
	disposition=decision or "(missing)", hook=hook_event)
	reason = (f"unusable Guardian disposition '{decision}', "
	f"failing closed per §6.3:146")
	if hook_event == "PreToolUse":
	return _pretool_response("deny", reason)
	# Stop and SubagentStop are deliberately absent. Claude Code reads
	# {"decision":"block"} on those as "do not stop", so a block there
	# increases activity instead of preventing it.
	if hook_event in ("PostToolUse", "UserPromptSubmit"):
	return _block_response(reason)
	return {}

Two side effects worth naming. The trailing return {} means an unreadable disposition on an informational hook (SessionStart, SessionEnd, Notification) stops short of the additional_context handling at lines 617-622, which I think is right but is a change. And cursor/acs_adapter.py:600 and nat/acs_adapter.py:857 still emit unknown_disposition for the same condition, so the event name wants renaming in all three or none.

[afogel]

The suite has no expectation for a Guardian that answers with something unusable.

Every fail-posture test in the tree covers a Guardian that says nothing: claude-code/tests/test_adapter.py:209, cursor/tests/test_adapter.py:162, nat/tests/test_live.py:185. All three are correct and worth keeping. None of them covers a verdict that arrived and cannot be read, and the spec treats the two cases in opposite directions.

docs/spec/instrument/specification.md:156 sends the silent case to the posture:

A step suffers a decision failure when no usable decision arrives within the negotiated timeout [...] the Observed Agent applies the deployment's failure posture, declared as on_decision_failure in the handshake (§4) and defaulting to proceed (fail-open).

docs/spec/instrument/specification.md:158 takes the arrived case away from the posture entirely:

When a decision does arrive within the timeout, the agent MUST honor it regardless of the posture.

One cell of that table is pinned, test_defer_substitutes_ask_cursor at line 899. Nothing pins line 158 itself, so no test notices when an arrived verdict falls through to the posture.

This appends to Core04b_DispositionsLiveThroughAdapters, which already has the fixtures. All five subtests go red on this commit and green with the translate_response fix applied. The split on unreadable matters: after that fix the padded variants normalize to a valid DENY and emit no audit event, so asserting one for them would keep the test red forever.

Suggested change

	f"cursor maps defer→ask per mapping.md; got {r['out']!r}")
	f"cursor maps defer→ask per mapping.md; got {r['out']!r}")
	def test_unusable_disposition_denies_regardless_of_posture(self) -> None:
	"""§6.4:158 requires an arrived decision to be honored regardless of
	the posture. §6.3:146 makes one whose intent cannot be determined a
	DENY plus an audit event. Posture stays at the shipped fail-open default on
	purpose: it must have no effect on a decision that arrived."""
	for bad, unreadable in (("deny ", False), (" deny", False),
	("DENY\n", False), ("quarantine", True),
	("", True)):
	with self.subTest(disposition=bad):
	with self._scripted_guardian(
	{"decision": bad, "reasoning": "policy hit"}) as g:
	r = self._run_claude(g)
	hso = r["out"].get("hookSpecificOutput", {})
	self.assertEqual(hso.get("permissionDecision"), "deny",
	f"{bad!r} must deny: normalization handles a padded verdict, "
	f"§6.3:146 handles one that cannot be read. Got {r['out']!r}, "
	f"and empty output runs the tool.")
	if unreadable:
	self.assertIn("unusable_disposition", r["stderr"],
	f"{bad!r} cannot be read at all, so §6.3:146's audit "
	f"event is required")

[afogel]

Failing closed on Stop tells the agent to keep working.

Stop and SubagentStop sit in this set, so both _emit_deny (via acs_adapter.py:815) and _translate_session_stop:577 answer with {"decision": "block", "reason": ...}.

Observed with the Guardian down and ACS_DEFAULT_DENY=1:

PreToolUse   -> {"hookSpecificOutput": {"permissionDecision": "deny", ...}}   correct
Stop         -> {"decision":"block","reason":"ACS adapter: decision-failure (transport_failure)"}
SubagentStop -> {"decision":"block","reason":"ACS adapter: decision-failure (transport_failure)"}

Claude Code's hooks reference gives the effect of a block on this event in its per-event table:

Stop | Yes | Prevents Claude from stopping, continues the conversation

The same page lists Stop and SubagentStop under "Top-level decision" with decision: "block" plus reason, and reason is returned to the model. So a dead Guardian under fail-closed tells the agent to keep going, and hands it "ACS adapter: decision-failure (transport_failure)" as the reason.

The agent cannot finish, and subagents never terminate. The setting exists to stop activity when the supervisor is gone. Right now it causes unbounded activity when the supervisor is gone. wire.py:425-426 applies --default-deny to every wired hook rather than only the gates, so the shipped tooling reaches this state.

What the spec says

The schemas already state that these hooks carry no decision.

specification/v0.1.0/hooks/subagent-stop.json:5:

Fires when an in-process subagent terminates. [...] This hook lets the parent's audit chain reference the subagent's terminal state without merging the two chains. Not decision-eligible — the subagent has already terminated.

docs/spec/instrument/hooks.md:290, on turn end, for the same reason:

Decision: Not decision-eligible — the turn has already happened.

For contrast, docs/spec/instrument/hooks.md:226 is what a decision-eligible hook looks like:

Decision: Decision-eligible. Guardian MAY DENY — refuse the subagent spawn, e.g. because the intent_derivation would grant capabilities the parent's Intent.parsed does not authorize.

adapters/claude-code/mapping.md:40 agrees and calls these hooks observation-only.

Where the implementation parts ways

The spec says the event reports something that already finished, so no verdict applies to it. The adapter emits a verdict anyway, and the framework reads that verdict as an instruction to continue. Every other path in this file gets the direction right. These two invert it, and they invert it only when an operator asks for stricter behavior, which is the worst possible trigger.

Suggested change

	# Hooks whose deny shape is {"decision": "block", "reason": "..."}
	# (i.e., everything except PreToolUse, which uses hookSpecificOutput.permissionDecision).
	BLOCK_RESPONSE_HOOKS = frozenset({
	"PostToolUse", "UserPromptSubmit", "Stop", "SubagentStop",
	})
	# Hooks whose deny shape is {"decision": "block", "reason": "..."} AND whose
	# block actually prevents the action.
	ENFORCEABLE_BLOCK_HOOKS = frozenset({
	"PostToolUse", "UserPromptSubmit",
	})
	# Not decision-eligible per the hook schemas. subagent-stop.json:5 says
	# "Not decision-eligible, the subagent has already terminated", and
	# hooks.md:290 says the same for turn end. Claude Code reads
	# {"decision":"block"} on these as "do not stop, continue the
	# conversation", so emitting one inverts a fail-closed posture into
	# unbounded activity. A DENY or a decision failure on these hooks is
	# recorded and nothing else.
	AUDIT_ONLY_HOOKS = frozenset({
	"Stop", "SubagentStop",
	})

Two readers of the old name exist, both in this file, and nothing else in the tree references it. acs_adapter.py:608 disappears if the translate_response suggestion is taken; commit this one alone and that line becomes a NameError. acs_adapter.py:815 becomes:

    if hook_name in AUDIT_ONLY_HOOKS:
        audit_event("unenforceable_decision", hook=hook_name, reason=msg)
        return
    if hook_name == "PreToolUse":
        _emit(_pretool_response("deny", msg))
    elif hook_name in ENFORCEABLE_BLOCK_HOOKS:
        _emit(_block_response(msg))

_block_response's docstring at acs_adapter.py:206 still lists Stop and SubagentStop among its callers and goes stale with this change.

Expectation to add in claude-code/tests/test_adapter.py, importing ProgrammableGuardian alongside the existing test_harness names on line 27. Four subtests, two hooks by two cases, all red on this commit:

    def test_audit_only_hooks_never_emit_a_block(self) -> None:
        """Stop and SubagentStop are not decision-eligible
        (subagent-stop.json:5, hooks.md:290). Claude Code reads
        {"decision":"block"} on them as "do not stop, continue", so a block
        inverts fail-closed into unbounded activity. Neither a Guardian DENY
        nor a decision failure may produce one."""
        for hook in ("Stop", "SubagentStop"):
            with self.subTest(hook=hook, case="guardian denies"):
                g = ProgrammableGuardian()
                g.handlers["__default__"] = lambda req: {
                    "type": "final", "acs_version": "0.1.0",
                    "request_id": req["params"]["request_id"],
                    "chain_hash": "0" * 64, "decision": "deny",
                    "reasoning": "policy hit",
                }
                with g:
                    rc, out, err = self._run_adapter(
                        _claude_code_event(hook),
                        env_overrides={"ACS_GUARDIAN_URL": g.url(),
                                       "ACS_HMAC_SECRET": g.hmac_secret})
                self.assertNotIn('"decision": "block"', out,
                    f"{hook} carries no decision; a block tells Claude Code to "
                    f"keep going. Got {out!r}")
                self.assertIn("unenforceable_decision", err,
                    "the verdict must still be recorded")

            with self.subTest(hook=hook, case="guardian unreachable"):
                rc, out, err = self._run_adapter(
                    _claude_code_event(hook),
                    env_overrides={"ACS_GUARDIAN_URL": "http://127.0.0.1:1/acs",
                                   "ACS_DEFAULT_DENY": "1"})
                self.assertNotIn('"decision": "block"', out,
                    f"fail-closed on {hook} must not emit a block, which reads "
                    f"as 'do not stop'. Got {out!r}")
                self.assertIn("ACS_AUDIT", err)

[afogel]

A Guardian DENY here becomes an instruction to continue.

This is the other half of the BLOCK_RESPONSE_HOOKS comment. _block_response on Stop or SubagentStop emits {"decision": "block", "reason": ...}, and Claude Code's hooks reference reads a block on those events as:

Stop | Yes | Prevents Claude from stopping, continues the conversation

with reason handed back to the model. So a Guardian that denies a terminated subagent gets the agent to keep going, carrying the denial text as its next instruction.

specification/v0.1.0/hooks/subagent-stop.json:5 says no verdict applies at this point:

Not decision-eligible — the subagent has already terminated.

The honest response records the verdict and emits nothing. _block_response's docstring at acs_adapter.py:206 lists these two hooks among its callers, so it wants updating too. The Guardian's decision still reaches the audit chain, which is the part that has value here, and the framework gets no signal it would misread.

Suggested change

	def _translate_session_stop(decision: str, reasoning: str,
	modifications: dict) -> dict[str, Any]:
	"""Stop / SubagentStop — only deny matters; allow is the default."""
	if decision == "deny":
	return _block_response(reasoning or "blocked by Guardian")
	return {}
	def _translate_session_stop(decision: str, reasoning: str,
	modifications: dict) -> dict[str, Any]:
	"""Stop / SubagentStop are not decision-eligible (subagent-stop.json:5:
	"the subagent has already terminated"). A DENY cannot be enforced here,
	and Claude Code reads {"decision":"block"} on these events as "do not
	stop, continue the conversation", so emitting one would turn a denial
	into an instruction to keep working. Record it and emit nothing."""
	if decision in ("deny", "ask", "defer"):
	audit_event("unenforceable_decision", decision=decision,
	reason=reasoning or "(none)")
	return {}

[afogel]

This file passes every setting through a field Claude Code discards.

All eight hook entries carry a per-hook "env" object holding ACS_GUARDIAN_URL, ACS_HMAC_SECRET_FILE, ACS_AUDIT_FILE, and on the gates ACS_DEFAULT_DENY.

Claude Code's hooks reference lists the command-hook fields as command, args, async, asyncRewake, shell, plus the common type, if, timeout, statusMessage, once. There is no env field. The same page states:

Handlers run in the current directory with Claude Code's environment.

Claude Code never reads that key, so none of those settings reach the process, on any of the eight hooks.

Run the adapter the way Claude Code runs it, with the parent environment and nothing added, while a permissive unsigned listener holds the default port. Not the example Guardian, which denies this command at example_guardian.py:166 and refuses to start without a secret at :852. Any other process that answers allow:

env -u ACS_GUARDIAN_URL -u ACS_HMAC_SECRET -u ACS_HMAC_SECRET_FILE \
    -u ACS_DEFAULT_DENY -u ACS_AUDIT_FILE \
    python3 adapters/claude-code/acs_adapter.py <<'EOF'
{"session_id":"s-9","hook_event_name":"PreToolUse","tool_name":"Bash",
 "tool_input":{"command":"rm -rf /home/u"},"tool_use_id":"tu-1","cwd":"/tmp"}
EOF

I get permissionDecision: allow from an unsigned reply, and one line on stderr:

ACS_AUDIT {"acs_audit_event": "unsigned_mode", "detail": "no ACS_HMAC_SECRET / ACS_HMAC_SECRET_FILE configured — envelopes are UNSIGNED and any local process that binds the Guardian address is trusted"}

The adapter is right, and it is talking to a stream nobody collects, because ACS_AUDIT_FILE came from the same dead block.

What the spec says

Signing is not optional at this tier. docs/spec/instrument/specification.md, §10:

A signature over the §10 canonical input is REQUIRED in ACS-Core. The signature envelope is { algorithm, value, key_id } [...] HMAC-SHA256 is the baseline that satisfies the requirement.

docs/spec/conformance.md:23, the same requirement in the Core checklist:

Baseline integrity: every request and response carries a signature over the canonical envelope ([§10]). HMAC-SHA256 with an HKDF-derived per-session key from deployment-provided key material is the baseline.

The audit half of the fail-open trade is also a MUST, docs/spec/instrument/specification.md:158:

Every step that proceeds without a decision MUST be recorded as an audit event, so the bypass is visible rather than silent.

Where the implementation parts ways

Copy this file, as its own _comment block instructs, and you get unsigned envelopes, which §10 makes non-conformant. You also get gate hooks at the fail-open default rather than the fail-closed one the comment promises, and audit events on an uncollected stream. The adapter code is fine. The configuration never reaches it.

wire.py:117-147 already builds the correct inline form, and this file's comment claims it was generated that way, so the artifact needs regenerating. Below is the PreToolUse entry in wire.py's exact ordering and marker. The other seven hooks take the same shape, without ACS_DEFAULT_DENY=1 on the six non-gate hooks. Commit it with the regenerated file rather than on its own, or the example ships two wiring forms at once and the test below stays red on UserPromptSubmit.

Suggested change

	"PreToolUse": [
	{
	"matcher": "*",
	"hooks": [
	{
	"type": "command",
	"command": "python3 /path/to/acs_adapter.py",
	"env": {
	"ACS_GUARDIAN_URL": "http://127.0.0.1:8787/acs",
	"ACS_HMAC_SECRET_FILE": "/path/to/.acs/hmac.key",
	"ACS_AUDIT_FILE": "/path/to/.acs/audit.log",
	"ACS_DEFAULT_DENY": "1"
	}
	}
	]
	}
	],
	"PreToolUse": [
	{
	"matcher": "*",
	"hooks": [
	{
	"type": "command",
	"command": "ACS_GUARDIAN_URL=http://127.0.0.1:8787/acs ACS_HMAC_SECRET_FILE=/path/to/.acs/hmac.key ACS_DEFAULT_DENY=1 ACS_AUDIT_FILE=/path/to/.acs/audit.log python3 /path/to/acs_adapter.py # acs-adapter-wired"
	}
	]
	}
	],

Worth one more test after that. Assert the checked-in example equals wire.py's output for the same arguments. The generator and the artifact have now drifted twice, this time and the earlier missing Notification.

[afogel]

This assertion reads a field Claude Code discards, so it passes for a config that governs nothing.

entries[0]["hooks"][0].get("env", {}) inspects a key that is not part of Claude Code's command-hook schema. Its hooks reference lists command, args, async, asyncRewake, shell, plus the common type, if, timeout, statusMessage, once, and states:

Handlers run in the current directory with Claude Code's environment.

So this test certifies the example as fail-closed while the example sets nothing at all. Run the adapter with the parent environment and no ACS_* variables, against any process on the default port that answers allow, and rm -rf /home/u comes back permitted on an unsigned reply.

Three requirements go unenforced by the file this test guards. docs/spec/instrument/specification.md, §10:

A signature over the §10 canonical input is REQUIRED in ACS-Core.

docs/spec/instrument/specification.md:158:

Every step that proceeds without a decision MUST be recorded as an audit event, so the bypass is visible rather than silent.

And the fail-closed posture on the gates, which is what this test set out to check.

Asserting on the command string tests the only channel Claude Code passes through.

Suggested change

	env = entries[0]["hooks"][0].get("env", {})
	self.assertEqual(env.get("ACS_DEFAULT_DENY"), "1",
	f"gate hook {hook} in the example must set ACS_DEFAULT_DENY=1")
	entry = entries[0]["hooks"][0]
	self.assertNotIn("env", entry,
	"Claude Code's command-hook fields are command, args, async, "
	"asyncRewake, shell plus the common ones. There is no `env`, so "
	"anything there is dropped and the hook runs with Claude Code's "
	"own environment. Use wire.py's inline VAR=value form.")
	cmd = entry["command"]
	self.assertIn("ACS_DEFAULT_DENY=1", cmd,
	f"gate hook {hook} must set ACS_DEFAULT_DENY=1 in the command "
	f"string, the only channel Claude Code passes through")
	for required in ("ACS_HMAC_SECRET_FILE=", "ACS_AUDIT_FILE=",
	"ACS_GUARDIAN_URL="):
	self.assertIn(required, cmd,
	f"{hook} must carry {required} inline. Unset means unsigned "
	f"envelopes, which §10 makes non-conformant, and audit "
	f"events that land nowhere, which §6.4:158 requires")

[afogel]

A missing dependency turns every hook into a silent no-op.

Making rfc8785 hard is the right call, and §10 permits no alternative canonicalization. The placement is the problem. The raise happens at module import, before main() exists, so no code in this repo runs.

$ ACS_DEFAULT_DENY=1 python3 adapters/claude-code/acs_adapter.py < pretooluse.json
exit code : 1
stdout    : ''
stderr    : ImportError: ACS adapters require the `rfc8785` package ...
audit line: NONE

Claude Code's hooks reference is explicit about exit 1:

For most hook events, exit code 2 is the only exit code that blocks through the code alone. Without valid JSON on stdout, Claude Code treats exit code 1 as a non-blocking error and proceeds with the action, even though 1 is the conventional Unix failure code.

So the tool call runs. ACS_DEFAULT_DENY=1 is never read, because the code that reads it did not load. No audit event exists, because the module that writes audit events is the one that failed.

adapters/claude-code/ and adapters/cursor/ ship no requirements.txt, and their READMEs point operators at adapters/requirements-test.txt, so meeting this on a first run is likely rather than exotic.

What the spec says

Proceeding here is legal. Proceeding silently is not, and ignoring the operator's posture is not.

docs/spec/instrument/specification.md:156:

A step suffers a decision failure when no usable decision arrives within the negotiated timeout [...] the Observed Agent applies the deployment's failure posture, declared as on_decision_failure in the handshake (§4) and defaulting to proceed (fail-open).

docs/spec/instrument/specification.md:158:

Every step that proceeds without a decision MUST be recorded as an audit event, so the bypass is visible rather than silent.

docs/spec/conformance.md:24, the same obligation in the Core checklist:

Decision honoring: the Observed Agent MUST wait for the Guardian's decision up to the negotiated timeout and apply it; on a decision failure (timeout, transport failure, or an error without a decision) it applies the on_decision_failure posture (default proceed, fail-open) and records every fail-open proceed as an audit event.

Where the implementation parts ways

An adapter that cannot load never sends a request. No decision arrives, so this is a decision failure and the posture governs it. Neither obligation is met today. §6.4:158 requires an audit event for the proceed, and §6.4:156 requires the deployment's posture to decide it.

Two notes for the fix. A blanket exit 2 is wrong, because exit 2 on Stop blocks the stop, which means the agent keeps working. And the degraded path cannot call audit_event, since that lives in the module that failed to import, so it writes its own line with the standard library alone.

Suggested change

	# Bootstrap shared helpers from sibling adapters/_common/
	sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "_common"))
	from acs_common import ( # noqa: E402
	ACS_VERSION,
	MAX_REQUEST_BODY_BYTES,
	audit_event,
	coerce_uuid,
	ensure_session_handshake,
	guardian_error_cause,
	is_guardian_refusal,
	iso8601_now,
	response_matches_request,
	sign_envelope,
	validate_guardian_url,
	verify_signature,
	)
	# Bootstrap shared helpers from sibling adapters/_common/
	sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "_common"))
	try:
	from acs_common import ( # noqa: E402
	ACS_VERSION,
	MAX_REQUEST_BODY_BYTES,
	audit_event,
	coerce_uuid,
	ensure_session_handshake,
	guardian_error_cause,
	is_guardian_refusal,
	iso8601_now,
	response_matches_request,
	sign_envelope,
	validate_guardian_url,
	verify_signature,
	)
	except ImportError as _bootstrap_error:
	# acs_common hard-requires rfc8785 (§10 permits no alternative
	# canonicalization), so a missing dependency kills this module before
	# main() runs. Claude Code proceeds on any nonzero exit except 2, so
	# dying here is an ungoverned step with no audit event (against
	# §6.4:158) that also ignores ACS_DEFAULT_DENY (against §6.4:156).
	# Handled with the standard library only: audit_event and the response
	# builders live in the module that failed to load.
	def _degraded_exit() -> int:
	if os.environ.get("ACS_DISABLED") == "1":
	# The documented kill switch is read in main(), which never runs
	# on this path. An operator who set it must still get a bypass.
	sys.stderr.write("acs-adapter: ACS_DISABLED=1, hook bypassed\n")
	return 0
	try:
	_event = json.loads(sys.stdin.read() or "{}")
	except ValueError:
	_event = {}
	_hook = _event.get("hook_event_name", "")
	_deny = os.environ.get("ACS_DEFAULT_DENY", "0") == "1"
	_line = "ACS_AUDIT " + json.dumps({
	"acs_audit_event": "adapter_unavailable",
	"hook": _hook,
	"posture": "deny" if _deny else "proceed",
	"error": str(_bootstrap_error).split("\n")[0],
	"detail": "adapter could not load; no envelope was sent",
	})
	sys.stderr.write(_line + "\n")
	_sink = os.environ.get("ACS_AUDIT_FILE", "").strip()
	if _sink:
	try:
	_fd = os.open(_sink, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
	with os.fdopen(_fd, "a") as _f:
	_f.write(_line + "\n")
	except OSError:
	pass
	if not _deny:
	return 0
	if _hook == "PreToolUse":
	print(json.dumps({"hookSpecificOutput": {
	"hookEventName": "PreToolUse",
	"permissionDecision": "deny",
	"permissionDecisionReason":
	"ACS adapter unavailable (dependency missing); "
	"failing closed per the deployment posture",
	}}))
	return 0
	if _hook == "UserPromptSubmit":
	print(json.dumps({
	"decision": "block",
	"reason": "ACS adapter unavailable (dependency missing); "
	"failing closed per the deployment posture",
	}))
	return 0
	return 0
	if __name__ == "__main__":
	raise SystemExit(_degraded_exit())
	raise

Shipping a requirements.txt in adapters/claude-code/ and adapters/cursor/ pinning rfc8785==0.1.4 keeps most people off this path.

Expectation to add in adapters/_common/tests/test_security.py. Both subtests go red on this commit, the first because nothing is written anywhere, the second because the posture is never consulted:

    def test_adapter_that_cannot_load_audits_and_honors_the_posture(self) -> None:
        """§10 makes rfc8785 mandatory, so its absence is not a degraded mode
        the adapter may take silently. Claude Code proceeds on any nonzero exit
        except 2, so a bare ImportError is an ungoverned step. §6.4:158 requires
        an audit event for it, and §6.4:156 puts it under the deployment's
        posture."""
        shadow = Path(self.tmpdir) / "shadow"
        shadow.mkdir()
        (shadow / "rfc8785.py").write_text(
            "raise ImportError('simulating an environment without rfc8785')\n")
        event = json.dumps({"session_id": "s-1", "cwd": "/tmp",
                            "hook_event_name": "PreToolUse", "tool_name": "Bash",
                            "tool_input": {"command": "rm -rf /home/u"}})

        for posture, expect_deny in (("1", True), ("0", False)):
            with self.subTest(ACS_DEFAULT_DENY=posture):
                env = os.environ.copy()
                env["PYTHONPATH"] = str(shadow)
                env["ACS_DEFAULT_DENY"] = posture
                p = subprocess.run([sys.executable, str(CLAUDE_ADAPTER)],
                                   input=event, capture_output=True,
                                   text=True, env=env, timeout=15)
                self.assertIn("adapter_unavailable", p.stderr,
                    "§6.4:158 requires every step that proceeds without a "
                    "decision to be recorded; today this path emits nothing")
                if expect_deny:
                    self.assertIn('"permissionDecision": "deny"', p.stdout,
                        "the deployment set the posture to deny per §6.4:156, "
                        "so an unloadable adapter must not let the tool run")
                else:
                    self.assertEqual(p.stdout.strip(), "",
                        "fail-open is the §6.4 default, so proceeding is correct "
                        "here as long as it is audited")

[afogel]

The observed agent can flip its own fail posture by editing a file.

ensure_session_handshake caches the ServerHello at ~/.cache/acs-adapter-handshake/<sha256(session_id + "|" + guardian_url)>.json. This read path returns json.load(f) and nothing else. The signature verification added in this round sits at line 672, on the fresh-fetch branch only. The failure-marker branch just below returns None with no audit event.

One session. Guardian alive for the first event, its ServerHello declaring on_decision_failure: deny. Then killed:

A) honest cached ServerHello                     -> permissionDecision "deny"   correct
B) "deny" edited to "proceed" in the cache file  -> empty stdout, tool runs     fail_open_bypass
C) cache deleted, empty .failed marker touched   -> empty stdout, tool runs     fail_open_bypass

The agent reads session_id from its own hook payloads and guardian_url from settings.json, so it can compute the filename. It runs as the same user as the hook process, so 0600 on the file and 0700 on the directory keep out every user except the one that matters. Case C needs no content at all, just an empty file with the right name, and it emits no audit event.

What the spec says

docs/spec/instrument/specification.md:75, on where this value comes from:

on_decision_failure is negotiated in the handshake, so it cannot govern a handshake that never completes. When handshake/hello fails [...] the Observed Agent applies its startup posture, configured out of band.

docs/spec/instrument/specification.md, §10, on what a response carries and what a verifier owes it:

A signature over the §10 canonical input is REQUIRED in ACS-Core.

A verifier MUST recompute this canonical form and MUST reject a signature that does not cover it (SIGNATURE_INVALID, §17.1).

docs/spec/conformance.md:23, the same rule in the Core checklist:

Baseline integrity: every request and response carries a signature over the canonical envelope.

docs/spec/instrument/specification.md:77, on the unguarded case that branch C produces:

A session started unguarded MUST be recorded in the deployment's own audit log — there is no Guardian to receive the event.

Where the implementation parts ways

The ServerHello is a response, so §10 requires a signature on it and requires the verifier to reject one that does not cover the envelope. The fetch path does exactly that. The read path discards the signature and trusts local file content, which means the posture is no longer negotiated with the Guardian in the sense §4.1 describes. It comes from a file the Observed Agent can write.

Branch C is the §4.1 unguarded-start case with no record, so it also misses the audit MUST at line 77.

The fix caches the whole signed envelope instead of the bare payload, then reuses the verify_signature defined at acs_common.py:325. Roughly twenty lines, no new dependencies. The write site at line 685 needs the matching change, in a separate comment.

Be precise about what this buys. Verification turns a silent self-downgrade into an audited one. It does not prevent it: a tamper-detected entry falls through to a re-handshake, which fails when the Guardian is down, and specification.md:75 puts that on the startup posture, whose default is proceed. Closing it fully needs either a deny startup posture or a rule that a tamper-detected entry forces deny. Worth saying which you mean. There is also a ceiling: verify_signature returns True for an unsigned envelope when no secret is configured (acs_common.py:334), so this binds only deployments that set one, which is the same gap as the settings.json.example comment.

Suggested change

	if cache.exists():
	try:
	mtime = cache.stat().st_mtime
	if (time.time() - mtime) <= _HANDSHAKE_CACHE_TTL_S:
	with open(cache) as f:
	return json.load(f)
	# Else: cache is stale, fall through to re-handshake
	except (json.JSONDecodeError, OSError):
	pass
	if failure_marker.exists():
	try:
	if (time.time() - failure_marker.stat().st_mtime) <= _HANDSHAKE_FAILURE_TTL_S:
	# Recent failure — fail fast instead of paying the
	# network timeout again on every hook event.
	return None
	except OSError:
	pass
	if cache.exists():
	try:
	mtime = cache.stat().st_mtime
	if (time.time() - mtime) <= _HANDSHAKE_CACHE_TTL_S:
	with open(cache) as f:
	cached = json.load(f)
	# §10 requires every response to carry a signature and the
	# verifier to reject one that does not cover the envelope.
	# This file sits at a predictable path writable by the
	# observed agent (same uid as this process), and its only
	# consumer is the fail posture, so trusting it unverified
	# lets the agent downgrade its own supervisor by editing one
	# word. Verify a cached envelope exactly like a fresh one.
	if not isinstance(cached, dict) or "result" not in cached:
	# Pre-0.1.2 cache held the bare payload, with no
	# signature to check. Treat as a miss and re-handshake.
	raise ValueError("legacy unsigned handshake cache entry")
	if not verify_signature(cached, session_id=session_id):
	audit_event("handshake_cache_signature_invalid",
	guardian_url=guardian_url, session_id=session_id,
	detail="cached ServerHello failed verification; "
	"re-handshaking")
	raise ValueError("cached ServerHello signature invalid")
	return (cached.get("result") or {}).get("payload")
	# Else: cache is stale, fall through to re-handshake
	except (json.JSONDecodeError, OSError, ValueError):
	pass
	if failure_marker.exists():
	try:
	if (time.time() - failure_marker.stat().st_mtime) <= _HANDSHAKE_FAILURE_TTL_S:
	# Recent failure. Fail fast rather than paying the network
	# timeout on every hook event. §4.1:77 requires a session
	# that starts unguarded to be recorded, and this branch is
	# that case, so it is audited rather than silent.
	audit_event("handshake_negative_cache_hit",
	guardian_url=guardian_url, session_id=session_id)
	return None
	except OSError:
	pass

Expectation to add in adapters/_common/tests/test_security.py, which needs ProgrammableGuardian imported and four small helpers written (_hello, _edit_cache, _replace_cache_with_failure_marker, and a _run_claude_adapter returning the usual three-tuple). The second and third stanzas go red on this commit:

    def test_cached_serverhello_is_reverified_before_governing_posture(self) -> None:
        """§4.1:75 says on_decision_failure is negotiated in the handshake.
        §10 says every response carries a signature and a verifier MUST reject
        one that does not cover the envelope. The cached ServerHello is a response, held
        at a predictable path the observed agent can write, and its only
        consumer is the fail posture."""
        g = ProgrammableGuardian()
        g.handlers["handshake/hello"] = self._hello(on_decision_failure="deny")
        with g:
            self._run_claude_adapter(guardian_url=g.url())     # populates the cache
        # Guardian is down from here on, so the posture decides every event.
        rc, out, err = self._run_claude_adapter(guardian_url=g.url())
        self.assertIn('"permissionDecision": "deny"', out,
            "an honest cached ServerHello declaring deny must fail closed")

        self._edit_cache(on_decision_failure="proceed")
        rc, out, err = self._run_claude_adapter(guardian_url=g.url())
        self.assertIn("handshake_cache_signature_invalid", err,
            "§10 requires a verifier to reject a signature that does not cover "
            "the envelope. Today the edit is accepted in silence. Note the edit "
            "still lands on the §4.1:75 startup posture, which defaults to "
            "proceed, so this makes the downgrade visible, not impossible.")

        self._replace_cache_with_failure_marker()
        rc, out, err = self._run_claude_adapter(guardian_url=g.url())
        self.assertIn("handshake_negative_cache_hit", err,
            "§4.1:77 requires a session that proceeds unguarded to be "
            "recorded. This branch is that case and is currently silent.")

[afogel]

Storing result.payload alone throws away the only thing that makes it trustworthy.

This is the write half of the handshake-cache read comment at acs_common.py:592. The read path at line 592 has no way to check a bare payload, because the signature covers the envelope. docs/spec/instrument/specification.md, §10:

Signed input. The signed input for every algorithm is the RFC 8785 (JCS) canonicalization of the request or response envelope with the signature field removed, encoded as UTF-8. This binds the signature to the whole envelope, including method, metadata.session_id, request_id, and timestamp [...]

Keep the envelope and the read path can verify it with the verify_signature defined at acs_common.py:325.

Suggested change

	fd = os.open(str(cache), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
	with os.fdopen(fd, "w") as f:
	json.dump(server_hello, f)
	fd = os.open(str(cache), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
	with os.fdopen(fd, "w") as f:
	# Store the whole signed response, not result.payload, so the
	# read path can re-verify it (§10 binds the signature to the
	# envelope, so a bare payload cannot be checked at all).
	json.dump(response, f)