[bar-capsule]

Summary

A top-level adapters/ directory with reference adapters that wire three agent frameworks to an ACS Guardian through configuration only — no agent code changes — plus a runnable example Guardian and the conformance machinery that proves what the adapters emit.

Component	What it is
adapters/claude-code/	Hook-command adapter: settings.json wiring, explicit turn tracking (turnStart/turnEnd), native allow/deny/ask, modify via merged updatedInput, automated live tests against claude --print
adapters/cursor/	Hook-command adapter: hooks.json wiring, documented-field payloads (docs.cursor.com, 2026-08-22), permission + exit-code-2 blocking
adapters/nat/	In-process FunctionMiddleware for NVIDIA NAT 1.7.0, configured in workflow YAML; a Guardian deny prevents the target function executing
adapters/example-guardian/	Runnable Guardian: signed envelopes (errors included), replay protection with durable file-locked state, capped policy scanning
adapters/_common/	acs_common (RFC 8785/JCS + HKDF-per-session HMAC signing, handshake with signed-ServerHello binding, total decision normalization) + the conformance and emission suites

265 automated checks green in CI: 230 in the adapter gate (guardian conformance, _common, claude-code, cursor — including emission tests that validate the exact bytes each adapter emits against the in-repo schemas and recompute signatures independently) plus 35 NAT, plus one documented manual procedure for Cursor live verification.

Scope, stated plainly

