agent-control-plane-core 0.11.2 → 0.13.0

package/README.md

@@ -182,6 +182,56 @@ on a non-blocking pipe. The entries ship as `acp-claude-hook`, `acp-codex-hook`,
 set `ACP_CODEX_VERSION` to the Codex version your launcher pins (or call
 `createCodexAdapter({ version })`); without it, Codex calls parse advisory.
 
+A judge may return its verdict or a promise of one, so a judge can ask a
+remote monitor before it answers. `renderHookResponse` returns a promise.
+`adapterFor(id, options)` takes the options its `LAUNCHER_OPTIONS[id]` row
+names, so a launcher passes a pinned version to whichever agents read one
+without naming them.
+
+A consumer that cannot import these modules (a bash hook wrapper, a Python
+monitor) reads `schema/control-plane/v1/agents.json` instead. It is generated
+from the adapters, with one row per agent: its block exit code and reason
+stream, whether a block needs a reason, whether it has an ask tier, the entry's
+default response when the hook breaks, its hook coverage, the verdict
+fields an allow cannot carry, and two pre-tool facts:
+
+- `pre_tool_response`: `hook_specific_output_keys` lists the
+  `hookSpecificOutput` keys the host reads on an exit-0 pre-tool answer.
+  `unread_key_fails_open` says what any other key does there: `true` means the
+  host discards the whole body and runs the call (Codex), `false` means the key
+  is ignored, `null` means unknown. The conformance harness fails an adapter
+  whose pre-tool render emits a key outside the list. Neither field covers the
+  body's top-level keys, which Codex also parses strictly.
+- `pre_tool_filing`: how the pre-tool hook files a model's tool call, so a
+  monitor can match the model's calls against the hook's. It is keyed by model
+  tool name: the call's `name`, prefixed with its `namespace` with no
+  separator, unless the namespace is empty or Codex's default `functions`
+  (`flatToolName` in `/contract`). Each value is one of:
+  - `null`: no pre-tool hook fires for this call.
+  - `{"tool_name": T, "input": I}`: the hook files `tool_name` T, and builds
+    `tool_input` from I. I is either `"$"`, meaning the call's whole arguments
+    value, or an object whose values are each `"$"` or `"$.<key>"`, meaning
+    that top-level argument. `<key>` is one literal key, non-empty and with no
+    `.`. If a `"$.<key>"` does not resolve (the arguments are not an object,
+    lack the key, or hold `null` there), the hook files nothing.
+
+  A function call the map does not list is filed with the model's own name and
+  arguments. A freeform (custom) call the map does not list files nothing; of
+  the shipped hosts only Codex makes them. The map describes calls the host
+  dispatches: Codex files nothing for a call it rejects first, e.g. a name it
+  has no tool for, a call kind the tool does not take, or arguments a handler
+  refuses before its hook (an `apply_patch` patch that does not parse, an
+  `exec_command` with a non-string `workdir`). On Codex the arguments value is a function call's
+  `arguments` parsed as JSON (an empty or all-whitespace string reads as `{}`,
+  unparseable text stays the raw string), or a freeform call's raw `input`
+  string. `fileModelCall` in `/contract` is the reference implementation; it
+  takes the call's kind, `"function"` or `"freeform"`. The map does not model
+  Codex's MCP names: Codex files an MCP call as `mcp__<namespace>__<tool>`,
+  which can differ from the flat name.
+
+Read the file from the installed package, so it always matches the adapters
+that version ships.
+
 Each entry fails the way its host expects when the hook itself breaks: claude,
 codex and gemini run the call, and amp asks. Set `ACP_FAIL_CLOSED=1` to block
 instead, on every host. The entry then exits 2 with the reason on stderr when

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-control-plane-core",
-  "version": "0.11.2",
+  "version": "0.13.0",
   "description": "Vendor-neutral control-plane contract for coding agents: a normalized ToolCallEvent/Verdict schema with per-agent adapters (Claude Code, Codex, Amp, Gemini CLI) and a conformance suite.",
   "type": "module",
   "repository": {

package/schema/control-plane/v1/agents.json

@@ -0,0 +1,228 @@
+{
+  "claude": {
+    "integration_mode": "external_hook",
+    "native_ask_tier": true,
+    "block": {
+      "exit_code": 2,
+      "reason_stream": "stderr",
+      "reason_required": false
+    },
+    "host_failure": {
+      "exit_code": 0,
+      "enforced": false
+    },
+    "coverage": {
+      "builtin": "covered",
+      "mcp": "covered",
+      "subagent": "covered",
+      "resumed": "covered"
+    },
+    "unrendered_fields_on_allow": {
+      "pre_tool": [
+        "mutated_output"
+      ],
+      "post_tool": [
+        "mutated_input"
+      ],
+      "prompt_submit": [
+        "mutated_input",
+        "mutated_output"
+      ],
+      "session_start": [
+        "mutated_input",
+        "mutated_output"
+      ],
+      "unknown": [
+        "additional_context",
+        "mutated_input",
+        "mutated_output"
+      ]
+    },
+    "pre_tool_filing": {},
+    "pre_tool_response": {
+      "hook_specific_output_keys": [
+        "additionalContext",
+        "hookEventName",
+        "permissionDecision",
+        "permissionDecisionReason",
+        "updatedInput"
+      ],
+      "unread_key_fails_open": null
+    }
+  },
+  "codex": {
+    "integration_mode": "external_hook",
+    "native_ask_tier": false,
+    "block": {
+      "exit_code": 2,
+      "reason_stream": "stderr",
+      "reason_required": true
+    },
+    "host_failure": {
+      "exit_code": 0,
+      "enforced": false
+    },
+    "coverage": {
+      "builtin": "partial",
+      "mcp": "partial",
+      "subagent": "partial",
+      "resumed": "partial"
+    },
+    "unrendered_fields_on_allow": {
+      "pre_tool": [
+        "additional_context",
+        "mutated_output"
+      ],
+      "post_tool": [
+        "mutated_input",
+        "mutated_output"
+      ],
+      "prompt_submit": [
+        "additional_context",
+        "mutated_input",
+        "mutated_output"
+      ],
+      "session_start": [
+        "additional_context",
+        "mutated_input",
+        "mutated_output"
+      ],
+      "unknown": [
+        "additional_context",
+        "mutated_input",
+        "mutated_output"
+      ]
+    },
+    "pre_tool_filing": {
+      "exec_command": {
+        "tool_name": "Bash",
+        "input": {
+          "command": "$.cmd"
+        }
+      },
+      "apply_patch": {
+        "tool_name": "apply_patch",
+        "input": {
+          "command": "$"
+        }
+      },
+      "multi_agent_v1spawn_agent": {
+        "tool_name": "spawn_agent",
+        "input": "$"
+      },
+      "write_stdin": null,
+      "wait": null,
+      "exec": null
+    },
+    "pre_tool_response": {
+      "hook_specific_output_keys": [
+        "additionalContext",
+        "hookEventName",
+        "permissionDecision",
+        "permissionDecisionReason",
+        "updatedInput"
+      ],
+      "unread_key_fails_open": true
+    }
+  },
+  "amp": {
+    "integration_mode": "external_hook",
+    "native_ask_tier": true,
+    "block": {
+      "exit_code": 2,
+      "reason_stream": "stderr",
+      "reason_required": false
+    },
+    "host_failure": {
+      "exit_code": 1,
+      "enforced": false
+    },
+    "coverage": {
+      "builtin": "covered",
+      "mcp": "covered",
+      "subagent": "covered",
+      "resumed": "unknown"
+    },
+    "unrendered_fields_on_allow": {
+      "pre_tool": [
+        "additional_context",
+        "mutated_input",
+        "mutated_output"
+      ],
+      "post_tool": [
+        "additional_context",
+        "mutated_input",
+        "mutated_output"
+      ],
+      "prompt_submit": [
+        "additional_context",
+        "mutated_input",
+        "mutated_output"
+      ],
+      "session_start": [
+        "additional_context",
+        "mutated_input",
+        "mutated_output"
+      ],
+      "unknown": [
+        "additional_context",
+        "mutated_input",
+        "mutated_output"
+      ]
+    },
+    "pre_tool_filing": {},
+    "pre_tool_response": {
+      "hook_specific_output_keys": [],
+      "unread_key_fails_open": false
+    }
+  },
+  "gemini": {
+    "integration_mode": "external_hook",
+    "native_ask_tier": false,
+    "block": {
+      "exit_code": 2,
+      "reason_stream": "stderr",
+      "reason_required": false
+    },
+    "host_failure": {
+      "exit_code": 0,
+      "enforced": false
+    },
+    "coverage": {
+      "builtin": "covered",
+      "mcp": "unknown",
+      "subagent": "unknown",
+      "resumed": "unknown"
+    },
+    "unrendered_fields_on_allow": {
+      "pre_tool": [
+        "mutated_output"
+      ],
+      "post_tool": [
+        "mutated_input",
+        "mutated_output"
+      ],
+      "prompt_submit": [
+        "mutated_input",
+        "mutated_output"
+      ],
+      "session_start": [
+        "additional_context",
+        "mutated_input",
+        "mutated_output"
+      ],
+      "unknown": [
+        "additional_context",
+        "mutated_input",
+        "mutated_output"
+      ]
+    },
+    "pre_tool_filing": {},
+    "pre_tool_response": {
+      "hook_specific_output_keys": [
+        "tool_input"
+      ],
+      "unread_key_fails_open": false
+    }
+  }
+}

package/src/adapters/amp.mjs

@@ -169,6 +169,23 @@ export function parse(native) {
  */
 export const NATIVE_ASK_TIER = true;
 
+/**
+ * No rename is modelled: no source shows Amp filing a call under a
+ * name or input other than the model's.
+ * @type {import("../control-plane.mjs").PreToolFiling}
+ */
+export const PRE_TOOL_FILING = Object.freeze({});
+
+/**
+ * Amp reads only the hook's exit code and no body, so no key in one can change
+ * the outcome.
+ * @type {import("../control-plane.mjs").PreToolResponse}
+ */
+export const PRE_TOOL_RESPONSE = Object.freeze({
+  hook_specific_output_keys: Object.freeze([]),
+  unread_key_fails_open: false,
+});
+
 /**
  * The EXHAUSTIVE (decision × `this_call_vetoable`) → exit-code table for Amp's
  * pure exit-code transport: 0 allow / 1 ask / 2 reject.
@@ -288,6 +305,8 @@ export const ampAdapter = {
   UNRENDERED_FIELDS,
   NATIVE_ASK_TIER,
   NATIVE_EVENT_FOR,
+  PRE_TOOL_FILING,
+  PRE_TOOL_RESPONSE,
   parse,
   render,
 };

package/src/adapters/claude.mjs

@@ -125,6 +125,32 @@ export const UNRENDERED_FIELDS = Object.freeze({
  */
 export const NATIVE_ASK_TIER = true;
 
+/**
+ * No rename is modelled: no source shows Claude Code filing a call under a
+ * name or input other than the model's.
+ * @type {import("../control-plane.mjs").PreToolFiling}
+ */
+export const PRE_TOOL_FILING = Object.freeze({});
+
+/**
+ * The `hookSpecificOutput` keys Claude Code's hooks reference documents for
+ * `PreToolUse` (https://code.claude.com/docs/en/hooks). Whether an unread key
+ * fails open is NOT established: the reference says an exit-0 body that fails
+ * schema validation lets the call go ahead, but not whether an extra key fails
+ * it, and the host's source is not public.
+ * @type {import("../control-plane.mjs").PreToolResponse}
+ */
+export const PRE_TOOL_RESPONSE = Object.freeze({
+  hook_specific_output_keys: Object.freeze([
+    "additionalContext",
+    "hookEventName",
+    "permissionDecision",
+    "permissionDecisionReason",
+    "updatedInput",
+  ]),
+  unread_key_fails_open: null,
+});
+
 /** Claude Code native hook event names (the `hook_event_name` field). */
 export const HookEvent = Object.freeze({
   PRE_TOOL_USE: "PreToolUse",
@@ -339,6 +365,8 @@ export const claudeAdapter = {
   UNRENDERED_FIELDS,
   NATIVE_ASK_TIER,
   NATIVE_EVENT_FOR,
+  PRE_TOOL_FILING,
+  PRE_TOOL_RESPONSE,
   parse,
   render,
 };

package/src/adapters/codex.mjs

@@ -39,6 +39,7 @@ import {
   asObject,
   asString,
   asStringOrNull,
+  WHOLE_ARGUMENTS,
 } from "../control-plane.mjs";
 
 /** @typedef {import("../control-plane.mjs").ToolCallEvent} ToolCallEvent */
@@ -130,6 +131,67 @@ export const UNRENDERED_FIELDS = Object.freeze({
   [EventKind.POST_TOOL]: readonlySet(["mutated_input", "mutated_output"]),
 });
 
+/**
+ * How Codex's `PreToolUse` hook files a model tool call ([X7], read from
+ * Codex's source at `rust-v0.166.0`). A function tool is filed under its flat
+ * name (namespace + name) with its parsed arguments by default; these
+ * handlers supply their own payload or none:
+ * - `exec_command` → `Bash` with `{command: <cmd>}`; arguments Codex cannot
+ *   parse as `ExecCommandArgs` file nothing, which this table models only for
+ *   a missing or null `cmd` or scalar arguments. Not modelled: other type
+ *   errors, and a positional array, which serde reads (`["ls"]` is `cmd: "ls"`).
+ * - `apply_patch` (a freeform tool) → `apply_patch` with its raw patch text as
+ *   `command`.
+ * - `spawn_agent` in the `multi_agent_v1` namespace → `spawn_agent`.
+ * - `write_stdin`, code mode's `wait`, and code mode's freeform `exec` → no hook.
+ *   These rules assume the named tool owns the name; a client-defined tool
+ *   called `wait` with code mode off takes the default payload.
+ *   The default payload is function-only, so a freeform extension tool files
+ *   nothing too — the mini-language's rule for an unlisted freeform call.
+ * NOT MODELLED: Codex files an MCP call as `mcp__<namespace>__<tool>`, with
+ * `_` trimmed from the namespace's end and the tool's start (`mcp.rs`
+ * `hook_tool_name`), which can differ from the flat name — a rule keyed by
+ * one name cannot express that.
+ * @type {import("../control-plane.mjs").PreToolFiling}
+ */
+export const PRE_TOOL_FILING = Object.freeze({
+  exec_command: Object.freeze({
+    tool_name: "Bash",
+    input: Object.freeze({ command: "$.cmd" }),
+  }),
+  apply_patch: Object.freeze({
+    tool_name: "apply_patch",
+    input: Object.freeze({ command: WHOLE_ARGUMENTS }),
+  }),
+  multi_agent_v1spawn_agent: Object.freeze({
+    tool_name: "spawn_agent",
+    input: WHOLE_ARGUMENTS,
+  }),
+  write_stdin: null,
+  wait: null,
+  exec: null,
+});
+
+/**
+ * Codex's `PreToolUse` output parser ([X8], `rust-v0.166.0`) deserializes
+ * `hookSpecificOutput` into a `deny_unknown_fields` struct of exactly these
+ * five keys. Any other key fails the whole body: the run is marked failed, no
+ * block is set, and the call RUNS. A known key can still void the body by its
+ * combination (`updatedInput` without `permissionDecision: "allow"`), which
+ * this declaration does not describe.
+ * @type {import("../control-plane.mjs").PreToolResponse}
+ */
+export const PRE_TOOL_RESPONSE = Object.freeze({
+  hook_specific_output_keys: Object.freeze([
+    "additionalContext",
+    "hookEventName",
+    "permissionDecision",
+    "permissionDecisionReason",
+    "updatedInput",
+  ]),
+  unread_key_fails_open: true,
+});
+
 /** Minimum Codex version whose hook can actually veto a tool call. */
 export const MIN_ENFORCING_VERSION = Object.freeze([0, 135]);
 
@@ -411,16 +473,28 @@ function postToolBody(hookEventName, vd, enforced) {
   return body;
 }
 
+/** The launcher option names {@link createCodexAdapter} reads. */
+export const OPTION_NAMES = Object.freeze(["version"]);
+
 /**
  * Build a Codex adapter whose `parse` judges every payload against `version`,
  * the Codex version the launcher pinned (Codex's hook stdin carries none).
  * Below {@link MIN_ENFORCING_VERSION} every event parses observe-only and a
  * deny renders advisory. With no `version`, `parse` falls back to a payload
- * `version` (see {@link parse}).
+ * `version` (see {@link parse}). An option outside {@link OPTION_NAMES} throws,
+ * so a misspelled setting is never dropped in silence.
  * @param {{ version?: string }} [options]
  * @returns {import("../control-plane.mjs").Adapter}
  */
-export function createCodexAdapter({ version } = {}) {
+export function createCodexAdapter(options = {}) {
+  const unread = Object.keys(options).filter(
+    (name) => !OPTION_NAMES.includes(name),
+  );
+  if (unread.length > 0)
+    throw new Error(
+      `codex: no option ${unread.map((name) => JSON.stringify(name)).join(", ")} (reads: ${OPTION_NAMES.join(", ")})`,
+    );
+  const { version } = options;
   return {
     AGENT,
     INTEGRATION_MODE,
@@ -428,6 +502,8 @@ export function createCodexAdapter({ version } = {}) {
     UNRENDERED_FIELDS,
     NATIVE_ASK_TIER,
     NATIVE_EVENT_FOR,
+    PRE_TOOL_FILING,
+    PRE_TOOL_RESPONSE,
     parse: (native) => parse(native, { version }),
     render,
   };

package/src/adapters/gemini.mjs

@@ -357,6 +357,28 @@ export function parse(native) {
  */
 export const NATIVE_ASK_TIER = false;
 
+/**
+ * No rename is modelled. Gemini CLI hands `BeforeTool` the invocation's tool
+ * name beside an `originalRequestName`, so an aliased call may be filed under
+ * a name the model did not use; that is unverified, so not published.
+ * @type {import("../control-plane.mjs").PreToolFiling}
+ */
+export const PRE_TOOL_FILING = Object.freeze({});
+
+/**
+ * Gemini CLI keeps `hookSpecificOutput` as a `Record<string, unknown>` and its
+ * `BeforeTool` path reads only `tool_input` from it, by `in` lookup, so any
+ * other key is ignored (`packages/core/src/hooks/types.ts`
+ * `BeforeToolHookOutput`; both firing paths, `core/coreToolHookTriggers.ts`
+ * and `scheduler/hook-utils.ts` `evaluateBeforeToolHook`, read at gemini-cli
+ * `62bab5b2`).
+ * @type {import("../control-plane.mjs").PreToolResponse}
+ */
+export const PRE_TOOL_RESPONSE = Object.freeze({
+  hook_specific_output_keys: Object.freeze(["tool_input"]),
+  unread_key_fails_open: false,
+});
+
 /**
  * Render into Gemini CLI's native external-hook transport. An enforceable deny
  * renders as exit 2 (the System Block on BeforeTool; documented on BeforeAgent
@@ -477,6 +499,8 @@ export const geminiAdapter = {
   UNRENDERED_FIELDS,
   NATIVE_ASK_TIER,
   NATIVE_EVENT_FOR,
+  PRE_TOOL_FILING,
+  PRE_TOOL_RESPONSE,
   parse,
   render,
 };

package/src/agent-manifest.mjs

@@ -0,0 +1,82 @@
+/**
+ * The per-agent manifest: what each agent's hook transport does, published as
+ * plain JSON at `schema/control-plane/v1/agents.json`.
+ *
+ * PROBLEM CLASS — a consumer that cannot call these adapters (a bash hook
+ * wrapper, a Python validator) re-types each agent's rules by hand: which exit
+ * code blocks, whether a block needs a reason, whether an `ask` has a tier.
+ * Each copy is one more place an agent's next release has to be chased into.
+ * `agents.json` is the copy they read instead, generated from the adapters'
+ * exports, so an adapter change reaches them on the next `pnpm gen:schema`.
+ *
+ * `pnpm gen:schema` writes every {@link generatedDocuments} entry, and
+ * `json-schema.test.mjs` regenerates each in-process and byte-compares.
+ */
+
+import { EventKind, blockTransportFor, lookup } from "./control-plane.mjs";
+import { jsonSchemaDocuments, SCHEMA_DIR } from "./json-schema.mjs";
+import { ADAPTERS, AGENT_IDS } from "./registry.mjs";
+import { HOST_FAILURE } from "./runtime.mjs";
+
+/**
+ * One agent's manifest row. Each field is read from the export it names:
+ * - `integration_mode`: the adapter's `INTEGRATION_MODE`.
+ * - `native_ask_tier`: `NATIVE_ASK_TIER`. `false` means an `ask` the host
+ *   receives does not stop the call, so a consumer must block instead.
+ * - `block`: the `BLOCK_TRANSPORT` row: the exit code the host blocks on, the
+ *   stream it reads the reason from, and whether an empty reason runs the call.
+ * - `host_failure`: the `HOST_FAILURE` row, the hook entry's DEFAULT response
+ *   when the hook breaks (exit 0 runs the call; amp's exit 1 asks the human).
+ *   `ACP_FAIL_CLOSED=1` replaces it with `block`.
+ * - `coverage`: `COVERAGE`, per call class.
+ * - `unrendered_fields_on_allow`: `UNRENDERED_FIELDS`, each set as a sorted
+ *   list. It describes the allow path only: a deny can drop more.
+ * - `pre_tool_filing`: `PRE_TOOL_FILING`, how the pre-tool hook files a model
+ *   tool call, in the mini-language the `PreToolFiling` typedef specifies.
+ * - `pre_tool_response`: `PRE_TOOL_RESPONSE`, the `hookSpecificOutput` keys the
+ *   host reads on an exit-0 pre-tool answer, and `unread_key_fails_open`
+ *   (`true`: any other key voids the body and the call runs; `null`: unknown).
+ * @param {string} id
+ * @returns {Record<string, unknown>}
+ */
+function manifestRow(id) {
+  const adapter = ADAPTERS[id];
+  const failure = HOST_FAILURE[id];
+  return {
+    integration_mode: adapter.INTEGRATION_MODE,
+    native_ask_tier: adapter.NATIVE_ASK_TIER,
+    block: blockTransportFor(id),
+    host_failure: { exit_code: failure.exit_code, enforced: failure.enforced },
+    coverage: adapter.COVERAGE,
+    unrendered_fields_on_allow: Object.fromEntries(
+      // The conformance harness refuses an adapter missing a row, and spreading
+      // a missing one throws here, so a gap never publishes as "every field renders".
+      Object.values(EventKind).map((kind) => [
+        kind,
+        [
+          .../** @type {ReadonlySet<string>} */ (
+            lookup(adapter.UNRENDERED_FIELDS, kind)
+          ),
+        ].sort(),
+      ]),
+    ),
+    pre_tool_filing: adapter.PRE_TOOL_FILING,
+    pre_tool_response: adapter.PRE_TOOL_RESPONSE,
+  };
+}
+
+/**
+ * Every generated file, keyed by its package-relative path: the JSON Schema
+ * documents and their data maps, plus `agents.json`, keyed by agent id in
+ * {@link AGENT_IDS} order. The SSOT the generator writes and the freshness test
+ * reads, so neither carries its own list of filenames.
+ * @returns {Record<string, Record<string, unknown>>}
+ */
+export function generatedDocuments() {
+  return {
+    ...jsonSchemaDocuments(),
+    [`${SCHEMA_DIR}/agents.json`]: Object.fromEntries(
+      AGENT_IDS.map((id) => [id, manifestRow(id)]),
+    ),
+  };
+}