agent-control-plane-core 0.11.2 → 0.13.0

package/src/conformance.mjs

@@ -11,6 +11,9 @@ import {
   isCoverageStatus,
   lookup,
   VERDICT_CONTENT_FIELDS,
+  WHOLE_ARGUMENTS,
+  FILING_RULE_GRAMMAR,
+  isFilingRule,
 } from "./control-plane.mjs";
 
 /**
@@ -623,6 +626,8 @@ function assertContentChannels(adapter, event, caseName, assert, seen) {
     );
     const paths = divergences(renders);
     const where = `'${caseName}' (${adapter.AGENT}), ${field} ${shape}`;
+    for (const rendered of renders)
+      assertPreToolKeysRead(adapter, event, rendered, where, assert);
     if (declared?.has(field)) {
       assert.deepEqual(
         paths,
@@ -712,6 +717,107 @@ function assertContentChannels(adapter, event, caseName, assert, seen) {
   }
 }
 
+/**
+ * Rule ⑫, for one render: on the host's native pre-tool event, every key the
+ * render puts in `hookSpecificOutput` is one the adapter's `PRE_TOOL_RESPONSE`
+ * says the host reads. On Codex any other key voids the whole body and the call
+ * RUNS, so an unread key is a silent fail-open, not a harmless extra. Scoped to
+ * the native name `NATIVE_EVENT_FOR` gives the pre-tool kind (the event kind
+ * when it gives none): Codex's `PermissionRequest` also parses as pre-tool but
+ * answers in a different schema this declaration does not describe.
+ * @param {import("./control-plane.mjs").Adapter} adapter
+ * @param {import("./control-plane.mjs").ToolCallEvent} event
+ * @param {import("./control-plane.mjs").NativeResponse} rendered
+ * @param {string} label
+ * @param {any} assert
+ * @returns {boolean} whether the render was on the pre-tool event and checked
+ */
+function assertPreToolKeysRead(adapter, event, rendered, label, assert) {
+  const preToolName = lookup(
+    adapter.NATIVE_EVENT_FOR ?? {},
+    EventKind.PRE_TOOL,
+  );
+  const onPreTool =
+    preToolName === undefined
+      ? event.event === EventKind.PRE_TOOL
+      : event.meta.native_event === preToolName;
+  if (!onPreTool) return false;
+  // `?.`: a broken render under rule ⑩'s probes may not be an object at all,
+  // and that rule, not this one, is what names it.
+  const body = /** @type {{ hookSpecificOutput?: unknown } | undefined} */ (
+    rendered?.stdout
+  );
+  const specific =
+    body?.hookSpecificOutput === undefined ? {} : body.hookSpecificOutput;
+  assert.ok(
+    typeof specific === "object" &&
+      specific !== null &&
+      !Array.isArray(specific),
+    `${adapter.AGENT}: a pre-tool render's hookSpecificOutput is ${JSON.stringify(specific)}, not an object: ${label}`,
+  );
+  const read = new Set(adapter.PRE_TOOL_RESPONSE.hook_specific_output_keys);
+  const unread = Object.keys(/** @type {object} */ (specific)).filter(
+    (key) => !read.has(key),
+  );
+  assert.deepEqual(
+    unread,
+    [],
+    `${adapter.AGENT}: a pre-tool render puts ${JSON.stringify(unread)} in hookSpecificOutput, which PRE_TOOL_RESPONSE says this host does not read${adapter.PRE_TOOL_RESPONSE.unread_key_fails_open ? " — the host then voids the body and runs the call" : ""}: ${label}`,
+  );
+  return true;
+}
+
+/**
+ * Assert an adapter declares a well-formed `PRE_TOOL_FILING` and
+ * `PRE_TOOL_RESPONSE`: both frozen, every filing rule `null` or a frozen
+ * `{tool_name, input}` in the mini-language {@link fileModelCall} reads, and the
+ * response's key list sorted and duplicate-free beside a boolean-or-null
+ * `unread_key_fails_open`. `agents.json` publishes both verbatim, so a shape a
+ * Python consumer cannot apply is refused here, not discovered there.
+ * @param {import("./control-plane.mjs").Adapter} adapter
+ * @param {any} assert
+ */
+function assertPreToolDeclarationsWellFormed(adapter, assert) {
+  const agent = adapter.AGENT;
+  const filing = adapter.PRE_TOOL_FILING;
+  assert.ok(
+    typeof filing === "object" && filing !== null && Object.isFrozen(filing),
+    `${agent}: adapter declares no frozen PRE_TOOL_FILING — every adapter needs one: Object.freeze({}) when its host files every model call as asked`,
+  );
+  for (const [name, rule] of Object.entries(filing)) {
+    if (rule === null) continue;
+    const where = `${agent}: PRE_TOOL_FILING[${JSON.stringify(name)}]`;
+    assert.ok(Object.isFrozen(rule), `${where} is not frozen`);
+    assert.ok(
+      isFilingRule(rule),
+      `${where} is ${JSON.stringify(rule)}, not ${FILING_RULE_GRAMMAR}`,
+    );
+    if (rule.input !== WHOLE_ARGUMENTS)
+      assert.ok(Object.isFrozen(rule.input), `${where}.input is not frozen`);
+  }
+  const response = adapter.PRE_TOOL_RESPONSE;
+  assert.ok(
+    typeof response === "object" &&
+      response !== null &&
+      Object.isFrozen(response),
+    `${agent}: adapter declares no frozen PRE_TOOL_RESPONSE — every adapter needs one naming the hookSpecificOutput keys its host reads on the pre-tool event (an empty list when it reads no body)`,
+  );
+  const keys = response.hook_specific_output_keys;
+  assert.ok(
+    Array.isArray(keys) && Object.isFrozen(keys),
+    `${agent}: PRE_TOOL_RESPONSE.hook_specific_output_keys is not a frozen array`,
+  );
+  assert.deepEqual(
+    [...keys],
+    [...new Set(keys)].sort(),
+    `${agent}: PRE_TOOL_RESPONSE.hook_specific_output_keys must be sorted and duplicate-free`,
+  );
+  assert.ok(
+    [true, false, null].includes(response.unread_key_fails_open),
+    `${agent}: PRE_TOOL_RESPONSE.unread_key_fails_open must be true, false or null`,
+  );
+}
+
 /**
  * Assert an adapter's {@link import("./control-plane.mjs").Adapter.COVERAGE}
  * hook-coverage matrix is well-formed: it classifies EXACTLY the canonical
@@ -962,13 +1068,18 @@ function assertBlockTransport(agent, rendered, label, assert) {
  *      decide where an `ask` must be escalated to a `deny`, so a wrong one
  *      either lets a call through or denies every asked call on the hosts that
  *      do ask. OBSERVE_ONLY renders are exempt, as in rule ⑧.
+ *  12. pre-tool key honesty: the adapter declares a well-formed
+ *      `PRE_TOOL_FILING` and `PRE_TOOL_RESPONSE`, and every render on the host's
+ *      native pre-tool event — fixture, rule ⑧ and rule ⑩ probes alike — puts
+ *      in `hookSpecificOutput` only keys `PRE_TOOL_RESPONSE` says the host
+ *      reads. At least one such render must be checked.
  *
  * `assert` is injected (node:assert/strict) so the harness stays test-framework
  * neutral; it throws on the first mismatch. Returns a summary the caller can
  * assert further on.
  *
  * @param {{ adapter: import("./control-plane.mjs").Adapter, fixtures: any, assert: any }} args
- * @returns {{ cases: number, renders: number, decisionsSeen: Set<string>, mutationSeen: boolean, contentFieldsSeen: Set<string>, enforcedDenySeen: boolean, vetoableDenySeen: boolean, unknownKindSeen: boolean, coverageClassesChecked: Set<string>, unenforceableDenyChecks: number, askTierChecks: number }}
+ * @returns {{ cases: number, renders: number, decisionsSeen: Set<string>, mutationSeen: boolean, contentFieldsSeen: Set<string>, enforcedDenySeen: boolean, vetoableDenySeen: boolean, unknownKindSeen: boolean, coverageClassesChecked: Set<string>, unenforceableDenyChecks: number, askTierChecks: number, preToolKeyChecks: number }}
  */
 export function runAdapterConformance({ adapter, fixtures, assert }) {
   assert.equal(
@@ -987,6 +1098,7 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
     "boolean",
     `${adapter.AGENT}: adapter declares no NATIVE_ASK_TIER — every adapter needs a boolean saying whether this host honours a distinct "ask the human" tier (false when render collapses ask onto another signal)`,
   );
+  assertPreToolDeclarationsWellFormed(adapter, assert);
 
   /** @type {Set<string>} */
   const decisionsSeen = new Set();
@@ -1003,6 +1115,7 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
   let preToolCases = 0;
   let unenforceableDenyChecks = 0;
   let askTierChecks = 0;
+  let preToolKeyChecks = 0;
   let renders = 0;
 
   for (const testCase of fixtures.cases) {
@@ -1057,6 +1170,16 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
         spec.native,
         `render mismatch: ${testCase.name} / ${scenario}`,
       );
+      if (
+        assertPreToolKeysRead(
+          adapter,
+          parsed,
+          rendered,
+          `${testCase.name} / ${scenario}`,
+          assert,
+        )
+      )
+        preToolKeyChecks += 1;
       if (rendered.enforced) {
         assert.ok(
           rendered.exit_code !== 0,
@@ -1148,6 +1271,13 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
     // An OBSERVE_ONLY render is exempt from the ≠-allow half: that transport has
     // no pre-emption channel at all, so its deny and allow are identical by
     // construction. Demanding a distinct signal there would demand a fiction.
+    assertPreToolKeysRead(
+      adapter,
+      unenforceable,
+      deniedRender,
+      `rule ⑧ probe: ${testCase.name}`,
+      assert,
+    );
     if (deniedRender.transport !== IntegrationMode.OBSERVE_ONLY)
       assert.notDeepEqual(
         deniedRender,
@@ -1225,6 +1355,13 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
     `rule ⑪ (ask-tier declaration) ran on ${askTierChecks} of ${preToolCases} pre-tool cases`,
   );
 
+  // A suite with pre-tool cases must reach the native pre-tool event at least
+  // once, or a NATIVE_EVENT_FOR naming the wrong event would skip every render.
+  assert.ok(
+    preToolCases === 0 || preToolKeyChecks > 0,
+    `rule ⑫ (pre-tool key honesty) checked no fixture render on ${adapter.AGENT}'s native pre-tool event — the suite is vacuous`,
+  );
+
   return {
     cases: fixtures.cases.length,
     renders,
@@ -1237,5 +1374,6 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
     coverageClassesChecked,
     unenforceableDenyChecks,
     askTierChecks,
+    preToolKeyChecks,
   };
 }

package/src/control-plane.mjs

@@ -40,10 +40,10 @@
  * {@link Adapter} interface an integrator implements. A new REQUIRED adapter
  * member breaks every third-party adapter while every event on the wire stays
  * byte-identical, so it is a package-semver break and leaves
- * {@link CONTROL_PLANE_SCHEMA} alone. `UNRENDERED_FIELDS` is one and
- * `NATIVE_ASK_TIER` is the second: adding either is a one-line change per
- * adapter, and the conformance harness names the member and the migration
- * rather than throwing from inside itself.
+ * {@link CONTROL_PLANE_SCHEMA} alone. `UNRENDERED_FIELDS`, `NATIVE_ASK_TIER`,
+ * `PRE_TOOL_FILING` and `PRE_TOOL_RESPONSE` are such members: adding one is a
+ * one-line change per adapter, and the conformance harness names the member
+ * and the migration rather than throwing from inside itself.
  */
 
 /** Wire identifier for this schema version; bump on a breaking shape change. */
@@ -493,6 +493,180 @@ export function readonlySet(values) {
  */
 export const UNRENDERED_ON_UNKNOWN = readonlySet(VERDICT_CONTENT_FIELDS);
 
+/** The {@link PreToolFiling} input reference to a call's whole arguments value. */
+export const WHOLE_ARGUMENTS = "$";
+
+/** The prefix of a {@link PreToolFiling} input reference to one top-level argument. */
+export const ARGUMENT_KEY_PREFIX = "$.";
+
+/**
+ * How a host's pre-tool hook files a model's tool call, keyed by MODEL tool
+ * name, the {@link flatToolName} of the call's `namespace` and `name`. Each
+ * value is one of:
+ * - `null`: no pre-tool hook fires for this call.
+ * - `{ tool_name, input }`: the hook fires with `tool_name`, and `tool_input`
+ *   built from `input` — either `"$"` (the call's whole arguments value), or
+ *   an object whose every value is `"$"` or `"$.<key>"`. `<key>` is one
+ *   literal, non-empty top-level key with no `.` in it. The hook files NOTHING
+ *   when a `"$.<key>"` does not resolve: the arguments are not an object, lack
+ *   the key, or hold `null` there.
+ * A FUNCTION call the map does not list is filed as the model asked: same
+ * name, whole arguments. A FREEFORM (custom) call the map does not list files
+ * nothing. Of the shipped hosts only Codex makes freeform calls ([X7] in
+ * `docs/hook-coverage-matrix.md`).
+ * The map describes a call the host DISPATCHES. Codex files nothing for a call
+ * it rejects first: a name it has no tool for, a call kind the tool does not
+ * take (each listed rule assumes the tool's own kind), or arguments the
+ * handler refuses before its hook (`apply_patch` whose patch does not parse).
+ * 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.
+ * Plain JSON by design: `agents.json` publishes it so a consumer with no JS
+ * runtime applies it the way {@link fileModelCall} does.
+ * @typedef {Readonly<Record<string, null | Readonly<{ tool_name: string, input: string | Readonly<Record<string, string>> }>>>} PreToolFiling
+ */
+
+/** Codex's default namespace, which it stamps on every un-namespaced call. */
+const DEFAULT_FUNCTION_NAMESPACE = "functions";
+
+/**
+ * The model tool name a {@link PreToolFiling} is keyed by: `name`, prefixed
+ * (no separator) with `namespace` unless that is absent, empty, or Codex's
+ * default `functions` namespace (`flat_tool_name`, `is_default_namespace`;
+ * [X7] in `docs/hook-coverage-matrix.md`).
+ * @param {string | null | undefined} namespace
+ * @param {string} name
+ * @returns {string}
+ */
+export function flatToolName(namespace, name) {
+  if (!namespace || namespace === DEFAULT_FUNCTION_NAMESPACE) return name;
+  return namespace + name;
+}
+
+/**
+ * What a host reads from the `hookSpecificOutput` of an exit-0 answer to its
+ * pre-tool event (`PreToolUse`, `BeforeTool`). `hook_specific_output_keys` is
+ * every key it reads there, sorted (empty when it reads no body).
+ * `unread_key_fails_open`: `true` ⇒ any other key there voids the whole body
+ * and the call RUNS; `false` ⇒ other keys are ignored; `null` ⇒ not
+ * established from the host's source. Top-level keys are outside this record;
+ * Codex parses those `deny_unknown_fields` too ([X8]).
+ * @typedef {Readonly<{ hook_specific_output_keys: readonly string[], unread_key_fails_open: boolean | null }>} PreToolResponse
+ */
+
+/**
+ * Whether `ref` is a {@link PreToolFiling} input reference: `"$"`, or `"$."`
+ * followed by one non-empty key with no `.`.
+ * @param {unknown} ref
+ * @returns {boolean}
+ */
+function isFilingRef(ref) {
+  if (ref === WHOLE_ARGUMENTS) return true;
+  if (typeof ref !== "string" || !ref.startsWith(ARGUMENT_KEY_PREFIX))
+    return false;
+  const key = ref.slice(ARGUMENT_KEY_PREFIX.length);
+  return key !== "" && !key.includes(".");
+}
+
+/**
+ * Whether `input` is a {@link PreToolFiling} rule's input: `"$"`, or a plain
+ * object (not an array) whose every value is `"$"` or `"$.<key>"`.
+ * @param {unknown} input
+ * @returns {boolean}
+ */
+function isFilingInput(input) {
+  if (input === WHOLE_ARGUMENTS) return true;
+  return (
+    typeof input === "object" &&
+    input !== null &&
+    !Array.isArray(input) &&
+    Object.values(input).every(isFilingRef)
+  );
+}
+
+/** What a {@link PreToolFiling} rule must be, for error messages. */
+export const FILING_RULE_GRAMMAR = `{tool_name: <non-empty string>, input: "${WHOLE_ARGUMENTS}" or an object of "${WHOLE_ARGUMENTS}"/"${ARGUMENT_KEY_PREFIX}<key>" references (<key>: non-empty, no ".")}`;
+
+/**
+ * Whether `rule` is a non-null {@link PreToolFiling} rule: a plain object with
+ * exactly a non-empty string `tool_name` and a well-formed `input`. The one
+ * grammar both {@link fileModelCall} and the conformance harness hold a rule to.
+ * @param {unknown} rule
+ * @returns {boolean}
+ */
+export function isFilingRule(rule) {
+  if (typeof rule !== "object" || rule === null || Array.isArray(rule))
+    return false;
+  const keys = Object.keys(rule).sort();
+  const { tool_name, input } = /** @type {Record<string, unknown>} */ (rule);
+  return (
+    keys.length === 2 &&
+    keys[0] === "input" &&
+    keys[1] === "tool_name" &&
+    typeof tool_name === "string" &&
+    tool_name !== "" &&
+    isFilingInput(input)
+  );
+}
+
+/** The kinds of model tool call a {@link PreToolFiling} distinguishes. */
+export const MODEL_CALL_KINDS = readonlySet(["function", "freeform"]);
+
+/**
+ * Resolve one valid {@link PreToolFiling} input reference against `args`;
+ * `undefined` when it does not resolve (see {@link PreToolFiling}).
+ * @param {string} ref
+ * @param {unknown} args
+ * @returns {unknown}
+ */
+function resolveArgument(ref, args) {
+  if (ref === WHOLE_ARGUMENTS) return args;
+  if (typeof args !== "object" || args === null || Array.isArray(args))
+    return undefined;
+  const value = lookup(
+    /** @type {Record<string, unknown>} */ (args),
+    ref.slice(ARGUMENT_KEY_PREFIX.length),
+  );
+  return value === null ? undefined : value;
+}
+
+/**
+ * The call a host's pre-tool hook files for a model call of `kind` to `name`
+ * with arguments value `args`, per that host's {@link PreToolFiling}; `null`
+ * when the hook files none. The reference reading of the mini-language
+ * `agents.json` publishes as `pre_tool_filing`. Throws on a rule outside that
+ * grammar or a kind outside {@link MODEL_CALL_KINDS}.
+ * @param {PreToolFiling} filing
+ * @param {"function" | "freeform"} kind whether the model made a function call or a freeform (custom) call
+ * @param {string} name the model tool name, a {@link flatToolName}
+ * @param {unknown} args the call's arguments value
+ * @returns {{ tool_name: string, tool_input: unknown } | null}
+ */
+export function fileModelCall(filing, kind, name, args) {
+  if (!MODEL_CALL_KINDS.has(kind))
+    throw new Error(
+      `control-plane: model call kind ${JSON.stringify(kind)} is neither "function" nor "freeform"`,
+    );
+  if (!Object.hasOwn(filing, name))
+    return kind === "function" ? { tool_name: name, tool_input: args } : null;
+  const rule = filing[name];
+  if (rule === null) return null;
+  if (!isFilingRule(rule))
+    throw new Error(
+      `control-plane: filing rule for ${JSON.stringify(name)} is ${JSON.stringify(rule)}, not ${FILING_RULE_GRAMMAR}`,
+    );
+  if (rule.input === WHOLE_ARGUMENTS)
+    return { tool_name: rule.tool_name, tool_input: args };
+  const entries = Object.entries(rule.input).map(([key, ref]) => [
+    key,
+    resolveArgument(ref, args),
+  ]);
+  if (entries.some(([, value]) => value === undefined)) return null;
+  // fromEntries defines own properties, so an input key `__proto__` stays a
+  // key, as it is in a Python consumer's dict, instead of hitting the setter.
+  return { tool_name: rule.tool_name, tool_input: Object.fromEntries(entries) };
+}
+
 /**
  * PROBLEM CLASS — an event marked vetoable on a path where the host can never
  * veto it, so a deny reads downstream as a block that never happened.
@@ -530,6 +704,8 @@ export const VETO_IMPOSSIBLE = Object.freeze([
  * @property {(verdict: Verdict, event: ToolCallEvent, options?: { soleGate?: boolean }) => NativeResponse} render
  * @property {Record<string, string|undefined>} [NATIVE_EVENT_FOR] the native event name this host uses for each {@link EventKind}, for a conformance probe of a kind no fixture produced. Optional: a kind absent here (`unknown` always, plus any kind this transport does not carry) is probed with a marker name, which takes the adapter's unrecognized-event branch. Never read at runtime — `parse` stamps the real name on `meta.native_event`.
  * @property {boolean} NATIVE_ASK_TIER whether this host's transport carries a DISTINCT "ask the human" tier that the host honours. `true` ⇒ a rendered `ask` suspends the call in front of a person (Claude Code's `permissionDecision: "ask"`, Amp's exit 1). `false` ⇒ the host has no such tier, so `render` collapses `ask` onto another signal (Gemini CLI writes its advisory `decision: "deny"`) and an un-escalated ask lets the tool run. A consumer that must not let an ask through reads this to decide where to escalate `ask` to `deny`, instead of keeping its own hand-typed list of agent ids. It is about the HOST, not the verdict: `ask` never renders as `enforced` on any adapter, and the tier it names is the PRE-TOOL gate — once a tool has run there is nothing left to suspend, so every host renders a post-tool `ask` as its block. The conformance harness probes the real `render` against it — a `true` whose ask renders as the host's abstaining allow fails, and so does a `false` whose ask differs from its own advisory deny.
+ * @property {PreToolFiling} PRE_TOOL_FILING how this host's pre-tool hook files a model tool call, for a consumer matching the model's calls against the hook's. `{}` when no rename is modelled.
+ * @property {PreToolResponse} PRE_TOOL_RESPONSE the `hookSpecificOutput` keys this host reads on its pre-tool event, and whether an unread key there runs the call. The conformance harness holds every pre-tool render to the key list.
  * @property {Record<string, ReadonlySet<string>|undefined>} UNRENDERED_FIELDS per-event-kind set of {@link VERDICT_CONTENT_FIELDS} this host has no native channel for, so `render` drops them. EVERY {@link EventKind} carries a row, including one this adapter's `parse` cannot emit — an omission would otherwise read as "every content field reaches a channel here", the reverse of the truth on a transport that carries none. The value type still admits `undefined` so a consumer handles a lookup miss rather than indexing straight into `.has(...)`; the conformance harness refuses a missing row. SCOPE — a row describes the ALLOW path only. An enforceable deny may drop more: Gemini's exit-2 System Block returns no stdout at all, so a deny there carries no `additional_context` whatever the row says. Do not read this map to infer what a deny delivers. The conformance harness fails an adapter whose renders disagree with its declaration either way, so a stale entry cannot survive.
  */
 

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/amp.d.mts

@@ -107,6 +107,18 @@ export const UNRENDERED_FIELDS: Record<string, ReadonlySet<string> | undefined>;
  * only honest because the tier is real.
  */
 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: import("../control-plane.mjs").PreToolFiling;
+/**
+ * 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: import("../control-plane.mjs").PreToolResponse;
 /** @type {import("../control-plane.mjs").Adapter} */
 export const ampAdapter: import("../control-plane.mjs").Adapter;
 export type ToolCallEvent = import("../control-plane.mjs").ToolCallEvent;

package/types/adapters/claude.d.mts

@@ -75,6 +75,21 @@ export const UNRENDERED_FIELDS: Record<string, ReadonlySet<string> | undefined>;
  * host did, pending an answer.
  */
 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: import("../control-plane.mjs").PreToolFiling;
+/**
+ * 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: import("../control-plane.mjs").PreToolResponse;
 /** Claude Code native hook event names (the `hook_event_name` field). */
 export const HookEvent: Readonly<{
     PRE_TOOL_USE: "PreToolUse";