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.