agent-control-plane-core 0.12.0 → 0.13.0

package/README.md

@@ -192,9 +192,45 @@ 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.
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-control-plane-core",
-  "version": "0.12.0",
+  "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

@@ -37,6 +37,17 @@
         "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": {
@@ -81,6 +92,37 @@
         "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": {
@@ -127,6 +169,11 @@
         "mutated_input",
         "mutated_output"
       ]
+    },
+    "pre_tool_filing": {},
+    "pre_tool_response": {
+      "hook_specific_output_keys": [],
+      "unread_key_fails_open": false
     }
   },
   "gemini": {
@@ -169,6 +216,13 @@
         "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]);
 
@@ -440,6 +502,8 @@ export function createCodexAdapter(options = {}) {
     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

@@ -31,6 +31,11 @@ import { HOST_FAILURE } from "./runtime.mjs";
  * - `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>}
  */
@@ -55,6 +60,8 @@ function manifestRow(id) {
         ].sort(),
       ]),
     ),
+    pre_tool_filing: adapter.PRE_TOOL_FILING,
+    pre_tool_response: adapter.PRE_TOOL_RESPONSE,
   };
 }
 

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/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";

package/types/adapters/codex.d.mts

@@ -119,6 +119,40 @@ export const COVERAGE: import("../control-plane.mjs").CoverageMap;
  * @type {Record<string, ReadonlySet<string>|undefined>}
  */
 export const UNRENDERED_FIELDS: Record<string, ReadonlySet<string> | undefined>;
+/**
+ * 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: import("../control-plane.mjs").PreToolFiling;
+/**
+ * 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: import("../control-plane.mjs").PreToolResponse;
 /** Minimum Codex version whose hook can actually veto a tool call. */
 export const MIN_ENFORCING_VERSION: readonly number[];
 /**

package/types/adapters/gemini.d.mts

@@ -126,6 +126,23 @@ export const GEMINI_TOOL_ALIASES: Readonly<Record<string, string>>;
  * here, because an un-escalated ask lets Gemini run the tool.
  */
 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: import("../control-plane.mjs").PreToolFiling;
+/**
+ * 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: import("../control-plane.mjs").PreToolResponse;
 /** @type {import("../control-plane.mjs").Adapter} */
 export const geminiAdapter: import("../control-plane.mjs").Adapter;
 export type ToolCallEvent = import("../control-plane.mjs").ToolCallEvent;

package/types/conformance.d.mts

@@ -132,13 +132,18 @@ export function assertAliasedInputsCanonical(fixturesList: any[], assert: any):
  *      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 }: {
     adapter: import("./control-plane.mjs").Adapter;
@@ -156,4 +161,5 @@ export function runAdapterConformance({ adapter, fixtures, assert }: {
     coverageClassesChecked: Set<string>;
     unenforceableDenyChecks: number;
     askTierChecks: number;
+    preToolKeyChecks: number;
 };

package/types/control-plane.d.mts

@@ -124,6 +124,40 @@ export function classifyCallClass(tool: string | null, native?: Record<string, u
  * @returns {ReadonlySet<string>}
  */
 export function readonlySet(values: Iterable<string>): ReadonlySet<string>;
+/**
+ * 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: string | null | undefined, name: string): string;
+/**
+ * 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: unknown): boolean;
+/**
+ * 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: PreToolFiling, kind: "function" | "freeform", name: string, args: unknown): {
+    tool_name: string;
+    tool_input: unknown;
+} | null;
 /**
  * The translator for one agent's protocol. `parse` maps a native event to a
  * {@link ToolCallEvent} (never throwing on unmodelled input, stamping the
@@ -137,6 +171,8 @@ export function readonlySet(values: Iterable<string>): ReadonlySet<string>;
  * @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.
  */
 /**
@@ -354,10 +390,10 @@ export function renderEscalated(adapter: Adapter, verdict: Verdict, event: ToolC
  * {@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. */
 export const CONTROL_PLANE_SCHEMA: "control-plane/v1";
@@ -544,6 +580,14 @@ export const VERDICT_CONTENT_FIELDS: readonly string[];
  * ignores the key it was written into.
  */
 export const UNRENDERED_ON_UNKNOWN: ReadonlySet<string>;
+/** 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: "$.";
+/** What a {@link PreToolFiling} rule must be, for error messages. */
+export const FILING_RULE_GRAMMAR: "{tool_name: <non-empty string>, input: \"$\" or an object of \"$\"/\"$.<key>\" references (<key>: non-empty, no \".\")}";
+/** The kinds of model tool call a {@link PreToolFiling} distinguishes. */
+export const MODEL_CALL_KINDS: ReadonlySet<string>;
 /**
  * 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.
@@ -600,6 +644,19 @@ export const BLOCK_TRANSPORT: Readonly<Record<string, Readonly<{
     reason_stream: "stderr";
     reason_required: boolean;
 }>>>;
+/**
+ * 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]).
+ */
+export type PreToolResponse = Readonly<{
+    hook_specific_output_keys: readonly string[];
+    unread_key_fails_open: boolean | null;
+}>;
 /**
  * The translator for one agent's protocol. `parse` maps a native event to a
  * {@link ToolCallEvent} (never throwing on unmodelled input, stamping the
@@ -625,6 +682,14 @@ export type Adapter = {
      * 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.
      */
     NATIVE_ASK_TIER: boolean;
+    /**
+     * 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.
+     */
+    PRE_TOOL_FILING: PreToolFiling;
+    /**
+     * 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.
+     */
+    PRE_TOOL_RESPONSE: PreToolResponse;
     /**
      * 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.
      */
@@ -739,3 +804,32 @@ export type Verdict = {
      */
     reason?: string | undefined;
 };
+/**
+ * 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.
+ */
+export type PreToolFiling = Readonly<Record<string, null | Readonly<{
+    tool_name: string;
+    input: string | Readonly<Record<string, string>>;
+}>>>;