[bar-capsule]

Stacked on #478. Next: #480. The full stack is listed in #22.

What changed

• The adapters read ACS_GUARDIAN_URL, ACS_DEFAULT_DENY, ACS_HANDSHAKE and ACS_DISABLED once, at the entry point, into a Config, and carry the §6.4 posture as a FailPosture value. The secret, the host allowlist and the audit destination are still read where they are used. FailPosture.resolve is the one place a step without a usable decision is settled. A Guardian refusal fails closed under either posture.
• acs.client.exchange returns Decided, Undecided or Refused with a cause and never raises; it replaces each adapter's call_guardian. A JSON-RPC body gets the same binding and signature checks whatever HTTP status carries it.
• The installed hook commands run a standard-library hook.py. When the adapter cannot import (rfc8785 missing), it audits adapter_unavailable and applies ACS_DEFAULT_DENY in the host's deny shape. The Claude Code and Cursor adapters use the shared KNOWN_DECISIONS; NAT follows in Share the round trip, sign once, and return a Decision #482.

Ariel's findings this answers

• Blocking: posture depends on mutable globals and call order
• Classify the Guardian's answer here, decide elsewhere
• Use the shared KNOWN_DECISIONS in Claude Code and Cursor
• August review, finding 4: without rfc8785 the hook exited 1 with no output, which the host treats as proceed.

Where this differs from Ariel's proposal

• Config holds the settings that decide where steps go and how failures settle; Let the handshake decide the session #480 and Use what the handshake negotiated #481 add ACS_STARTUP_POSTURE and ACS_REQUIRE_PROFILES. The secret, the host allowlist and the audit destination are still read where they are used.
• FailPosture.resolve returns a Resolution (proceed or deny, with its audit record) for the adapter to write in the host's shape, and Decided carries the verified response. The Decision value arrives in Share the round trip, sign once, and return a Decision #482.

Which issue does this implement

Part of #134

Base branch

Stacked on #478, 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 (1b68a89c), with claude removed from PATH and ACS_LIVE_CLAUDE and ACS_SPEC_DIR unset: 343 passed and 3 expected skips with the NAT extra, 299 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 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 hook that cannot load its adapter records an audit line and applies ACS_DEFAULT_DENY, and every step without a decision is settled in one place.

[drk-ram]

Reviewed at head 1b68a89c7ebef0963f3ca5c1d01cd313fc1f1991.

This is the PR I spent the most time on, since it touches the §6.4 fail-posture logic directly, and I think it's a solid improvement over what it replaces.

Design

• FailPosture/Config/Resolution (frozen dataclasses in acs.client._config) replace the per-adapter mutable module globals (_SERVER_DENY, _DECISION_TIMEOUT_S) that the linked finding called out as order-dependent. FailPosture.negotiated() applies "deny wins over proceed" and the negotiated timeout in one place, and FailPosture.resolve() is the single function that turns an Undecided/Refused outcome into a proceed/deny Resolution - I traced every call site across claude_code, cursor, and nat adapters and they all route through it now instead of three divergent copies of the same if/else.
• acs.client.exchange / classify_response (_exchange.py) centralizes the HTTP-status, binding, and signature classification that used to be duplicated (and had drifted slightly) across claude_code/adapter.py, cursor/adapter.py, and nat/adapter.py. I diffed the old per-adapter _guardian_roundtrip/pre_invoke/post_invoke error-handling branches against classify_response line by line: the important invariant - a Guardian refusal (is_guardian_refusal) or a binding/signature failure returns Refused and fails closed regardless of posture, while a transport/timeout/malformed-response failure returns Undecided and goes through the posture - is preserved exactly in all three call sites after the refactor, including the NAT adapter's separate _settle_pre/_settle_post (pre_invoke blocks, post_invoke redacts).
• acs.integrations._bootstrap.run_hook is a nice consolidation: previously each of the three adapters had its own ~50-line hand-rolled "if the import fails, write an audit line by hand with sys.stdout/os.fdopen and apply ACS_DEFAULT_DENY" block using only the standard library (since acs.core/acs.client themselves can't be imported on this path). Now that logic lives once in _bootstrap.py and each hook only supplies its own _event_name/_deny callables.

Hardening noticed in the supporting modules

• core/_signing.py's verify_with_key and client/_signing.py's verify_signature both gained isinstance(container, dict) / isinstance(sig, dict) guards and a try/except around jcs_canonicalize for envelopes RFC 8785 can't represent (e.g. values beyond 2**53) - good defense against a crafted response crashing verification into an unhandled exception rather than returning False.
• core/_errors.py extended GUARDIAN_ERROR_CAUSE with the -32000/-32003/-32007 and -3260x codes and tightened guardian_error_cause/is_guardian_refusal to reject non-int codes (including bools, via the explicit not isinstance(code, bool) check) - this matters because code comes straight off an untrusted JSON-RPC body.

Minor, non-blocking

• _settle's deny-message label is picked by comparing resolution.audit_type against the string "guardian_refusal_fail_closed" rather than branching on the Outcome type itself. It works today, but it's a bit stringly-typed given the rest of this PR is clearly oriented around using dataclass variants instead of string tags for this exact reason. Not a blocker, just something to watch if more audit types accumulate.

I spot-checked tests/client/test_exchange.py and tests/client/test_config.py and they cover the classification matrix (each HTTP status / binding mismatch / signature failure / error code combination) thoroughly.

Approving.

[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.