Fix Claude Code schema, add Cursor reference impl, verify live integration

Claude Code adapter:
- Corrected response shape to use hookSpecificOutput.permissionDecision
  (per https://code.claude.com/docs/en/hooks); previous version emitted
  a top-level {"decision": "block"} which Claude Code does not parse
  on PreToolUse.
- Honor Claude Code's native ask/defer permissionDecision values
  instead of substituting them to deny.
- PostToolUse: handle the actual tool_response object (stdout/stderr/...)
  rather than the docs-claimed tool_output string. Preserve tool_use_id
  and duration_ms for Guardian correlation.
- Added real_claude_code_payloads.example: captured payloads from a real
  `claude --print` session for reference.
- Updated tests with corrected expectations (13 tests, all passing).

Live integration verified against a real `claude --print` session:
- ALLOW path: command ran, Guardian saw toolCallRequest + toolCallResult
  with the real Claude Code session id.
- DENY path: Claude Code surfaced "The command was blocked - a policy
  named '...' denied the Bash tool call, so it never ran." Reasoning
  flowed from Guardian -> adapter -> Claude Code -> user-visible message.

Cursor adapter (NEW, promoted from research to reference implementation):
- Schema source: ~/.cursor/skills-cursor/create-hook/SKILL.md
- Full implementation: cursor_adapter.py covers all 20 documented Cursor
  hook events.
- Per-event dispatch via argv[1] (Cursor wires one command per event).
- Per-event output translation:
  - Permission events (preToolUse, subagentStart, beforeShell, beforeMCP)
    use top-level {permission, user_message, agent_message, updated_input}
  - Post-tool events use additional_context / updated_mcp_tool_output
  - subagentStop uses followup_message
  - beforeSubmitPrompt uses exit code 2 to block (Cursor's protocol)
- Reuses the Claude Code example Guardian (same ACS shape on the wire).
- 13 round-trip tests, all passing.

Example Guardian (shared):
- Recognize both 'Bash' and 'Shell' tool names (Cursor uses Shell).
- Allow subagentStart, knowledgeRetrieval, memoryStore,
  memoryContextRetrieval in addition to the original allow-list.

Total: 26/26 tests passing across both adapters.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bar-capsule

adapters/README.md

@@ -4,28 +4,39 @@ Reference implementations that wire popular agent frameworks to an ACS Guardian.
 
 ## Status
 
-| Adapter | Status | Mapping | Working adapter | Tests |
-|---|---|---|---|---|
-| [claude-code](./claude-code/) | Reference implementation | ✓ | ✓ | ✓ (10 round-trip tests) |
-| [nat](./nat/) | Draft | ✓ | — | — |
-| [cursor](./cursor/) | Research | ✓ | — | — |
+| Adapter | Status | Mapping | Working adapter | Tests | Live integration verified |
+|---|---|---|---|---|---|
+| [claude-code](./claude-code/) | Reference implementation | ✓ | ✓ | ✓ 13 round-trip tests | ✓ ALLOW + DENY paths verified against a real `claude --print` session |
+| [cursor](./cursor/) | Reference implementation | ✓ | ✓ | ✓ 13 round-trip tests | ⚠ Manual verification by reviewer with Cursor installed (Cursor has no headless mode) |
+| [nat](./nat/) | Draft | ✓ | — | — | — |
 
 ## The adapter pattern
 
 Each adapter does the same three things, with framework-specific glue:
 
-1. Listen for the framework's lifecycle events (hook callback, middleware, command-driven shell hook, etc.).
+1. Listen for the framework's lifecycle events (hook callback, command-driven shell hook, middleware, etc.).
 2. Translate each event to an ACS JSON-RPC request and send it to a Guardian endpoint over HTTP.
 3. Translate the Guardian's ACS decision back to the framework's expected response shape (allow / block / modify / pause).
 
-The translation tables live in each adapter's `mapping.md`. The translation code lives in each adapter's reference implementation (when available).
+The translation tables live in each adapter's `mapping.md`. The translation code lives in each adapter's reference implementation. The Claude Code and Cursor adapters share the same example Guardian (`adapters/claude-code/example_guardian.py`) — the ACS shape on the wire is identical regardless of which framework emits the event.
 
 ## Why "adapters" and not first-class framework support
 
 ACS-Core specifies what a hook event looks like on the wire and what the Guardian's decision looks like coming back. It deliberately does not dictate how a framework physically wires the interception in. That last part is implementation: an MCP proxy, a framework callback, a shell-script command, or a runtime monkey-patch. The choice depends on which boundary the framework already crosses (see the FAQ in `docs/topics/faq.md`, "How do I make my framework ACS-conformant?").
 
 The adapters here demonstrate the boundary choice for each target framework. Other frameworks can ship their own adapters, or contribute new ones to this directory.
 
+## Cross-adapter design summary
+
+| Aspect | Claude Code | Cursor | NAT (draft) |
+|---|---|---|---|
+| Interception mechanism | Shell command per hook (settings.json) | Shell command per hook (hooks.json) | Config-level middleware (planned) |
+| Event dispatch | Event name in stdin JSON | Event name as `argv[1]` | Middleware lifecycle position |
+| Permission output | `hookSpecificOutput.permissionDecision` | `permission` (top-level, per-event) | TBD |
+| Modify output | `hookSpecificOutput.updatedInput` | `updated_input` | TBD |
+| Block via exit code | Optional | Supported (`exit 2`); required on `beforeSubmitPrompt` | TBD |
+| Fail-closed flag | Adapter env var | Hook-level `failClosed: true` + adapter env var | TBD |
+
 ## Contributing a new adapter
 
 1. Create `adapters/<framework-name>/`.

adapters/claude-code/acs_adapter.py

@@ -6,18 +6,17 @@
 ACS JSON-RPC request, sends it to a Guardian, and translates the ACS
 response back into the format Claude Code expects (printed to stdout).
 
+Schema source: https://code.claude.com/docs/en/hooks
+
 Wire up via Claude Code's `~/.claude/settings.json`. See
 settings.json.example in this directory.
 
 Environment variables:
   ACS_GUARDIAN_URL    Guardian endpoint (default: http://127.0.0.1:8787/acs)
-  ACS_SESSION_ID      Session id to send on every request (default: a stable
-                      id derived from the working directory)
-  ACS_DEFAULT_DENY    If "1", deny on any adapter error. Default: "1".
+  ACS_DEFAULT_DENY    If "1", block on any adapter error. Default: "1".
 """
 from __future__ import annotations
 
-import hashlib
 import json
 import os
 import sys
@@ -33,7 +32,7 @@
 ACS_VERSION = "0.1.0"
 
 
-# Claude Code hook event name -> ACS step method
+# Claude Code hook_event_name -> ACS step method
 HOOK_MAP: dict[str, str] = {
     "SessionStart": "steps/sessionStart",
     "SessionEnd": "steps/sessionEnd",
@@ -48,36 +47,52 @@
 }
 
 
-def session_id_from_cwd() -> str:
-    cwd = os.environ.get("PWD") or os.getcwd()
-    return "cc-" + hashlib.sha256(cwd.encode()).hexdigest()[:16]
-
-
 def build_payload(event: dict[str, Any]) -> dict[str, Any]:
     """Build the ACS step payload from a Claude Code hook event."""
     name = event.get("hook_event_name", "")
     payload: dict[str, Any] = {
-        "session_id": os.environ.get("ACS_SESSION_ID") or session_id_from_cwd(),
+        "session_id": event.get("session_id", ""),
         "step_id": str(uuid.uuid4()),
+        "cwd": event.get("cwd"),
+        "transcript_path": event.get("transcript_path"),
+        "permission_mode": event.get("permission_mode"),
     }
+    # Drop None values to keep the payload clean
+    payload = {k: v for k, v in payload.items() if v is not None}
+
     if name == "PreToolUse":
         payload["tool"] = {
             "name": event.get("tool_name", ""),
             "arguments": event.get("tool_input", {}),
         }
+        payload["tool_use_id"] = event.get("tool_use_id")
     elif name == "PostToolUse":
         payload["tool"] = {
             "name": event.get("tool_name", ""),
             "arguments": event.get("tool_input", {}),
         }
+        # Real Claude Code emits tool_response (object with stdout/stderr/...);
+        # docs say tool_output (string). Accept either for forward-compat.
         payload["result"] = event.get("tool_response", event.get("tool_output"))
+        payload["tool_use_id"] = event.get("tool_use_id")
+        payload["duration_ms"] = event.get("duration_ms")
     elif name == "UserPromptSubmit":
         payload["content"] = event.get("prompt", "")
     elif name == "Notification":
         payload["content"] = event.get("message", "")
-    elif name in ("SessionStart", "SessionEnd", "Stop"):
+        payload["notification_type"] = event.get("notification_type")
+    elif name == "SessionStart":
+        payload["source"] = event.get("source")
+        payload["model"] = event.get("model")
+    elif name == "SessionEnd":
         payload["reason"] = event.get("reason")
-    return payload
+    elif name in ("PreCompact", "PostCompact"):
+        payload["trigger"] = event.get("trigger")
+    elif name == "SubagentStop":
+        payload["agent_id"] = event.get("agent_id")
+        payload["agent_type"] = event.get("agent_type")
+
+    return {k: v for k, v in payload.items() if v is not None}
 
 
 def build_request(event: dict[str, Any]) -> dict[str, Any]:
@@ -109,40 +124,126 @@ def call_guardian(request: dict[str, Any]) -> dict[str, Any]:
         return json.loads(resp.read().decode("utf-8"))
 
 
+# ACS disposition -> Claude Code permissionDecision (PreToolUse only)
+PRETOOL_PERMISSION_MAP: dict[str, str] = {
+    "allow": "allow",
+    "deny": "deny",
+    "ask": "ask",
+    "defer": "defer",
+}
+
+
 def translate_response(acs_response: dict[str, Any], hook_event: str) -> dict[str, Any]:
     """Translate an ACS decision envelope to Claude Code's expected output.
 
-    Claude Code expects either:
-      - empty / no decision => proceed
-      - {"decision": "approve"} on PreToolUse
-      - {"decision": "block", "reason": "..."} on PreToolUse
-      - {"continue": false, "stopReason": "..."} to halt the agent
+    Schema reference: https://code.claude.com/docs/en/hooks
     """
     result = acs_response.get("result", {})
     decision = (result.get("decision") or "").lower()
     reasoning = result.get("reasoning", "")
+    modifications = result.get("modifications", {})
 
-    if decision == "allow":
-        return {}  # Claude Code interprets empty as proceed
-    if decision == "deny":
-        if hook_event == "PreToolUse":
-            return {"decision": "block", "reason": reasoning or "blocked by Guardian"}
-        return {"continue": False, "stopReason": reasoning or "blocked by Guardian"}
-    if decision == "modify":
-        mods = result.get("modifications", {})
-        out: dict[str, Any] = {}
-        if hook_event == "PreToolUse" and "parameter_overrides" in mods:
-            out["decision"] = "modify"
-            out["modifiedInput"] = mods["parameter_overrides"]
+    # ----- PreToolUse: permissionDecision under hookSpecificOutput -----
+    if hook_event == "PreToolUse":
+        hso: dict[str, Any] = {"hookEventName": "PreToolUse"}
+        if decision in PRETOOL_PERMISSION_MAP:
+            hso["permissionDecision"] = PRETOOL_PERMISSION_MAP[decision]
             if reasoning:
-                out["reason"] = reasoning
-            return out
-        # Adapter does not implement MODIFY on other hooks: substitute DENY with audit
-        return {"decision": "block", "reason": f"MODIFY substituted to DENY: {reasoning}"}
-    if decision == "ask":
-        return {"decision": "block", "reason": f"approval required: {reasoning}"}
-    if decision == "defer":
-        return {"decision": "block", "reason": f"deferred: {reasoning}"}
+                hso["permissionDecisionReason"] = reasoning
+            return {"hookSpecificOutput": hso}
+        if decision == "modify":
+            # Claude Code's modify path: updatedInput
+            overrides = modifications.get("parameter_overrides")
+            if overrides is not None:
+                hso["permissionDecision"] = "allow"
+                hso["updatedInput"] = overrides
+                if reasoning:
+                    hso["permissionDecisionReason"] = reasoning
+                return {"hookSpecificOutput": hso}
+            # MODIFY without parameter_overrides on PreToolUse: substitute DENY
+            hso["permissionDecision"] = "deny"
+            hso["permissionDecisionReason"] = (
+                f"MODIFY substituted to DENY (no parameter_overrides): {reasoning}"
+            )
+            return {"hookSpecificOutput": hso}
+        # Unknown / empty decision: proceed
+        return {}
+
+    # ----- PostToolUse: top-level decision, optional updatedToolOutput -----
+    if hook_event == "PostToolUse":
+        if decision == "deny":
+            return {
+                "decision": "block",
+                "reason": reasoning or "blocked by Guardian",
+                "hookSpecificOutput": {"hookEventName": "PostToolUse"},
+            }
+        if decision == "modify":
+            updated = modifications.get("modified_content")
+            if updated is not None:
+                return {
+                    "hookSpecificOutput": {
+                        "hookEventName": "PostToolUse",
+                        "updatedToolOutput": str(updated),
+                        **({"additionalContext": reasoning} if reasoning else {}),
+                    }
+                }
+            return {
+                "decision": "block",
+                "reason": f"MODIFY substituted to DENY (no modified_content): {reasoning}",
+            }
+        if decision in ("ask", "defer"):
+            return {
+                "decision": "block",
+                "reason": f"{decision} on post-tool not supported by Claude Code: {reasoning}",
+            }
+        return {}
+
+    # ----- UserPromptSubmit: decision block + additionalContext -----
+    if hook_event == "UserPromptSubmit":
+        if decision == "deny":
+            return {
+                "decision": "block",
+                "reason": reasoning or "blocked by Guardian",
+            }
+        if decision in ("ask", "defer"):
+            return {
+                "decision": "block",
+                "reason": f"{decision} on user prompt: {reasoning}",
+            }
+        # Modify on a prompt isn't expressible via this hook's contract;
+        # Guardian-side rewrite would have to happen before submission.
+        return {}
+
+    # ----- Stop / SubagentStop -----
+    if hook_event in ("Stop", "SubagentStop"):
+        if decision == "deny":
+            return {
+                "decision": "block",
+                "reason": reasoning or "blocked by Guardian",
+            }
+        return {}
+
+    # ----- PreCompact -----
+    if hook_event == "PreCompact":
+        if decision == "deny":
+            return {
+                "decision": "block",
+                "reason": reasoning or "compaction blocked by Guardian",
+                "hookSpecificOutput": {"hookEventName": "PreCompact"},
+            }
+        return {}
+
+    # ----- SessionStart / SessionEnd / PostCompact / Notification -----
+    # Informational hooks: ACS records them, Claude Code does not gate on them.
+    # If the Guardian wants to feed context back, additionalContext goes here.
+    additional = result.get("additional_context")
+    if additional:
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": hook_event,
+                "additionalContext": str(additional),
+            }
+        }
     return {}
 
 
@@ -158,36 +259,47 @@ def main() -> int:
 
     hook_name = event.get("hook_event_name", "")
     if hook_name not in HOOK_MAP:
-        # Not a hook we map; emit empty so Claude Code proceeds
-        return 0
+        return 0  # not a hook we map; proceed
 
     try:
         request = build_request(event)
         response = call_guardian(request)
         out = translate_response(response, hook_name)
     except (urllib.error.URLError, urllib.error.HTTPError, TimeoutError, OSError) as e:
         sys.stderr.write(f"acs-adapter: Guardian unreachable: {e}\n")
-        return _fail()
+        return _fail(hook_name)
     except Exception as e:  # noqa: BLE001
         sys.stderr.write(f"acs-adapter: adapter error: {e}\n")
-        return _fail()
+        return _fail(hook_name)
 
     if out:
         json.dump(out, sys.stdout)
         sys.stdout.write("\n")
     return 0
 
 
-def _fail() -> int:
-    """Apply fail posture and emit the corresponding Claude Code output."""
-    if DEFAULT_DENY:
+def _fail(hook_name: str = "") -> int:
+    """Emit a fail-closed response in the shape the hook expects."""
+    if not DEFAULT_DENY:
+        return 0  # fail-open: proceed with no output
+    msg = "ACS adapter: Guardian unreachable"
+    if hook_name == "PreToolUse":
         json.dump(
-            {"decision": "block", "reason": "ACS adapter: Guardian unreachable"},
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                    "permissionDecisionReason": msg,
+                }
+            },
             sys.stdout,
         )
-        sys.stdout.write("\n")
+    elif hook_name in ("PostToolUse", "UserPromptSubmit", "Stop", "SubagentStop", "PreCompact"):
+        json.dump({"decision": "block", "reason": msg}, sys.stdout)
+    else:
+        # Informational hooks: fail-open is the only viable option (no block contract)
         return 0
-    # Fail-open: proceed (empty output), record nothing (the Guardian is the audit sink)
+    sys.stdout.write("\n")
     return 0
 
 

adapters/claude-code/example_guardian.py

@@ -43,7 +43,7 @@ def evaluate(method: str, params: dict[str, Any]) -> dict[str, Any]:
         tool_name = tool.get("name", "")
         args = tool.get("arguments", {})
 
-        if tool_name == "Bash":
+        if tool_name in ("Bash", "Shell"):
             cmd = args.get("command", "")
             if DESTRUCTIVE_BASH.search(cmd):
                 return {
@@ -73,7 +73,11 @@ def evaluate(method: str, params: dict[str, Any]) -> dict[str, Any]:
         "steps/agentResponse",
         "steps/preCompact",
         "steps/postCompact",
+        "steps/subagentStart",
         "steps/subagentStop",
+        "steps/knowledgeRetrieval",
+        "steps/memoryStore",
+        "steps/memoryContextRetrieval",
     ):
         return {"decision": "allow", "chain_hash": chain_hash}
 

adapters/claude-code/tests/real_claude_code_payloads.example

@@ -0,0 +1,16 @@
+=== HOOK FIRED 2026-06-15T08:55:53Z ===
+{"session_id":"befb9d53-a5c4-4024-95e4-09c5b1d08b17","transcript_path":"/Users/barkaduri/.claude/projects/-private-tmp-acs-real-test/befb9d53-a5c4-4024-95e4-09c5b1d08b17.jsonl","cwd":"/private/tmp/acs-real-test","hook_event_name":"SessionStart","source":"startup"}
+
+=== END ===
+=== HOOK FIRED 2026-06-15T08:55:53Z ===
+{"session_id":"befb9d53-a5c4-4024-95e4-09c5b1d08b17","transcript_path":"/Users/barkaduri/.claude/projects/-private-tmp-acs-real-test/befb9d53-a5c4-4024-95e4-09c5b1d08b17.jsonl","cwd":"/private/tmp/acs-real-test","permission_mode":"acceptEdits","hook_event_name":"UserPromptSubmit","prompt":"Run the shell command: echo HOOK_PROBE_OK"}
+
+=== END ===
+=== HOOK FIRED 2026-06-15T08:55:56Z ===
+{"session_id":"befb9d53-a5c4-4024-95e4-09c5b1d08b17","transcript_path":"/Users/barkaduri/.claude/projects/-private-tmp-acs-real-test/befb9d53-a5c4-4024-95e4-09c5b1d08b17.jsonl","cwd":"/private/tmp/acs-real-test","permission_mode":"acceptEdits","effort":{"level":"high"},"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"echo HOOK_PROBE_OK","description":"Echo a probe string"},"tool_use_id":"toolu_01VA6o3dtCvr716MhHFrA7VW"}
+
+=== END ===
+=== HOOK FIRED 2026-06-15T08:56:01Z ===
+{"session_id":"befb9d53-a5c4-4024-95e4-09c5b1d08b17","transcript_path":"/Users/barkaduri/.claude/projects/-private-tmp-acs-real-test/befb9d53-a5c4-4024-95e4-09c5b1d08b17.jsonl","cwd":"/private/tmp/acs-real-test","permission_mode":"acceptEdits","effort":{"level":"high"},"hook_event_name":"PostToolUse","tool_name":"Bash","tool_input":{"command":"echo HOOK_PROBE_OK","description":"Echo a probe string"},"tool_response":{"stdout":"HOOK_PROBE_OK","stderr":"","interrupted":false,"isImage":false,"noOutputExpected":false},"tool_use_id":"toolu_01VA6o3dtCvr716MhHFrA7VW","duration_ms":5616}
+
+=== END ===