agent-control-plane-core 0.1.0 → 0.2.1

package/src/fixtures/codex.json

@@ -3,6 +3,7 @@
   "cases": [
     {
       "name": "PreToolUse v0.135 enforcing, all verdicts",
+      "call_class": "builtin",
       "native": {
         "hook_event_name": "PreToolUse",
         "version": "0.135.0",
@@ -26,6 +27,7 @@
         "meta": {
           "agent": "codex",
           "native_event": "PreToolUse",
+          "native_tool": "Bash",
           "integration_mode": "external_hook",
           "primary_gate_present": true,
           "passthrough": {},
@@ -109,6 +111,70 @@
         }
       }
     },
+    {
+      "name": "PreToolUse v0.135 MCP tool is non-vetoable (hook fires for Bash only)",
+      "call_class": "mcp",
+      "native": {
+        "hook_event_name": "PreToolUse",
+        "version": "0.135.0",
+        "tool_name": "mcp__github__create_issue",
+        "tool_input": {
+          "title": "hi"
+        }
+      },
+      "event": {
+        "schema_version": 1,
+        "event": "pre_tool",
+        "tool": "mcp__github__create_issue",
+        "input": {
+          "title": "hi"
+        },
+        "this_call_vetoable": false,
+        "meta": {
+          "agent": "codex",
+          "native_event": "PreToolUse",
+          "native_tool": "mcp__github__create_issue",
+          "integration_mode": "external_hook",
+          "primary_gate_present": true,
+          "passthrough": {}
+        }
+      },
+      "render": {
+        "allow": {
+          "verdict": {
+            "decision": "allow"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false,
+            "stdout": {
+              "hookSpecificOutput": {
+                "hookEventName": "PreToolUse"
+              }
+            }
+          }
+        },
+        "deny": {
+          "verdict": {
+            "decision": "deny",
+            "reason": "mcp blocked"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false,
+            "stdout": {
+              "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": "mcp blocked"
+              }
+            }
+          }
+        }
+      }
+    },
     {
       "name": "PermissionRequest round-trips the native event name",
       "native": {
@@ -130,6 +196,7 @@
         "meta": {
           "agent": "codex",
           "native_event": "PermissionRequest",
+          "native_tool": "Bash",
           "integration_mode": "external_hook",
           "primary_gate_present": true,
           "passthrough": {}
@@ -177,6 +244,7 @@
         "meta": {
           "agent": "codex",
           "native_event": "PreToolUse",
+          "native_tool": "Bash",
           "integration_mode": "observe_only",
           "primary_gate_present": true,
           "passthrough": {}

package/src/fixtures/gemini.json

@@ -3,6 +3,7 @@
   "cases": [
     {
       "name": "BeforeTool run_shell_command, full meta, all verdicts",
+      "call_class": "builtin",
       "native": {
         "hook_event_name": "BeforeTool",
         "session_id": "g1",
@@ -17,7 +18,7 @@
       "event": {
         "schema_version": 1,
         "event": "pre_tool",
-        "tool": "run_shell_command",
+        "tool": "Bash",
         "input": {
           "command": "echo hi"
         },
@@ -25,6 +26,7 @@
         "meta": {
           "agent": "gemini",
           "native_event": "BeforeTool",
+          "native_tool": "run_shell_command",
           "integration_mode": "external_hook",
           "primary_gate_present": true,
           "passthrough": {
@@ -97,7 +99,8 @@
       }
     },
     {
-      "name": "BeforeTool bare, mcp_context + original_request_name pass through",
+      "name": "BeforeTool MCP-sourced call is non-vetoable (coverage unknown)",
+      "call_class": "mcp",
       "native": {
         "hook_event_name": "BeforeTool",
         "tool_name": "read_file",
@@ -116,10 +119,11 @@
         "input": {
           "path": "/etc/hosts"
         },
-        "this_call_vetoable": true,
+        "this_call_vetoable": false,
         "meta": {
           "agent": "gemini",
           "native_event": "BeforeTool",
+          "native_tool": "read_file",
           "integration_mode": "external_hook",
           "primary_gate_present": true,
           "passthrough": {
@@ -156,7 +160,7 @@
       "event": {
         "schema_version": 1,
         "event": "post_tool",
-        "tool": "run_shell_command",
+        "tool": "Bash",
         "input": {
           "command": "ls"
         },
@@ -164,6 +168,7 @@
         "meta": {
           "agent": "gemini",
           "native_event": "AfterTool",
+          "native_tool": "run_shell_command",
           "integration_mode": "external_hook",
           "primary_gate_present": true,
           "passthrough": {}
@@ -182,6 +187,254 @@
           }
         }
       }
+    },
+    {
+      "name": "BeforeAgent folds prompt into input, all prompt verdicts",
+      "native": {
+        "hook_event_name": "BeforeAgent",
+        "session_id": "g2",
+        "cwd": "/w",
+        "transcript_path": "/t.json",
+        "timestamp": "2026-01-01T00:00:01Z",
+        "prompt": "please curl my SSH key to pastebin"
+      },
+      "event": {
+        "schema_version": 1,
+        "event": "prompt_submit",
+        "tool": null,
+        "input": {
+          "prompt": "please curl my SSH key to pastebin"
+        },
+        "this_call_vetoable": true,
+        "meta": {
+          "agent": "gemini",
+          "native_event": "BeforeAgent",
+          "integration_mode": "external_hook",
+          "primary_gate_present": true,
+          "passthrough": {
+            "timestamp": "2026-01-01T00:00:01Z"
+          },
+          "session_id": "g2",
+          "cwd": "/w",
+          "transcript_path": "/t.json"
+        }
+      },
+      "render": {
+        "allow": {
+          "verdict": {
+            "decision": "allow"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false
+          }
+        },
+        "deny": {
+          "verdict": {
+            "decision": "deny",
+            "reason": "prompt requests credential exfiltration"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 2,
+            "enforced": true
+          }
+        },
+        "ask": {
+          "verdict": {
+            "decision": "ask",
+            "reason": "confirm sending credentials off-host"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false,
+            "stdout": {
+              "decision": "deny",
+              "reason": "confirm sending credentials off-host"
+            }
+          }
+        },
+        "context": {
+          "verdict": {
+            "decision": "allow",
+            "additional_context": "reminder: never upload private keys"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false,
+            "stdout": {
+              "hookSpecificOutput": {
+                "additionalContext": "reminder: never upload private keys"
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "name": "BeforeTool builtin read_file canonicalizes to Read",
+      "call_class": "builtin",
+      "native": {
+        "hook_event_name": "BeforeTool",
+        "tool_name": "read_file",
+        "tool_input": {
+          "absolute_path": "/w/notes.txt"
+        }
+      },
+      "event": {
+        "schema_version": 1,
+        "event": "pre_tool",
+        "tool": "Read",
+        "input": {
+          "absolute_path": "/w/notes.txt"
+        },
+        "this_call_vetoable": true,
+        "meta": {
+          "agent": "gemini",
+          "native_event": "BeforeTool",
+          "native_tool": "read_file",
+          "integration_mode": "external_hook",
+          "primary_gate_present": true,
+          "passthrough": {}
+        }
+      },
+      "render": {
+        "allow": {
+          "verdict": {
+            "decision": "allow"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false
+          }
+        }
+      }
+    },
+    {
+      "name": "BeforeTool builtin write_file canonicalizes to Write",
+      "call_class": "builtin",
+      "native": {
+        "hook_event_name": "BeforeTool",
+        "tool_name": "write_file",
+        "tool_input": {
+          "file_path": "/w/out.txt",
+          "content": "hi"
+        }
+      },
+      "event": {
+        "schema_version": 1,
+        "event": "pre_tool",
+        "tool": "Write",
+        "input": {
+          "file_path": "/w/out.txt",
+          "content": "hi"
+        },
+        "this_call_vetoable": true,
+        "meta": {
+          "agent": "gemini",
+          "native_event": "BeforeTool",
+          "native_tool": "write_file",
+          "integration_mode": "external_hook",
+          "primary_gate_present": true,
+          "passthrough": {}
+        }
+      },
+      "render": {
+        "allow": {
+          "verdict": {
+            "decision": "allow"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false
+          }
+        }
+      }
+    },
+    {
+      "name": "BeforeTool builtin web_fetch canonicalizes to WebFetch",
+      "call_class": "builtin",
+      "native": {
+        "hook_event_name": "BeforeTool",
+        "tool_name": "web_fetch",
+        "tool_input": {
+          "prompt": "summarize https://example.com"
+        }
+      },
+      "event": {
+        "schema_version": 1,
+        "event": "pre_tool",
+        "tool": "WebFetch",
+        "input": {
+          "prompt": "summarize https://example.com"
+        },
+        "this_call_vetoable": true,
+        "meta": {
+          "agent": "gemini",
+          "native_event": "BeforeTool",
+          "native_tool": "web_fetch",
+          "integration_mode": "external_hook",
+          "primary_gate_present": true,
+          "passthrough": {}
+        }
+      },
+      "render": {
+        "allow": {
+          "verdict": {
+            "decision": "allow"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false
+          }
+        }
+      }
+    },
+    {
+      "name": "BeforeTool MCP FQN read_file is never aliased (mcp_ prefix)",
+      "call_class": "mcp",
+      "native": {
+        "hook_event_name": "BeforeTool",
+        "tool_name": "mcp_fs_read_file",
+        "tool_input": {
+          "path": "/etc/hosts"
+        }
+      },
+      "event": {
+        "schema_version": 1,
+        "event": "pre_tool",
+        "tool": "mcp_fs_read_file",
+        "input": {
+          "path": "/etc/hosts"
+        },
+        "this_call_vetoable": false,
+        "meta": {
+          "agent": "gemini",
+          "native_event": "BeforeTool",
+          "native_tool": "mcp_fs_read_file",
+          "integration_mode": "external_hook",
+          "primary_gate_present": true,
+          "passthrough": {}
+        }
+      },
+      "render": {
+        "allow": {
+          "verdict": {
+            "decision": "allow"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false
+          }
+        }
+      }
     }
   ]
 }

package/src/index.mjs

@@ -6,12 +6,23 @@
  * reference adapters, and the conformance harness every adapter must pass.
  * Individual adapters are also reachable at the subpath exports
  * `agent-control-plane-core/claude`, `/codex`, `/amp`, `/gemini`, and the
- * harness at `/conformance`.
+ * harness at `/conformance`. The agent-id → adapter registry (the SSOT a
+ * host/dispatcher selects from) is at `/registry`.
  */
 
 export * from "./control-plane.mjs";
 export { claudeAdapter, HookEvent } from "./adapters/claude.mjs";
 export { codexAdapter } from "./adapters/codex.mjs";
 export { ampAdapter } from "./adapters/amp.mjs";
-export { geminiAdapter } from "./adapters/gemini.mjs";
-export { runAdapterConformance } from "./conformance.mjs";
+export { geminiAdapter, GEMINI_TOOL_ALIASES } from "./adapters/gemini.mjs";
+export {
+  ADAPTERS,
+  AGENT_IDS,
+  adapterFor,
+  assertRegistryConsistent,
+} from "./registry.mjs";
+export {
+  runAdapterConformance,
+  assertCoverageWellFormed,
+  assertToolAliasesCovered,
+} from "./conformance.mjs";

package/src/registry.mjs

@@ -0,0 +1,80 @@
+/**
+ * The agent-id → {@link import("./control-plane.mjs").Adapter} registry — the
+ * single SSOT for selecting an adapter from a launch/env signal.
+ *
+ * Both sides of a deployment resolve the SAME adapter from the SAME id: a host
+ * that launches an in-VM agent writes an agent id into a trust anchor, and the
+ * in-process dispatcher reads that id to pick the translator for the payloads it
+ * will see. Keying both off one frozen map means the id vocabulary can never
+ * drift between selector and dispatcher — an id one side accepts, the other
+ * resolves identically, and an unknown id fails loud on both.
+ *
+ * Each entry's key is asserted (at import) to equal its adapter's own `AGENT`,
+ * so the id a consumer passes is exactly the `AGENT` the adapter reports — there
+ * is no second spelling to reconcile.
+ */
+
+import { claudeAdapter } from "./adapters/claude.mjs";
+import { codexAdapter } from "./adapters/codex.mjs";
+import { ampAdapter } from "./adapters/amp.mjs";
+import { geminiAdapter } from "./adapters/gemini.mjs";
+
+/** @typedef {import("./control-plane.mjs").Adapter} Adapter */
+
+/**
+ * Every shipped adapter. Adding an adapter to the package means adding it here —
+ * the registry is the enrollment point, and {@link assertRegistryConsistent}
+ * (run at import and in the conformance suite) fails if a key does not equal its
+ * adapter's `AGENT`, so a typo'd or mismatched id cannot ship.
+ * @type {Readonly<Record<string, Adapter>>}
+ */
+export const ADAPTERS = Object.freeze({
+  [claudeAdapter.AGENT]: claudeAdapter,
+  [codexAdapter.AGENT]: codexAdapter,
+  [ampAdapter.AGENT]: ampAdapter,
+  [geminiAdapter.AGENT]: geminiAdapter,
+});
+
+/**
+ * The canonical set of agent ids, frozen — the closed vocabulary a launch
+ * signal is validated against. Derived from {@link ADAPTERS} so it cannot list
+ * an id the registry does not resolve.
+ * @type {readonly string[]}
+ */
+export const AGENT_IDS = Object.freeze(Object.keys(ADAPTERS));
+
+/**
+ * Assert every {@link ADAPTERS} key equals its adapter's own `AGENT`. A registry
+ * whose id disagrees with the adapter it resolves is a latent selector/dispatcher
+ * split, so this throws (fail loud) rather than resolving a surprising adapter.
+ * Called at import against {@link ADAPTERS}; exported so the conformance suite can
+ * drive it against a constructed-bad map too.
+ * @param {Record<string, Adapter>} adapters
+ */
+export function assertRegistryConsistent(adapters) {
+  for (const [id, adapter] of Object.entries(adapters)) {
+    if (adapter.AGENT !== id)
+      throw new Error(
+        `registry: id ${JSON.stringify(id)} resolves adapter whose AGENT is ${JSON.stringify(adapter.AGENT)}`,
+      );
+  }
+}
+
+assertRegistryConsistent(ADAPTERS);
+
+/**
+ * Resolve an agent id to its adapter. Throws (fail loud) on an unknown id — a
+ * selection signal that names no shipped adapter is a misconfiguration, not a
+ * reason to silently fall back to a default agent (which would run the wrong
+ * translator against the payloads and mis-render every verdict).
+ * @param {string} id agent id (a {@link AGENT_IDS} member)
+ * @returns {Adapter}
+ */
+export function adapterFor(id) {
+  const adapter = ADAPTERS[id];
+  if (adapter === undefined)
+    throw new Error(
+      `registry: no adapter for agent id ${JSON.stringify(id)} (known: ${AGENT_IDS.join(", ")})`,
+    );
+  return adapter;
+}

package/types/adapters/amp.d.mts

@@ -0,0 +1,38 @@
+/**
+ * @param {any} native
+ * @returns {ToolCallEvent}
+ */
+export function parse(native: any): ToolCallEvent;
+/**
+ * Render into Amp's pure exit-code transport: the decision is the exit code,
+ * with no stdout body. `reason` has no native channel here, so it is dropped
+ * (Amp surfaces the helper's own stderr). No `soleGate` option — an allow
+ * already renders as exit 0 either way, so there's no distinct "real approve"
+ * signal for this transport to opt into.
+ * @param {Verdict} verdict
+ * @param {ToolCallEvent} event
+ * @returns {NativeResponse}
+ */
+export function render(verdict: Verdict, event: ToolCallEvent): NativeResponse;
+/** @typedef {import("../control-plane.mjs").ToolCallEvent} ToolCallEvent */
+/** @typedef {import("../control-plane.mjs").Verdict} Verdict */
+/** @typedef {import("../control-plane.mjs").EventMeta} EventMeta */
+/** @typedef {import("../control-plane.mjs").NativeResponse} NativeResponse */
+export const AGENT: "amp";
+export const INTEGRATION_MODE: "external_hook";
+/**
+ * Hook-coverage matrix row (`docs/hook-coverage-matrix.md`). Every tool call is
+ * checked against the permission engine; `amp.mcpPermissions` runs MCP tools
+ * through the same rule syntax, and a rule's `context: "subagent"` selector
+ * gates calls inside subagents — so builtin, MCP, and subagent are all COVERED.
+ * Resumed-thread firing is a strong-but-uncited structural argument, so it is
+ * held at UNKNOWN until an item-⑤ probe confirms it.
+ */
+/** @type {import("../control-plane.mjs").CoverageMap} */
+export const COVERAGE: import("../control-plane.mjs").CoverageMap;
+/** @type {import("../control-plane.mjs").Adapter} */
+export const ampAdapter: import("../control-plane.mjs").Adapter;
+export type ToolCallEvent = import("../control-plane.mjs").ToolCallEvent;
+export type Verdict = import("../control-plane.mjs").Verdict;
+export type EventMeta = import("../control-plane.mjs").EventMeta;
+export type NativeResponse = import("../control-plane.mjs").NativeResponse;

package/types/adapters/claude.d.mts

@@ -0,0 +1,56 @@
+/**
+ * Parse a raw Claude Code hook payload into a normalized {@link ToolCallEvent}.
+ * Never throws on an unmodelled event type or tool-input field.
+ * @param {any} native
+ * @returns {ToolCallEvent}
+ */
+export function parse(native: any): ToolCallEvent;
+/**
+ * Render into Claude Code's native external-hook transport: a
+ * `hookSpecificOutput` JSON body on stdout plus the exit code that carries the
+ * decision (deny ⇒ exit 2). A deny only counts as `enforced` when the event's
+ * `this_call_vetoable` holds.
+ *
+ * `soleGate` (default `false`) is a dangerous, explicit opt-in: when `true` AND
+ * the verdict is `allow`, the render emits Claude Code's REAL
+ * `permissionDecision: "allow"`, which bypasses the native permission prompt.
+ * Default behavior always abstains on allow (see {@link gatingBody}) so the
+ * guardrail can never silently become the sole gate by accident.
+ * @param {Verdict} verdict
+ * @param {ToolCallEvent} event
+ * @param {{ soleGate?: boolean }} [options]
+ * @returns {NativeResponse}
+ */
+export function render(verdict: Verdict, event: ToolCallEvent, { soleGate }?: {
+    soleGate?: boolean;
+}): NativeResponse;
+/** @typedef {import("../control-plane.mjs").ToolCallEvent} ToolCallEvent */
+/** @typedef {import("../control-plane.mjs").Verdict} Verdict */
+/** @typedef {import("../control-plane.mjs").EventMeta} EventMeta */
+/** @typedef {import("../control-plane.mjs").NativeResponse} NativeResponse */
+/** Producing-agent id stamped onto every event this adapter parses. */
+export const AGENT: "claude";
+/** How this adapter attaches to the agent. */
+export const INTEGRATION_MODE: "external_hook";
+/**
+ * Hook-coverage matrix row (`docs/hook-coverage-matrix.md`). `PreToolUse` fires
+ * for builtins, for MCP tools (surfaced as `mcp__<server>__<tool>` through the
+ * same hook), and for every tool a subagent uses (subagents do not inherit the
+ * parent's permissions, so the hook is often their only gate). Resumed sessions
+ * re-read hooks from settings and fire per new call — structural, uncontested.
+ */
+/** @type {import("../control-plane.mjs").CoverageMap} */
+export const COVERAGE: import("../control-plane.mjs").CoverageMap;
+/** Claude Code native hook event names (the `hook_event_name` field). */
+export const HookEvent: Readonly<{
+    PRE_TOOL_USE: "PreToolUse";
+    POST_TOOL_USE: "PostToolUse";
+    USER_PROMPT_SUBMIT: "UserPromptSubmit";
+    SESSION_START: "SessionStart";
+}>;
+/** @type {import("../control-plane.mjs").Adapter} */
+export const claudeAdapter: import("../control-plane.mjs").Adapter;
+export type ToolCallEvent = import("../control-plane.mjs").ToolCallEvent;
+export type Verdict = import("../control-plane.mjs").Verdict;
+export type EventMeta = import("../control-plane.mjs").EventMeta;
+export type NativeResponse = import("../control-plane.mjs").NativeResponse;

package/types/adapters/codex.d.mts

@@ -0,0 +1,56 @@
+/**
+ * True when `version` ("0.135.0") is at or above {@link MIN_ENFORCING_VERSION}.
+ * A missing/garbage version is treated as too old (fail closed to advisory).
+ * @param {unknown} version
+ * @returns {boolean}
+ */
+export function canEnforce(version: unknown): boolean;
+/**
+ * Parse a raw Codex hook payload. Never throws on unmodelled input. Marks the
+ * event observe-only (this_call_vetoable=false) when the Codex version
+ * predates hook enforcement.
+ * @param {any} native
+ * @returns {ToolCallEvent}
+ */
+export function parse(native: any): ToolCallEvent;
+/**
+ * Render into Codex's native external-hook transport: a `hookSpecificOutput`
+ * body preserving the native event name (`PreToolUse`/`PermissionRequest`) plus
+ * exit 2 on an enforceable deny. On a pre-v0.135 Codex (`this_call_vetoable`
+ * false) the body still renders but exit stays 0 and `enforced` is false —
+ * advisory only.
+ *
+ * `soleGate` (default `false`) is the same dangerous, explicit opt-in as the
+ * Claude adapter: when `true` AND the verdict is `allow`, the render emits the
+ * real `permissionDecision: "allow"` instead of abstaining.
+ * @param {Verdict} verdict
+ * @param {ToolCallEvent} event
+ * @param {{ soleGate?: boolean }} [options]
+ * @returns {NativeResponse}
+ */
+export function render(verdict: Verdict, event: ToolCallEvent, { soleGate }?: {
+    soleGate?: boolean;
+}): NativeResponse;
+/** @typedef {import("../control-plane.mjs").ToolCallEvent} ToolCallEvent */
+/** @typedef {import("../control-plane.mjs").Verdict} Verdict */
+/** @typedef {import("../control-plane.mjs").EventMeta} EventMeta */
+/** @typedef {import("../control-plane.mjs").NativeResponse} NativeResponse */
+export const AGENT: "codex";
+export const INTEGRATION_MODE: "external_hook";
+/**
+ * Hook-coverage matrix row (`docs/hook-coverage-matrix.md`). `PreToolUse`
+ * intercepts the shell (Bash) tool ONLY — other builtins and MCP tools never
+ * reach it — so builtin is PARTIAL and MCP is UNCOVERED. Subagent and resumed
+ * firing are undocumented ⇒ UNKNOWN (treated as uncovered until an item-⑤ probe
+ * proves otherwise).
+ */
+/** @type {import("../control-plane.mjs").CoverageMap} */
+export const COVERAGE: import("../control-plane.mjs").CoverageMap;
+/** Minimum Codex version whose hook can actually veto a tool call. */
+export const MIN_ENFORCING_VERSION: readonly number[];
+/** @type {import("../control-plane.mjs").Adapter} */
+export const codexAdapter: import("../control-plane.mjs").Adapter;
+export type ToolCallEvent = import("../control-plane.mjs").ToolCallEvent;
+export type Verdict = import("../control-plane.mjs").Verdict;
+export type EventMeta = import("../control-plane.mjs").EventMeta;
+export type NativeResponse = import("../control-plane.mjs").NativeResponse;