agent-control-plane-core 0.11.1 → 0.12.0

package/README.md

@@ -127,7 +127,10 @@ Read `NATIVE_ASK_TIER` instead of keeping a list of which agents to escalate an
 where the flag is `false`, and leaves it alone where the host does the asking.
 `renderEscalated(adapter, verdict, event, { soleGate })` applies that rule: it
 re-renders as a `deny` any non-allow verdict that would render unenforced on a
-vetoable call, except an `ask` on a host whose flag is `true`.
+vetoable call, except an `ask` on a host whose flag is `true`. A non-allow
+verdict on a payload that names no event at all blocks through the host's exit
+code and stderr, since `render` has no channel for it, unless the event parsed
+observe-only (a Codex below its enforcing version), which cannot veto.
 It describes the HOST, not the verdict — `ask` renders as `enforced: false`
 everywhere — and it names the pre-tool gate, since a tool that already ran has
 nothing left to suspend. Conformance probes your real `render` against it, so a
@@ -179,6 +182,20 @@ 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, and the verdict
+fields an allow cannot carry. 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.1",
+  "version": "0.12.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,174 @@
+{
+  "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"
+      ]
+    }
+  },
+  "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"
+      ]
+    }
+  },
+  "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"
+      ]
+    }
+  },
+  "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"
+      ]
+    }
+  }
+}

package/src/adapters/codex.mjs

@@ -411,16 +411,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,

package/src/agent-manifest.mjs

