agent-control-plane-core 0.1.0 → 0.2.0

package/package.json

@@ -1,10 +1,17 @@
 {
   "name": "agent-control-plane-core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Vendor-neutral control-plane contract for coding agents: a normalized ToolCallEvent/Verdict schema with per-agent adapters (Claude Code, Codex) and a conformance suite.",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlexanderMattTurner/agent-control-plane-core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AlexanderMattTurner/agent-control-plane-core/issues"
+  },
+  "homepage": "https://github.com/AlexanderMattTurner/agent-control-plane-core#readme",
   "license": "MIT",
-  "packageManager": "pnpm@11.8.0",
   "engines": {
     "node": ">=20"
   },
@@ -34,6 +41,10 @@
     "./conformance": {
       "types": "./types/conformance.d.mts",
       "import": "./src/conformance.mjs"
+    },
+    "./registry": {
+      "types": "./types/registry.d.mts",
+      "import": "./src/registry.mjs"
     }
   },
   "files": [
@@ -51,17 +62,6 @@
     "adapter",
     "guardrail"
   ],
-  "scripts": {
-    "prepare": "git config core.hooksPath .hooks",
-    "build": "tsc -p tsconfig.build.json",
-    "prepublishOnly": "pnpm build",
-    "test": "node --test test/*.test.mjs",
-    "test:coverage": "c8 node --test test/*.test.mjs",
-    "check": "tsc --noEmit",
-    "lint": "eslint .",
-    "format": "prettier --write .",
-    "format:check": "prettier --check ."
-  },
   "lint-staged": {
     "*.{css,scss}": [
       "prettier --write"
@@ -105,5 +105,14 @@
     "lint-staged": "^17.0.5",
     "prettier": "^3.0.0",
     "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "node --test test/*.test.mjs",
+    "test:coverage": "c8 node --test test/*.test.mjs",
+    "check": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
   }
-}
+}

package/src/adapters/amp.mjs

@@ -15,6 +15,11 @@ import {
   EventKind,
   Decision,
   IntegrationMode,
+  CallClass,
+  CoverageStatus,
+  classifyCallClass,
+  coverageAllowsVeto,
+  canonicalTool,
   makeEvent,
   normalizeVerdict,
   nativeResponse,
@@ -31,6 +36,22 @@ import {
 export const AGENT = "amp";
 export const INTEGRATION_MODE = IntegrationMode.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 = Object.freeze({
+  [CallClass.BUILTIN]: CoverageStatus.COVERED,
+  [CallClass.MCP]: CoverageStatus.COVERED,
+  [CallClass.SUBAGENT]: CoverageStatus.COVERED,
+  [CallClass.RESUMED]: CoverageStatus.UNKNOWN,
+});
+
 // Amp invokes the delegate for a tool call; the payload carries the tool name +
 // input and the session context. Pinned by fixtures/amp.json.
 const CONSUMED = new Set(["tool", "input", "session_id", "cwd"]);
@@ -51,12 +72,17 @@ export function parse(native) {
   };
   if (typeof raw.session_id === "string") meta.session_id = raw.session_id;
   if (typeof raw.cwd === "string") meta.cwd = raw.cwd;
+  const nativeTool = asStringOrNull(raw.tool);
+  if (nativeTool !== null) meta.native_tool = nativeTool;
   return makeEvent({
     event: EventKind.PRE_TOOL,
-    tool: asStringOrNull(raw.tool),
+    tool: canonicalTool(nativeTool),
     input: asObject(raw.input),
     response: undefined,
-    this_call_vetoable: true,
+    // Classify on the NATIVE name (MCP detection keys on `mcp__…`).
+    this_call_vetoable: coverageAllowsVeto(
+      COVERAGE[classifyCallClass(nativeTool, raw)],
+    ),
     meta,
   });
 }
@@ -79,4 +105,4 @@ export function render(verdict, event) {
 }
 
 /** @type {import("../control-plane.mjs").Adapter} */
-export const ampAdapter = { AGENT, INTEGRATION_MODE, parse, render };
+export const ampAdapter = { AGENT, INTEGRATION_MODE, COVERAGE, parse, render };

package/src/adapters/claude.mjs

@@ -16,6 +16,11 @@ import {
   EventKind,
   Decision,
   IntegrationMode,
+  CallClass,
+  CoverageStatus,
+  classifyCallClass,
+  coverageAllowsVeto,
+  canonicalTool,
   makeEvent,
   normalizeVerdict,
   nativeResponse,
@@ -36,6 +41,21 @@ export const AGENT = "claude";
 /** How this adapter attaches to the agent. */
 export const INTEGRATION_MODE = IntegrationMode.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 = Object.freeze({
+  [CallClass.BUILTIN]: CoverageStatus.COVERED,
+  [CallClass.MCP]: CoverageStatus.COVERED,
+  [CallClass.SUBAGENT]: CoverageStatus.COVERED,
+  [CallClass.RESUMED]: CoverageStatus.COVERED,
+});
+
 /** Claude Code native hook event names (the `hook_event_name` field). */
 export const HookEvent = Object.freeze({
   PRE_TOOL_USE: "PreToolUse",
@@ -129,13 +149,20 @@ export function parse(native) {
     /** @type {Record<string, string>} */ (NATIVE_TO_KIND)[nativeEvent] ??
     EventKind.UNKNOWN;
   const response = kind === EventKind.POST_TOOL ? raw.tool_response : undefined;
+  const nativeTool = claudeTool(kind, raw);
+  const meta = claudeMeta(nativeEvent, raw);
+  if (nativeTool !== null) meta.native_tool = nativeTool;
   return makeEvent({
     event: kind,
-    tool: claudeTool(kind, raw),
+    tool: canonicalTool(nativeTool),
     input: claudeInput(kind, raw),
     response,
-    this_call_vetoable: true,
-    meta: claudeMeta(nativeEvent, raw),
+    // Classify on the NATIVE name — MCP detection keys on `mcp__…`, which a
+    // canonical builtin name would never carry.
+    this_call_vetoable: coverageAllowsVeto(
+      COVERAGE[classifyCallClass(nativeTool, raw)],
+    ),
+    meta,
   });
 }
 
@@ -212,6 +239,11 @@ function gatingBody(hookEventName, vd, soleGate) {
 function nonGatingBody(hookEventName, vd) {
   /** @type {Record<string, unknown>} */
   const hookSpecificOutput = { hookEventName };
+  // A PostToolUse content transform: `updatedToolOutput` replaces what the model
+  // sees (the tool already ran, so this governs only the model's view). The
+  // native channel for the whole redaction/sanitize pipeline.
+  if (vd.mutated_output !== undefined)
+    hookSpecificOutput.updatedToolOutput = vd.mutated_output;
   if (vd.additional_context !== undefined)
     hookSpecificOutput.additionalContext = vd.additional_context;
   /** @type {Record<string, unknown>} */
@@ -224,4 +256,10 @@ function nonGatingBody(hookEventName, vd) {
 }
 
 /** @type {import("../control-plane.mjs").Adapter} */
-export const claudeAdapter = { AGENT, INTEGRATION_MODE, parse, render };
+export const claudeAdapter = {
+  AGENT,
+  INTEGRATION_MODE,
+  COVERAGE,
+  parse,
+  render,
+};

package/src/adapters/codex.mjs

@@ -15,6 +15,11 @@ import {
   EventKind,
   Decision,
   IntegrationMode,
+  CallClass,
+  CoverageStatus,
+  classifyCallClass,
+  coverageAllowsVeto,
+  canonicalTool,
   makeEvent,
   normalizeVerdict,
   nativeResponse,
@@ -32,6 +37,21 @@ import {
 export const AGENT = "codex";
 export const INTEGRATION_MODE = IntegrationMode.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 = Object.freeze({
+  [CallClass.BUILTIN]: CoverageStatus.PARTIAL,
+  [CallClass.MCP]: CoverageStatus.UNCOVERED,
+  [CallClass.SUBAGENT]: CoverageStatus.UNKNOWN,
+  [CallClass.RESUMED]: CoverageStatus.UNKNOWN,
+});
+
 /** Minimum Codex version whose hook can actually veto a tool call. */
 export const MIN_ENFORCING_VERSION = Object.freeze([0, 135]);
 
@@ -96,12 +116,20 @@ export function parse(native) {
   if (typeof raw.transcript_path === "string")
     meta.transcript_path = raw.transcript_path;
 
+  // Coverage floor: even on an enforcing Codex, `PreToolUse` fires for Bash only,
+  // so an MCP-sourced call is un-vetoable regardless of version (COVERAGE.mcp).
+  // Classify on the NATIVE name (MCP detection keys on `mcp__…`).
+  const nativeTool = asStringOrNull(raw.tool_name);
+  if (nativeTool !== null) meta.native_tool = nativeTool;
+  const vetoable =
+    enforce && coverageAllowsVeto(COVERAGE[classifyCallClass(nativeTool, raw)]);
+
   return makeEvent({
     event: kind,
-    tool: asStringOrNull(raw.tool_name),
+    tool: canonicalTool(nativeTool),
     input: asObject(raw.tool_input),
     response: undefined,
-    this_call_vetoable: enforce,
+    this_call_vetoable: vetoable,
     meta,
   });
 }
@@ -146,4 +174,10 @@ export function render(verdict, event, { soleGate = false } = {}) {
 }
 
 /** @type {import("../control-plane.mjs").Adapter} */
-export const codexAdapter = { AGENT, INTEGRATION_MODE, parse, render };
+export const codexAdapter = {
+  AGENT,
+  INTEGRATION_MODE,
+  COVERAGE,
+  parse,
+  render,
+};

package/src/adapters/gemini.mjs

@@ -23,11 +23,18 @@ import {
   EventKind,
   Decision,
   IntegrationMode,
+  CallClass,
+  CoverageStatus,
+  classifyCallClass,
+  coverageAllowsVeto,
+  canonicalTool,
+  assertAliasTargetsModeled,
   makeEvent,
   normalizeVerdict,
   nativeResponse,
   collectPassthrough,
   asObject,
+  asString,
   asStringOrNull,
 } from "../control-plane.mjs";
 
@@ -39,15 +46,33 @@ import {
 export const AGENT = "gemini";
 export const INTEGRATION_MODE = IntegrationMode.EXTERNAL_HOOK;
 
+/**
+ * Hook-coverage matrix row (`docs/hook-coverage-matrix.md`). `BeforeTool` gates
+ * builtins on v0.26+ (COVERED). MCP routing through the same matcher is only
+ * MEDIUM-confidence and unproven, subagent firing for a loaded agent is
+ * undocumented, and resumed-session behavior has no source — all three are
+ * UNKNOWN, held at fail-closed until an item-⑤ probe upgrades them. A guessed ✅
+ * here would be a silent fail-open.
+ */
+/** @type {import("../control-plane.mjs").CoverageMap} */
+export const COVERAGE = Object.freeze({
+  [CallClass.BUILTIN]: CoverageStatus.COVERED,
+  [CallClass.MCP]: CoverageStatus.UNKNOWN,
+  [CallClass.SUBAGENT]: CoverageStatus.UNKNOWN,
+  [CallClass.RESUMED]: CoverageStatus.UNKNOWN,
+});
+
 /** Gemini CLI native hook event names (the `hook_event_name` field). */
 export const HookEvent = Object.freeze({
   BEFORE_TOOL: "BeforeTool",
   AFTER_TOOL: "AfterTool",
+  BEFORE_AGENT: "BeforeAgent",
 });
 
 const NATIVE_TO_KIND = Object.freeze({
   [HookEvent.BEFORE_TOOL]: EventKind.PRE_TOOL,
   [HookEvent.AFTER_TOOL]: EventKind.POST_TOOL,
+  [HookEvent.BEFORE_AGENT]: EventKind.PROMPT_SUBMIT,
 });
 
 // Only the fields the adapter maps are consumed; everything else (timestamp,
@@ -60,6 +85,7 @@ const CONSUMED = new Set([
   "tool_name",
   "tool_input",
   "tool_response",
+  "prompt",
 ]);
 
 /**
@@ -83,11 +109,67 @@ function geminiMeta(nativeEvent, raw) {
   return meta;
 }
 
+/**
+ * Adapter-scoped native-builtin → canonical tool aliases, applied ONLY when a
+ * call classifies as BUILTIN. These names are too generic for the global
+ * {@link TOOL_ALIASES} (an MCP server could export a `read_file`), but Gemini
+ * CLI removes the ambiguity at parse time: every MCP tool is unconditionally
+ * registered — and surfaced in hook payloads — under its fully qualified
+ * `mcp_{server}_{tool}` name (gemini-cli docs/tools/mcp-server.md), so a bare
+ * builtin name in `tool_name` can only be the builtin. The builtin's native
+ * input fields still pass through verbatim (e.g. read_file's `absolute_path`,
+ * not Read's `file_path`) — `meta.native_tool` tells a consumer which field
+ * dialect to expect. Targets are pinned to {@link MODELED_TOOLS} at import, and
+ * every entry must be witnessed by a gemini conformance fixture
+ * (`assertToolAliasesCovered`).
+ * @type {Readonly<Record<string, string>>}
+ */
+export const GEMINI_TOOL_ALIASES = Object.freeze({
+  read_file: "Read",
+  write_file: "Write",
+  web_fetch: "WebFetch",
+});
+
+assertAliasTargetsModeled(GEMINI_TOOL_ALIASES);
+
+/**
+ * Canonicalize a Gemini native tool name: adapter-scoped builtin aliases first
+ * (BUILTIN calls only — an MCP- or context-flagged call is never reclassified),
+ * then the global {@link canonicalTool} map, else verbatim.
+ * @param {string|null} nativeTool
+ * @param {string} callClass a {@link CallClass} value
+ * @returns {string|null}
+ */
+function geminiCanonicalTool(nativeTool, callClass) {
+  if (nativeTool !== null && callClass === CallClass.BUILTIN) {
+    const scoped = GEMINI_TOOL_ALIASES[nativeTool];
+    if (scoped !== undefined) return scoped;
+  }
+  return canonicalTool(nativeTool);
+}
+
+/**
+ * @param {string} kind
+ * @param {Record<string, unknown>} raw
+ * @returns {Record<string, unknown>}
+ */
+function geminiInput(kind, raw) {
+  if (kind === EventKind.PROMPT_SUBMIT)
+    return { prompt: asString(raw.prompt, "") };
+  if (kind === EventKind.PRE_TOOL || kind === EventKind.POST_TOOL)
+    return asObject(raw.tool_input);
+  return {};
+}
+
 /**
  * Parse a raw Gemini CLI hook payload into a normalized {@link ToolCallEvent}.
- * Never throws on an unmodelled event type or tool-input field. Any payload we
- * receive comes from a hooks-capable Gemini (v0.26.0+) whose `BeforeTool` can
- * pre-empt via exit 2, so `this_call_vetoable` is true.
+ * Never throws on an unmodelled event type or tool-input field. A payload comes
+ * from a hooks-capable Gemini (v0.26.0+) whose `BeforeTool` can pre-empt builtin
+ * tools via exit 2. But MCP firing is only medium-confidence (COVERAGE.mcp is
+ * UNKNOWN), so an MCP-sourced call — flagged by `mcp_context` or an `mcp_`-named
+ * tool — parses non-vetoable until an item-⑤ probe confirms the hook fires.
+ * `BeforeAgent` (fires after the user submits a prompt, before planning) maps to
+ * `prompt_submit`: no tool, the submitted text folded into `input.prompt`.
  * @param {any} native
  * @returns {ToolCallEvent}
  */
@@ -100,22 +182,31 @@ export function parse(native) {
     EventKind.UNKNOWN;
   const gating = kind === EventKind.PRE_TOOL || kind === EventKind.POST_TOOL;
   const response = kind === EventKind.POST_TOOL ? raw.tool_response : undefined;
+  const nativeTool = gating ? asStringOrNull(raw.tool_name) : null;
+  const meta = geminiMeta(nativeEvent, raw);
+  if (nativeTool !== null) meta.native_tool = nativeTool;
+  // Classify on the NATIVE name (MCP detection keys on the `mcp_…` FQN prefix
+  // every Gemini MCP tool carries); the class gates both the veto flag and the
+  // builtin-only adapter-scoped aliases.
+  const callClass = classifyCallClass(nativeTool, raw);
   return makeEvent({
     event: kind,
-    tool: gating ? asStringOrNull(raw.tool_name) : null,
-    input: gating ? asObject(raw.tool_input) : {},
+    tool: geminiCanonicalTool(nativeTool, callClass),
+    input: geminiInput(kind, raw),
     response,
-    this_call_vetoable: true,
-    meta: geminiMeta(nativeEvent, raw),
+    this_call_vetoable: coverageAllowsVeto(COVERAGE[callClass]),
+    meta,
   });
 }
 
 /**
  * Render into Gemini CLI's native external-hook transport. An enforceable deny
- * renders as exit 2 (the System Block); everything else exits 0 with a JSON
- * decision body (or none, when `allow` abstains). `soleGate` (default false) is
- * the same dangerous opt-in as the other adapters: it makes an `allow` emit the
- * real `decision: "allow"` instead of abstaining.
+ * renders as exit 2 (the System Block on BeforeTool; documented on BeforeAgent
+ * as "same as decision: deny" — it aborts the turn); everything else exits 0
+ * with a JSON decision body (or none, when `allow` abstains). `soleGate`
+ * (default false) is the same dangerous opt-in as the other adapters: it makes
+ * an `allow` emit the real `decision: "allow"` instead of abstaining (tool
+ * events only — BeforeAgent documents no allow behavior to opt into).
  * @param {Verdict} verdict
  * @param {ToolCallEvent} event
  * @param {{ soleGate?: boolean }} [options]
@@ -134,7 +225,10 @@ export function render(verdict, event, { soleGate = false } = {}) {
       enforced: true,
     });
 
-  const body = decisionBody(vd, soleGate);
+  const body =
+    event.event === EventKind.PROMPT_SUBMIT
+      ? promptSubmitBody(vd)
+      : decisionBody(vd, soleGate);
   return nativeResponse({
     transport: INTEGRATION_MODE,
     exit_code: 0,
@@ -171,5 +265,36 @@ function decisionBody(vd, soleGate) {
   return Object.keys(out).length > 0 ? out : undefined;
 }
 
+/**
+ * Build the exit-0 stdout body for a `prompt_submit` (BeforeAgent) render.
+ * BeforeAgent's documented channels differ from BeforeTool's: `decision:
+ * "deny"` blocks the turn and discards the prompt, and context injection is
+ * `hookSpecificOutput.additionalContext` (appended to the prompt for this turn
+ * only) — there is no `tool_input` to mutate and no documented allow decision,
+ * so `allow` always abstains and `mutated_input` has no home here. `deny`/`ask`
+ * both surface `decision: "deny"` with the reason, mirroring how BeforeTool
+ * renders ask (Gemini has no native ask tier). Returns undefined when there is
+ * nothing to emit.
+ * @param {Verdict} vd
+ * @returns {Record<string, unknown>|undefined}
+ */
+function promptSubmitBody(vd) {
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  if (vd.decision === Decision.DENY || vd.decision === Decision.ASK) {
+    out.decision = "deny";
+    if (vd.reason !== undefined) out.reason = vd.reason;
+  }
+  if (vd.additional_context !== undefined)
+    out.hookSpecificOutput = { additionalContext: vd.additional_context };
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
 /** @type {import("../control-plane.mjs").Adapter} */
-export const geminiAdapter = { AGENT, INTEGRATION_MODE, parse, render };
+export const geminiAdapter = {
+  AGENT,
+  INTEGRATION_MODE,
+  COVERAGE,
+  parse,
+  render,
+};