• This proves emission conformance, not yet a requirement-by-requirement ACS-Core claim — that program is milestone [Proposal] Milestone: full ACS-Core conformance (requirement ledger + behavioral tests, beyond adapter emission) #33.
• Cursor's live end-to-end run is a manual procedure (tests/live_verification.md); the adapter is fully tested headlessly. Claude Code and NAT have automated live tests.
• MCP traffic flattens onto the generic tool hooks; nothing here claims wrapped MCP.
• Deliberately-unmapped platform events are documented with reasons (KNOWN_UNMAPPED + each mapping.md) — fabricating unknowable fields would corrupt the artifacts they exist for. subagentStop re-wires once Set the ACS-Core floor: MODIFY and system/ping to SHOULD, Wrapped MCP and subagentStart as conditional MUSTs #21 makes final_chain_hash optional.
• git diff against the base touches no specification/ file: adapters, the CI workflow, .gitignore, and one CONTRIBUTING section.

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 emit the same signed ACS envelope. Decision honoring follows §6.4: fail-open-with-audit by default, fail-closed via ACS_DEFAULT_DENY=1 or the ServerHello posture; Guardian refusals always fail closed (deliberately stricter than v0.1 text, tracked in #32).

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

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 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 (or packaging, per the SDK plan) is straightforward.

Sequencing

Base is integration, status:blocked on #21 — the Core floor this posture conforms to. When #21 lands, one alignment commit updates the floor references and wires subagentStop.

Running

cd adapters && python3 run_conformance.py claude cursor   # full gate: guardian + _common + both CLI adapters
cd adapters/nat && python -m unittest discover tests      # requires nvidia-nat-core

Closes #134.

[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 Set the ACS-Core floor: MODIFY and system/ping to SHOULD, Wrapped MCP and subagentStart as conditional MUSTs #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.

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

[rocklambros]

@bar-capsule The order for your three PRs is #21, then #20, then this one.

Once #21 merges I'll push the alignment commit here myself. It updates the conformance.md line citations, which went stale when #77 added a diagram above the Core bullets (that's why CitationGuard fails against current integration), replaces the "#21 (open; not in this branch)" hedges, and adds notes on what Wrapped MCP and liveness mean for these adapters under the new floor. Please don't push to bar/adapters until this merges, so our commits don't collide.

The subagentStop wiring you have staged is still wanted. I opened #131 for it, accepted and assigned to you. Please open it as a new PR against that issue so this one doesn't need another full review.

[rocklambros]

@bar-capsule the adapters here can't complete a handshake with the TypeScript reference Guardian, or with any Guardian that follows the schema. ensure_session_handshake reads the ServerHello from result.payload (adapters/_common/acs_common.py:776, and the cached path at :692). response-envelope.json says handshake/hello returns the ServerHello directly as result, and that it carries no decision. The TypeScript Guardian sends exactly that (reference-implementations/agt/packages/guardian/src/server.ts:698).

Against this branch at 7174a03, with both replies signed by its own sign_envelope, a ServerHello sent directly as result makes ensure_session_handshake return None and log no_server_hello_payload, while the wrapped shape goes through. The suite stays green because example_guardian.py sends the wrapped shape too, an AcsResult with decision: "allow" and the ServerHello in payload. That validates against the schema's AcsResult branch, since the schema has no way to know which method a reply answers, so the Guardian and the adapters agree with each other and schema validation passes on both.

@President caught this on #162, and @Lrd0036 fixed it there in d077978 with a 277-line contract test. The same commit moves example_guardian.py to the direct shape. That fix is sitting in a PR that can't merge until this one does, so pulling it in here is the shorter path. It needs one extra piece: the new test calls ensure_session_handshake with profiles_supported, one of two optional parameters that #162's Codex commit (3d4bdb3) adds to the same helper. This sequence brings both over:

git fetch https://github.com/GenAI-Security-Project/agent-control-standard pull/162/head
git cherry-pick -s d07797805945801e443ab04eaf3a1f8c5c332ff8
# stops on adapters/codex/tests/test_adapter.py, which doesn't exist on this branch
git rm adapters/codex/tests/test_adapter.py
git show 3d4bdb3e84665e6db13835bc075ee8ec876bc14b -- adapters/_common/acs_common.py | git apply --3way
git add adapters/_common/acs_common.py
git cherry-pick --continue

The commit keeps @Lrd0036 as author, with both sign-offs. On my machine python3 run_conformance.py claude cursor goes from 230 passed to 243 passed, 1 expected skip, 0 failures, and the 13 new contract tests are in that count. I didn't run the NAT suite because I don't have the NVIDIA runtime here, and d077978 touches two lines in nat/tests/test_adapter.py, so that one's worth a run on your side.

It also means #162 gets smaller when @Lrd0036 rebases.

[bar-capsule]

@rocklambros - I cherry-picked d077978 as you laid out: 243 passed, matching yours, and NAT 35/35.

I found another problem: the adapters never read methods_evaluated. handshake.json says clients MUST treat methods outside that list as ALLOW-by-default. Instead, every method was sent, and a Guardian's error on an unevaluated one counted as a decision failure, so fail-closed blocked every prompt and fail-open logged a spurious fail_open_bypass per lifecycle event.

Fixed in the next commit: unevaluated methods are recorded as method_not_evaluated and not sent, the turn still opens locally, and a result never cites a request that wasn't sent. 8 new tests (7 covering Claude Code and Cursor, 1 for NAT); adapter gate now 250 passed with 1 expected skip, NAT 36/36.

Thanks @Lrd0036 !!

[rocklambros]

@almogbhl @stefanoamorelli this is ready for review. These are the coding agent adapters, so it's your call, and an approval from either of you covers everything under adapters/. The PR also touches .github/workflows/adapter_tests.yml, .gitignore, and CONTRIBUTING.md, which need a project lead's approval, so I've added @afogel for those.

#21 merged, so the ACS-Core floor these adapters describe is on integration now, and this branch carries it. I cherry-picked Lance's citation-guard fix from #162 (49f5232), which anchors the guard on requirement names so the diagram #77 added doesn't break it anymore. The same commit sets persist-credentials: false on the adapter workflow's checkouts.

eb69849 replaces the "PR #21 (open; not in this branch)" hedges and updates the subagentStart, Wrapped MCP, and liveness notes to match the merged floor. Nothing in the runtime logic or the test assertions changed.

On integration plus this branch, the adapter suite passes 251 tests with 3 expected skips (the live Claude CLI check and the manual Cursor procedure). I couldn't run the NAT suite, because it needs the NVIDIA runtime. @bar-capsule can you run python3 run_conformance.py nat once more? Your last run was 36 of 36.

#20 doesn't gate this, since the two PRs share no files. @bar-capsule the hold on pushing to bar/adapters is lifted. Once this merges, please open the subagentStop wiring as a new PR against #131.

Everything in this review is fixed on the current head, including the alignment with the merged ACS-Core floor.

[afogel]

Hey! adding a few more blocking changes, unfortunately, and made some suggestions for layout of the functionality for easier maintainability and readability (and hopefully reviewability moving forward). Also, I noticed we probably should cover async functionality for this, but we can likely kick that to a future PR rather than expanding scope here.

[afogel]

Blocking: let's give adapters/ a package layout with the boundaries a future SDK needs.

We're not calling this an SDK yet. But _common is already becoming the client library, and example_guardian a Guardian library. If we set those boundaries and the names users depend on now, the later move is a rename and a publish.

What the current layout costs:

• claude-code and example-guardian aren't valid module names, so every test uses sys.path.insert(...).
• Three files named acs_adapter.py collide in sys.modules. run_conformance.py:167 runs each suite in a subprocess to work around it.
• Client logic (_guardian_roundtrip, _fail, _force_deny, handshake wiring, posture globals) is copied into each adapter, and the copies have drifted apart.

Proposed layout:

adapters/
├── pyproject.toml                 # distribution "acs-adapters"; extra [nat]
├── src/acs/                       # permanent import name
│   ├── core/                      # no I/O: envelope, signing, decision, handshake types, errors, schemas/
│   ├── client/                    # config, posture, session, store, transport, audit, govern()
│   ├── integrations/<framework>/  # translation only: events, hooks, responses, wire, __main__
│   ├── guardian/                  # server, replay/skew/chain, Policy protocol
│   ├── examples/destructive_bash.py
│   └── testing/                   # CaptureGuardian, assert_conforms(...)
├── tests/                         # mirrors src/acs/
└── docs/<framework>/              # mapping.md, *.example configs

Imports flow integrations → client → core ← guardian, enforced in CI by an import-linter contract. The client stays synchronous in this PR. Keeping core/ free of I/O lets an async client be added in a follow-up without touching it (see the comment on nat/acs_adapter.py:995).

Names users depend on. Fix these now:

1. Import path acs. The distribution name changes later, not the imports. Check first that no common PyPI package already installs a top-level acs module.
2. Hook commands as console scripts (acs-claude-code-hook, acs-cursor-hook under [project.scripts]), so user configs never refer to a module path.
3. ACS_* environment variables, documented as stable.
4. An acs.integrations entry-point group, so integrations from other repos plug in the same way.

Also: each layer's public API goes in __all__, with internals in _-prefixed modules. Use one package version from metadata (today NAT says 0.1.2 and Claude Code says 0.1.3), and bundle the schemas into core/schemas/.

Where today's files go:

Today	Moves to
acs_common.py: JCS, HKDF, signing, error codes, decision rules	core/
acs_common.py: handshake cache, session state, audit, URL checks	client/
Each adapter's round trip, _fail, _force_deny, posture globals	client/, written once
Each adapter's payloads, translators, HOOK_MAP, turn/subagent handling	integrations/<framework>/
example_guardian.py wire handling / toy policy	guardian/ / examples/
capture_guardian.py, test_harness.py, e2e_report.py	testing/

Why this helps:

• Migration: becoming the SDK changes only the distribution name. Imports, hook commands, environment variables and tests stay the same.
• Maintenance: posture and handshake fixes land once, in client/, not three times.
• Readability: each integration contains only its framework's translation.
• Review: a move-only first commit shows up as renames, so the 19.7k-line diff stops being 19.7k lines to read.

[afogel]

Part of the proposed layout change: this file can split into an integration plus shared client code.

Concern	Functions	Moves to
Native event → HookEvent	_agent_id, _is_subagent_spawn, _tool_use_request_id	integrations/claude_code/events.py
Event → payload	_payload_*, HOOK_MAP, KNOWN_UNMAPPED	integrations/claude_code/hooks.py
Decision → native output	_pretool_response, _block_response, _translate_*	integrations/claude_code/responses.py
Turns, round trip, posture	_open_turn, _close_turn, call_guardian, _guardian_roundtrip, _fail, _force_deny	client/
Entry point	main	__main__.py, about 5 lines

What to share with Cursor: five functions are near-identical and can move to client/ now: _effective_default_deny, call_guardian, build_turn_start_request, _guardian_roundtrip, and _current_turn_id. The rest, including main, _fail, _force_deny and translate_response, have drifted apart. Make them converge in small steps with the tests passing, and extract once they match. Extracting now would mean a shared version with a flag for every difference.

Why this helps:

• Maintenance: 1,064 lines here and 1,262 in Cursor shrink to translation only, and the protocol logic exists once.
• Review: each integration can be checked against its mapping.md without reading transport code.

[afogel]

Suggestion, non-blocking: return a Decision value instead of a tuple. Goes in core/decision.py.

normalize_decision returns (decision, reasoning, modifications). Every translator then takes it as four positional arguments, and each adapter repeats the decision not in KNOWN_DECISIONS check (claude-code:768, cursor:952, nat:862) with its own fail-closed branch.

# core/types.py: shared JSON types
JSONValue: TypeAlias = str | int | float | bool | None | list["JSONValue"] | dict[str, "JSONValue"]
JSONObject: TypeAlias = dict[str, JSONValue]

# core/decision.py
Disposition: TypeAlias = Literal["allow", "deny", "modify", "ask", "defer"]

@dataclass(frozen=True)
class Decision:
    disposition: Disposition
    reasoning: str = ""
    modifications: Modifications | None = None   # frozen dataclass for the modifications.json shapes

    @classmethod
    def from_result(cls, result: JSONValue) -> Decision:
        """Never raises. Unknown disposition, bad MODIFY composition → deny (§6.3)."""

modify_composition_violation moves into from_result, so an invalid MODIFY can't be constructed at all. result is typed JSONValue, not Any, because it's whatever json.loads returned, and from_result has to narrow it.

Why this helps:

• Maintenance: "an unknown disposition means deny" lives in one place for all three adapters, and the three KNOWN_DECISIONS copies go away.
• Readability: translators take a single typed Decision argument, and a type checker can verify every branch on disposition.
• Migration: Decision is a natural part of the public acs.core API.

[afogel]

Suggestion: sign once, as the last step before sending. If we restructure the layout, I imagine this would go in core/envelope.py.

Currently, build_request signs the envelope, then this branch removes request_id_ref from the signed payload and signs it again. Cursor does the same at line 1156. It's correct today, but every future edit after signing has to remember to re-sign.

SessionKey = NewType("SessionKey", bytes)       # the HKDF-derived per-session key

@dataclass(frozen=True)
class Envelope:
    rpc_id: str                                 # JSON-RPC id, needed to bind the response
    method: str
    request_id: str
    timestamp: str
    metadata: Mapping[str, JSONValue]           # JSONValue: see core/types.py
    payload: Mapping[str, JSONValue]

    def without_ref(self) -> Envelope: ...      # returns a copy; nothing to re-sign
    def signed_body(self, key: SessionKey) -> bytes: ...   # the only place a signature is created

client/transport.py calls .signed_body() and POSTs the result directly. Because it returns bytes, the same code serves today's synchronous transport and a future async one.

Why this helps:

• Maintenance: nothing runs between signing and sending, so forgetting to re-sign becomes impossible.
• Review: one function produces both the signature and the bytes on the wire.

[afogel]

Suggestion: classify the Guardian's answer here, and decide what to do about it somewhere else. In how I'm thinking about it, this would go in client/posture.py.

This function does three jobs at once. It finds out what happened, chooses fail closed or the configured posture, and writes the hook's native response through _fail and _force_deny. Because the response is already written, it returns a (response, terminal) tuple, and every caller has to remember to check terminal. The rule "which causes fail closed?" is spread across 10 return statements.

@dataclass(frozen=True)
class Decided:
    decision: Decision                          # good, bound, signed result

@dataclass(frozen=True)
class Undecided:                                # no usable answer arrived → §6.4 posture applies
    cause: str                                  # transport_failure, decision_timeout, adapter_exception, …
    audit: Mapping[str, JSONValue]              # extra fields for the audit record

@dataclass(frozen=True)
class Refused:                                  # something answered wrongly → always fail closed (#32)
    cause: str                                  # binding mismatch, bad signature, refusal codes, oversize
    audit: Mapping[str, JSONValue]

Outcome: TypeAlias = Decided | Undecided | Refused

The round trip returns an Outcome with no side effects. FailPosture.resolve(outcome) turns it into a Decision (see my comment on line 172), and the integration writes the native response.

Why this helps:

• Review: the fail-closed rule becomes one readable list: the causes that produce Refused.
• Maintenance: the tests can check the classification without capturing stdout. Cursor's _guardian_roundtrip has the same shape and uses the same code.

[afogel]

Suggestion: run the blocking Guardian call off the event loop.

Suggested change

	response = self._call_guardian(request)
	response = await asyncio.to_thread(self._call_guardian, request)

Why this helps:

• Correctness: frees the event loop during the Guardian round trip. The behavior and the existing except clauses are unchanged.
• Apply this together with the import asyncio suggestion on line 48.

[afogel]

Suggestion: use the shared KNOWN_DECISIONS instead of redefining it.

Suggested change

	KNOWN_DECISIONS = frozenset({"allow", "deny", "modify", "ask", "defer"})
	from acs_common import KNOWN_DECISIONS # noqa: E402

Why this helps:

• Maintenance: one definition of the five dispositions. If the spec changes them, three copies won't drift.
• Note: the acs_common import above has already succeeded by this line. Adding it to that import list is cleaner still.

[afogel]

Suggestion: use the shared KNOWN_DECISIONS instead of redefining it.

Suggested change

	KNOWN_DECISIONS = frozenset({"allow", "deny", "modify", "ask", "defer"})
	from acs_common import KNOWN_DECISIONS # noqa: E402

Why this helps:

• Maintenance: one definition of the five dispositions. If the spec changes them, three copies won't drift.
• Note: the acs_common import above has already succeeded by this line. Adding it to that import list is cleaner still.

[afogel]

Suggestion: use the shared KNOWN_DECISIONS instead of redefining it.

Suggested change

	KNOWN_DECISIONS = frozenset({"allow", "deny", "modify", "ask", "defer"})
	from acs_common import KNOWN_DECISIONS # noqa: E402

Why this helps:

• Maintenance: one definition of the five dispositions. If the spec changes them, three copies won't drift.
• Note: the acs_common import above has already succeeded by this line. Adding it to that import list is cleaner still.

[afogel]

Small ask: state the Trace scope.

Suggested change

Known limitations kept in view: Cursor's real-framework wiring is a manual GUI procedure, and Wrapped MCP is validated for namespace shape only, not full wrapping. ACS-Core requires `protocols/MCP/*` for any session that involves MCP and lets only MCP `tools/call` collapse into the generic tool hooks. These adapters perform that collapse and wrap no other MCP surface, so a session that uses MCP falls short of ACS-Core there. Milestone #33 tracks the reference-stack side.

Known limitations kept in view: Cursor's real-framework wiring is a manual GUI procedure, and Wrapped MCP is validated for namespace shape only, not full wrapping. ACS-Core requires `protocols/MCP/*` for any session that involves MCP and lets only MCP `tools/call` collapse into the generic tool hooks. These adapters perform that collapse and wrap no other MCP surface, so a session that uses MCP falls short of ACS-Core there. Milestone #33 tracks the reference-stack side. The adapters also emit no Trace events and do not claim ACS-Trace: `ACS_AUDIT` lines are local audit records, not OpenTelemetry or OCSF output.

Why this helps:

• Readability: the limitations list is complete, so nobody reads "ACS v0.1.0 conformance" as covering Trace. The OTel spec gaps go to separate issues and don't block this PR.