@@ -0,0 +1,75 @@
+/**
+ * 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.
+ * @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(),
+      ]),
+    ),
+  };
+}
+
+/**
+ * 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)]),
+    ),
+  };
+}

package/src/control-plane.mjs

@@ -967,6 +967,13 @@ export function gatedResponse(
  * ({@link Adapter} `NATIVE_ASK_TIER`). Nothing changes for an allow, for a call
  * this guardrail cannot veto (a deny there blocks nothing either), or for a
  * render the host already enforces. The deny keeps the verdict's other fields.
+ *
+ * A payload that names no event at all (`meta.native_event` empty) is the one
+ * exception: `render` has no channel for it, so a non-allow verdict there takes
+ * the host's {@link BLOCK_TRANSPORT} block, which stops whatever call the hook
+ * was run for. An observe-only parse renders that block unenforced (exit 0),
+ * since its host cannot veto. An event the payload names but no adapter models keeps the rule
+ * above: on Claude Code's Stop, a block would keep the agent running.
  * @param {Adapter} adapter
  * @param {Verdict} verdict
  * @param {ToolCallEvent} event
@@ -974,7 +981,18 @@ export function gatedResponse(
  * @returns {NativeResponse}
  */
 export function renderEscalated(adapter, verdict, event, options = {}) {
-  const { decision } = normalizeVerdict(verdict);
+  const { decision, reason } = normalizeVerdict(verdict);
+  // This block is what stops a guardrail's deny on an unreadable payload from
+  // rendering as an empty exit 0, which every host runs.
+  if (event.meta.native_event === "" && decision !== Decision.ALLOW)
+    return gatedResponse(adapter.AGENT, {
+      transport: event.meta.integration_mode,
+      // An observe-only parse (a Codex below its enforcing version) has no
+      // veto, so claiming the block was enforced would report a false block.
+      enforced: event.meta.integration_mode !== IntegrationMode.OBSERVE_ONLY,
+      unblocked_exit_code: 0,
+      reason,
+    });
   const response = adapter.render(verdict, event, options);
   if (
     response.enforced ||

package/src/json-schema.mjs

@@ -291,10 +291,10 @@ export function verdictSchema() {
 }
 
 /**
- * Every generated file, keyed by its package-relative path — the SSOT the
- * generator writes and the freshness test reads, so neither carries its own
- * list of filenames. The two `.schema.json` entries are JSON Schema documents;
- * `tool-input-keys.json` is the data map {@link TOOL_INPUT_KEYS_FILE} describes.
+ * The contract's generated files, keyed by package-relative path. The two
+ * `.schema.json` entries are JSON Schema documents; `tool-input-keys.json` is
+ * the data map {@link TOOL_INPUT_KEYS_FILE} describes. `agent-manifest.mjs`'s
+ * `generatedDocuments` adds the per-agent manifest to these.
  * @returns {Record<string, Record<string, unknown>>}
  */
 export function jsonSchemaDocuments() {

package/src/registry.mjs

@@ -16,7 +16,11 @@
 
 import { lookup } from "./control-plane.mjs";
 import { claudeAdapter } from "./adapters/claude.mjs";
-import { codexAdapter, createCodexAdapter } from "./adapters/codex.mjs";
+import {
+  codexAdapter,
+  createCodexAdapter,
+  OPTION_NAMES as CODEX_OPTION_NAMES,
+} from "./adapters/codex.mjs";
 import { ampAdapter } from "./adapters/amp.mjs";
 import { geminiAdapter } from "./adapters/gemini.mjs";
 
@@ -64,23 +68,43 @@ export function assertRegistryConsistent(adapters) {
 assertRegistryConsistent(ADAPTERS);
 
 /**
- * The adapters that take launcher options, keyed by agent id. Only Codex does:
- * its hook stdin carries no version, so the launcher pins one.
- * @type {Readonly<Record<string, (options: any) => Adapter>>}
+ * The adapters that take launcher options, keyed by agent id: the option names
+ * each reads, and its factory. Only Codex takes one: its hook stdin carries no
+ * version, so the launcher pins one.
+ * @type {Readonly<Record<string, Readonly<{ options: readonly string[], create: (options: any) => Adapter }>>>}
  */
 const CONFIGURABLE = Object.freeze({
-  [codexAdapter.AGENT]: createCodexAdapter,
+  [codexAdapter.AGENT]: Object.freeze({
+    options: CODEX_OPTION_NAMES,
+    create: createCodexAdapter,
+  }),
 });
 
+/**
+ * The launcher option names each agent's adapter reads, for EVERY agent id (an
+ * empty list when it reads none). A launcher builds the options for any agent
+ * from this instead of naming the agents that take a version.
+ * @type {Readonly<Record<string, readonly string[]>>}
+ */
+export const LAUNCHER_OPTIONS = Object.freeze(
+  Object.fromEntries(
+    AGENT_IDS.map((id) => [
+      id,
+      lookup(CONFIGURABLE, id)?.options ?? Object.freeze([]),
+    ]),
+  ),
+);
+
 /**
  * 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).
  *
- * `options` are the launcher's settings for that adapter (Codex:
- * `{ version }`). Passing options to an adapter that takes none throws, so a
- * setting the launcher believes it applied cannot be dropped in silence.
+ * `options` are the launcher's settings for that adapter, named by its
+ * {@link LAUNCHER_OPTIONS} row. Options for an adapter that takes none throw
+ * here, and an option a configurable adapter does not read throws in its
+ * factory, so a setting the launcher believes it applied is never dropped.
  * @param {string} id agent id (a {@link AGENT_IDS} member)
  * @param {Record<string, unknown>} [options]
  * @returns {Adapter}
@@ -92,10 +116,10 @@ export function adapterFor(id, options) {
       `registry: no adapter for agent id ${JSON.stringify(id)} (known: ${AGENT_IDS.join(", ")})`,
     );
   if (options === undefined) return adapter;
-  const configure = lookup(CONFIGURABLE, id);
-  if (configure === undefined)
+  const configurable = lookup(CONFIGURABLE, id);
+  if (configurable === undefined)
     throw new Error(
       `registry: adapter ${JSON.stringify(id)} takes no options, got ${JSON.stringify(options)}`,
     );
-  return configure(options);
+  return configurable.create(options);
 }

package/src/runtime.mjs

@@ -20,6 +20,12 @@ import {
   sanitizeVerdict,
 } from "./control-plane.mjs";
 
+/**
+ * A guardrail judge: one normalized event in, its verdict out, synchronously or
+ * as a promise. Its answer is untrusted either way (see {@link renderHookResponse}).
+ * @typedef {(event: import("./control-plane.mjs").ToolCallEvent) => import("./control-plane.mjs").Verdict | Promise<import("./control-plane.mjs").Verdict>} Judge
+ */
+
 /**
  * Read all of stdin to a string.
  * @returns {Promise<string>}
@@ -77,16 +83,18 @@ export function demoJudge(event) {
  * greppable trace. Every host tolerates hook stderr: claude/codex surface it
  * only in verbose/debug on a 0 exit, amp forwards the helper's stderr, and
  * gemini reads stderr as a reason only on exit 2.
- * `judge` is the seam a real deployment fills — {@link demoJudge} is a stand-in,
- * so the guardrail is supplied here rather than by forking this file. Whatever
- * it returns is treated as untrusted (see the clamp below).
+ * `judge` is the seam a real deployment fills, so the guardrail is supplied here
+ * rather than by forking this file ({@link demoJudge} is a stand-in). It may
+ * return a promise (a judge that asks a remote monitor); a rejection takes the
+ * same path as a throw. Whatever it returns is treated as untrusted (see the
+ * clamp below).
  * @param {import("./control-plane.mjs").Adapter} adapter
  * @param {string} rawInput
  * @param {import("./control-plane.mjs").NativeResponse} onFailure
- * @param {(event: import("./control-plane.mjs").ToolCallEvent) => import("./control-plane.mjs").Verdict} [judge]
- * @returns {import("./control-plane.mjs").NativeResponse}
+ * @param {Judge} [judge]
+ * @returns {Promise<import("./control-plane.mjs").NativeResponse>}
  */
-export function renderHookResponse(
+export async function renderHookResponse(
   adapter,
   rawInput,
   onFailure,
@@ -107,7 +115,7 @@ export function renderHookResponse(
     /** @type {unknown} */
     let answer;
     try {
-      answer = judge(event);
+      answer = await judge(event);
     } catch (err) {
       // No `decision`, so the clamp below turns this into an `ask`.
       answer = { reason: `hook judge threw: ${describe(err).split("\n")[0]}` };
@@ -227,9 +235,11 @@ export function failurePosture(agent, env = process.env) {
  * {@link renderHookResponse} with that host's {@link failurePosture}, and
  * {@link emit} the result. Every `bin/<host>-hook.mjs` is this one call. The
  * failure response also answers a stdin read error and, when
- * {@link hookDeadlineMs} is set, a hook still running at that deadline.
+ * {@link hookDeadlineMs} is set, a hook still running at that deadline. It also
+ * answers a judge promise that never settles once nothing else keeps node alive,
+ * which would otherwise end the process with no response.
  * @param {import("./control-plane.mjs").Adapter} adapter
- * @param {(event: import("./control-plane.mjs").ToolCallEvent) => import("./control-plane.mjs").Verdict} [judge]
+ * @param {Judge} [judge]
  * @returns {Promise<never>}
  */
 export async function runHookEntry(adapter, judge = demoJudge) {
@@ -258,7 +268,17 @@ export async function runHookEntry(adapter, judge = demoJudge) {
   } catch (err) {
     return fail("hook stdin error", err);
   }
-  return emit(renderHookResponse(adapter, raw, onFailure, judge));
+  // An unsettled judge promise with no pending I/O drains the event loop, and
+  // node then exits with no response (13 under top-level await, 0 otherwise),
+  // which a fail-open host runs. Registered after stdin is read, so only the
+  // judge can be what never answered.
+  process.once("beforeExit", () =>
+    fail(
+      "hook judge never answered",
+      new Error("the judge's promise never settled"),
+    ),
+  );
+  return emit(await renderHookResponse(adapter, raw, onFailure, judge));
 }
 
 /**

package/types/adapters/codex.d.mts

@@ -58,11 +58,12 @@ export function render(verdict: Verdict, event: ToolCallEvent, { soleGate }?: {
  * 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?: {
     version?: string;
 }): import("../control-plane.mjs").Adapter;
 /** @typedef {import("../control-plane.mjs").ToolCallEvent} ToolCallEvent */
@@ -140,6 +141,8 @@ export const NATIVE_EVENT_FOR: Record<string, string | undefined>;
  * naming a key the host discards.
  */
 export const NATIVE_ASK_TIER: false;
+/** The launcher option names {@link createCodexAdapter} reads. */
+export const OPTION_NAMES: readonly string[];
 /**
  * The Codex adapter with no launcher-pinned version. Real Codex sends no
  * version, so every event it sends parses observe-only here. A deployment that

package/types/agent-manifest.d.mts

@@ -0,0 +1,8 @@
+/**
+ * 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(): Record<string, Record<string, unknown>>;

package/types/control-plane.d.mts

@@ -296,6 +296,13 @@ export function gatedResponse(agent: string, { transport, enforced, unblocked_ex
  * ({@link Adapter} `NATIVE_ASK_TIER`). Nothing changes for an allow, for a call
  * this guardrail cannot veto (a deny there blocks nothing either), or for a
  * render the host already enforces. The deny keeps the verdict's other fields.
+ *
+ * A payload that names no event at all (`meta.native_event` empty) is the one
+ * exception: `render` has no channel for it, so a non-allow verdict there takes
+ * the host's {@link BLOCK_TRANSPORT} block, which stops whatever call the hook
+ * was run for. An observe-only parse renders that block unenforced (exit 0),
+ * since its host cannot veto. An event the payload names but no adapter models keeps the rule
+ * above: on Claude Code's Stop, a block would keep the agent running.
  * @param {Adapter} adapter
  * @param {Verdict} verdict
  * @param {ToolCallEvent} event

package/types/json-schema.d.mts

@@ -25,10 +25,10 @@ export function toolCallEventSchema(): Record<string, unknown>;
  */
 export function verdictSchema(): Record<string, unknown>;
 /**
- * Every generated file, keyed by its package-relative path — the SSOT the
- * generator writes and the freshness test reads, so neither carries its own
- * list of filenames. The two `.schema.json` entries are JSON Schema documents;
- * `tool-input-keys.json` is the data map {@link TOOL_INPUT_KEYS_FILE} describes.
+ * The contract's generated files, keyed by package-relative path. The two
+ * `.schema.json` entries are JSON Schema documents; `tool-input-keys.json` is
+ * the data map {@link TOOL_INPUT_KEYS_FILE} describes. `agent-manifest.mjs`'s
+ * `generatedDocuments` adds the per-agent manifest to these.
  * @returns {Record<string, Record<string, unknown>>}
  */
 export function jsonSchemaDocuments(): Record<string, Record<string, unknown>>;

package/types/registry.d.mts

@@ -13,9 +13,10 @@ export function assertRegistryConsistent(adapters: Record<string, Adapter>): voi
  * reason to silently fall back to a default agent (which would run the wrong
  * translator against the payloads and mis-render every verdict).
  *
- * `options` are the launcher's settings for that adapter (Codex:
- * `{ version }`). Passing options to an adapter that takes none throws, so a
- * setting the launcher believes it applied cannot be dropped in silence.
+ * `options` are the launcher's settings for that adapter, named by its
+ * {@link LAUNCHER_OPTIONS} row. Options for an adapter that takes none throw
+ * here, and an option a configurable adapter does not read throws in its
+ * factory, so a setting the launcher believes it applied is never dropped.
  * @param {string} id agent id (a {@link AGENT_IDS} member)
  * @param {Record<string, unknown>} [options]
  * @returns {Adapter}
@@ -37,4 +38,11 @@ export const ADAPTERS: Readonly<Record<string, Adapter>>;
  * @type {readonly string[]}
  */
 export const AGENT_IDS: readonly string[];
+/**
+ * The launcher option names each agent's adapter reads, for EVERY agent id (an
+ * empty list when it reads none). A launcher builds the options for any agent
+ * from this instead of naming the agents that take a version.
+ * @type {Readonly<Record<string, readonly string[]>>}
+ */
+export const LAUNCHER_OPTIONS: Readonly<Record<string, readonly string[]>>;
 export type Adapter = import("./control-plane.mjs").Adapter;

package/types/runtime.d.mts

@@ -1,3 +1,8 @@
+/**
+ * A guardrail judge: one normalized event in, its verdict out, synchronously or
+ * as a promise. Its answer is untrusted either way (see {@link renderHookResponse}).
+ * @typedef {(event: import("./control-plane.mjs").ToolCallEvent) => import("./control-plane.mjs").Verdict | Promise<import("./control-plane.mjs").Verdict>} Judge
+ */
 /**
  * Read all of stdin to a string.
  * @returns {Promise<string>}
@@ -31,16 +36,18 @@ export function demoJudge(event: import("./control-plane.mjs").ToolCallEvent): i
  * greppable trace. Every host tolerates hook stderr: claude/codex surface it
  * only in verbose/debug on a 0 exit, amp forwards the helper's stderr, and
  * gemini reads stderr as a reason only on exit 2.
- * `judge` is the seam a real deployment fills — {@link demoJudge} is a stand-in,
- * so the guardrail is supplied here rather than by forking this file. Whatever
- * it returns is treated as untrusted (see the clamp below).
+ * `judge` is the seam a real deployment fills, so the guardrail is supplied here
+ * rather than by forking this file ({@link demoJudge} is a stand-in). It may
+ * return a promise (a judge that asks a remote monitor); a rejection takes the
+ * same path as a throw. Whatever it returns is treated as untrusted (see the
+ * clamp below).
  * @param {import("./control-plane.mjs").Adapter} adapter
  * @param {string} rawInput
  * @param {import("./control-plane.mjs").NativeResponse} onFailure
- * @param {(event: import("./control-plane.mjs").ToolCallEvent) => import("./control-plane.mjs").Verdict} [judge]
- * @returns {import("./control-plane.mjs").NativeResponse}
+ * @param {Judge} [judge]
+ * @returns {Promise<import("./control-plane.mjs").NativeResponse>}
  */
-export function renderHookResponse(adapter: import("./control-plane.mjs").Adapter, rawInput: string, onFailure: import("./control-plane.mjs").NativeResponse, judge?: (event: import("./control-plane.mjs").ToolCallEvent) => import("./control-plane.mjs").Verdict): import("./control-plane.mjs").NativeResponse;
+export function renderHookResponse(adapter: import("./control-plane.mjs").Adapter, rawInput: string, onFailure: import("./control-plane.mjs").NativeResponse, judge?: Judge): Promise<import("./control-plane.mjs").NativeResponse>;
 /**
  * The response that BLOCKS the call on `agent`'s host: its
  * {@link BLOCK_TRANSPORT} row's exit code, with `reason` on the row's reason
@@ -69,12 +76,14 @@ export function failurePosture(agent: string, env?: NodeJS.ProcessEnv): import("
  * {@link renderHookResponse} with that host's {@link failurePosture}, and
  * {@link emit} the result. Every `bin/<host>-hook.mjs` is this one call. The
  * failure response also answers a stdin read error and, when
- * {@link hookDeadlineMs} is set, a hook still running at that deadline.
+ * {@link hookDeadlineMs} is set, a hook still running at that deadline. It also
+ * answers a judge promise that never settles once nothing else keeps node alive,
+ * which would otherwise end the process with no response.
  * @param {import("./control-plane.mjs").Adapter} adapter
- * @param {(event: import("./control-plane.mjs").ToolCallEvent) => import("./control-plane.mjs").Verdict} [judge]
+ * @param {Judge} [judge]
  * @returns {Promise<never>}
  */
-export function runHookEntry(adapter: import("./control-plane.mjs").Adapter, judge?: (event: import("./control-plane.mjs").ToolCallEvent) => import("./control-plane.mjs").Verdict): Promise<never>;
+export function runHookEntry(adapter: import("./control-plane.mjs").Adapter, judge?: Judge): Promise<never>;
 /**
  * `ACP_HOOK_TIMEOUT_MS` as a positive integer, or `undefined` when unset. Set it
  * below the host's own hook timeout, so the hook's failure response lands
@@ -135,3 +144,8 @@ export function emit(response: import("./control-plane.mjs").NativeResponse): ne
  * @type {Readonly<Record<string, import("./control-plane.mjs").NativeResponse>>}
  */
 export const HOST_FAILURE: Readonly<Record<string, import("./control-plane.mjs").NativeResponse>>;
+/**
+ * A guardrail judge: one normalized event in, its verdict out, synchronously or
+ * as a promise. Its answer is untrusted either way (see {@link renderHookResponse}).
+ */
+export type Judge = (event: import("./control-plane.mjs").ToolCallEvent) => import("./control-plane.mjs").Verdict | Promise<import("./control-plane.mjs").Verdict>;