agent-control-plane-core 0.12.0 → 0.14.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";
 
 /**
@@ -404,14 +407,20 @@ function assertRowReads(agent, kind, row, assert) {
  * @param {Set<string>} seen fields observed to REACH a wire
  */
 function assertEveryKindRenders(adapter, byKind, assert, seen) {
-  for (const kind of Object.values(EventKind))
+  for (const kind of Object.values(EventKind)) {
+    // A parsed event under another native name is not the event the row
+    // describes, so the probe synthesizes the native one instead.
+    const parsed = lookup(byKind, kind);
     assertContentChannels(
       adapter,
-      lookup(byKind, kind) ?? coherentEvent(adapter, byKind, kind),
+      parsed !== undefined && onKindsNativeEvent(adapter, parsed)
+        ? parsed
+        : coherentEvent(adapter, byKind, kind),
       `every-kind probe '${kind}'`,
       assert,
       seen,
     );
+  }
 }
 
 /**
@@ -575,6 +584,10 @@ function assertAskTier(adapter, event, vetoable, caseName, assert) {
  * (kind, decision) would state that, and is not worth its weight while the only
  * field a blocked call can still want is `additional_context`.
  *
+ * SCOPE — a row describes its kind's `NATIVE_EVENT_FOR` event, so an event of
+ * that kind under another native name (Codex's `PermissionRequest`, which
+ * parses as `pre_tool` and carries no content) is not held to it.
+ *
  * Reaching the wire is checked as SERIALIZATION, so the rule proves a field is
  * carried, not that the key it is carried in is one the host reads. Nothing
  * machine-readable describes a host's schema, so that half stays with the
@@ -586,6 +599,7 @@ function assertAskTier(adapter, event, vetoable, caseName, assert) {
  * @param {Set<string>} seen fields observed to REACH a wire, for the non-vacuity check
  */
 function assertContentChannels(adapter, event, caseName, assert, seen) {
+  if (!onKindsNativeEvent(adapter, event)) return;
   const declared = lookup(adapter.UNRENDERED_FIELDS, event.event);
 
   // Every value of a field is rendered and the renders compared to EACH OTHER.
@@ -623,6 +637,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 +728,150 @@ function assertContentChannels(adapter, event, caseName, assert, seen) {
   }
 }
 
+/**
+ * Whether `event` arrived as the native event `NATIVE_EVENT_FOR` names for its
+ * kind (always, when the adapter names none for that kind) — the event a
+ * kind-keyed declaration describes.
+ * @param {import("./control-plane.mjs").Adapter} adapter
+ * @param {import("./control-plane.mjs").ToolCallEvent} event
+ * @returns {boolean}
+ */
+function onKindsNativeEvent(adapter, event) {
+  const native = lookup(adapter.NATIVE_EVENT_FOR ?? {}, event.event);
+  return native === undefined || event.meta.native_event === native;
+}
+
+/**
+ * The two levels of a pre-tool body `PRE_TOOL_RESPONSE` declares, each as the
+ * key-list member, its fail-open member, and where in the body it applies.
+ */
+const PRE_TOOL_RESPONSE_LEVELS = Object.freeze([
+  Object.freeze({
+    keys: "top_level_keys",
+    failsOpen: "unread_top_level_key_fails_open",
+    where: "the body",
+    /** @param {any} body */
+    pick: (body) => body,
+  }),
+  Object.freeze({
+    keys: "hook_specific_output_keys",
+    failsOpen: "unread_key_fails_open",
+    where: "hookSpecificOutput",
+    /** @param {any} body */
+    pick: (body) => body?.hookSpecificOutput,
+  }),
+]);
+
+/**
+ * Rule ⑫, for one render: on the host's native pre-tool event, every key the
+ * render puts at the body's top level or in `hookSpecificOutput` is one the
+ * adapter's `PRE_TOOL_RESPONSE` says the host reads there. On Codex any other
+ * key, at either level, 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 (any pre-tool event 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) {
+  if (event.event !== EventKind.PRE_TOOL || !onKindsNativeEvent(adapter, event))
+    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. No body reads as an empty one.
+  const body = rendered?.stdout;
+  for (const level of PRE_TOOL_RESPONSE_LEVELS) {
+    const found = level.pick(body);
+    const part = found === undefined ? {} : found;
+    assert.ok(
+      isPlainObject(part),
+      `${adapter.AGENT}: in a pre-tool render, ${level.where} is ${JSON.stringify(part)}, not an object: ${label}`,
+    );
+    const read = new Set(
+      /** @type {readonly string[]} */ (
+        lookup(adapter.PRE_TOOL_RESPONSE, level.keys)
+      ),
+    );
+    const unread = Object.keys(/** @type {object} */ (part)).filter(
+      (key) => !read.has(key),
+    );
+    assert.deepEqual(
+      unread,
+      [],
+      `${adapter.AGENT}: a pre-tool render puts ${JSON.stringify(unread)} in ${level.where}, which PRE_TOOL_RESPONSE.${level.keys} says this host does not read${lookup(adapter.PRE_TOOL_RESPONSE, level.failsOpen) ? " — the host then voids the body and runs the call" : ""}: ${label}`,
+    );
+  }
+  return true;
+}
+
+/**
+ * Whether `value` is an object that is neither `null` nor an array.
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * 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
+ * each of the response's key lists sorted and duplicate-free beside its
+ * boolean-or-null fail-open bit. `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 top-level and hookSpecificOutput keys its host reads on the pre-tool event (empty lists when it reads no body)`,
+  );
+  for (const level of PRE_TOOL_RESPONSE_LEVELS) {
+    const keys = /** @type {any} */ (lookup(response, level.keys));
+    assert.ok(
+      Array.isArray(keys) && Object.isFrozen(keys),
+      `${agent}: PRE_TOOL_RESPONSE.${level.keys} is not a frozen array`,
+    );
+    assert.deepEqual(
+      [...keys],
+      [...new Set(keys)].sort(),
+      `${agent}: PRE_TOOL_RESPONSE.${level.keys} must be sorted and duplicate-free`,
+    );
+    assert.ok(
+      [true, false, null].includes(
+        /** @type {any} */ (lookup(response, level.failsOpen)),
+      ),
+      `${agent}: PRE_TOOL_RESPONSE.${level.failsOpen} 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 +1122,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 +1152,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 +1169,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 +1224,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,
@@ -1114,7 +1291,15 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
       renders += 1;
     }
 
-    parsedByKind[parsed.event] ??= parsed;
+    // The kind's native event stands for it in the every-kind sweep when one
+    // arrives; another native name is only a seed to synthesize one from.
+    const held = lookup(parsedByKind, parsed.event);
+    if (
+      held === undefined ||
+      (!onKindsNativeEvent(adapter, held) &&
+        onKindsNativeEvent(adapter, parsed))
+    )
+      parsedByKind[parsed.event] = parsed;
     assertContentChannels(
       adapter,
       parsed,
@@ -1148,6 +1333,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 +1417,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 +1436,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 an exit-0 answer to its pre-tool event (`PreToolUse`,
+ * `BeforeTool`), as two sorted key lists, each empty when the host reads no
+ * body: `hook_specific_output_keys` inside `hookSpecificOutput`, and
+ * `top_level_keys` at the body's top level. Each list has a fail-open bit,
+ * `unread_key_fails_open` and `unread_top_level_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.
+ * @typedef {Readonly<{ hook_specific_output_keys: readonly string[], unread_key_fails_open: boolean | null, top_level_keys: readonly string[], unread_top_level_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,7 +704,9 @@ 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 {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.
+ * @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 top-level and `hookSpecificOutput` keys this host reads on its pre-tool event, each list with whether an unread key there runs the call. The conformance harness holds every pre-tool render to both lists.
+ * @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 on the kind's `NATIVE_EVENT_FOR` event only; another native event of that kind (Codex's `PermissionRequest`) may drop more. 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.
  */
 
 /**
@@ -874,6 +1050,8 @@ export const DEFAULT_DENY_REASON = "blocked by monitor";
  *   exit. Every host here discards (or never gets) the stdout body on exit 2.
  * - `reason_required`: the host drops a block whose reason is empty and runs
  *   the tool, so every body field that carries the reason must be non-empty.
+ *   Unlike the other two fields, this holds for ANY block body the host parses,
+ *   enforced or advisory: Codex voids an empty-reason deny either way.
  *
  * {@link gatedResponse} derives each adapter's enforced render from its row,
  * and the conformance harness holds every enforced render to the same row.

package/src/fixtures/codex.json

@@ -79,7 +79,8 @@
             "enforced": false,
             "stdout": {
               "hookSpecificOutput": {
-                "hookEventName": "PreToolUse"
+                "hookEventName": "PreToolUse",
+                "additionalContext": "redacted 1 secret"
               }
             }
           }
@@ -127,7 +128,7 @@
             "mutated_input": {
               "command": "ls"
             },
-            "additional_context": "dropped by codex"
+            "additional_context": "narrowed to a plain ls"
           },
           "native": {
             "transport": "external_hook",
@@ -136,9 +137,11 @@
             "stdout": {
               "hookSpecificOutput": {
                 "hookEventName": "PreToolUse",
+                "permissionDecision": "allow",
                 "updatedInput": {
                   "command": "ls"
-                }
+                },
+                "additionalContext": "narrowed to a plain ls"
               }
             }
           }
@@ -285,6 +288,7 @@
             "stdout": {
               "hookSpecificOutput": {
                 "hookEventName": "PreToolUse",
+                "permissionDecision": "allow",
                 "updatedInput": {
                   "command": ["ls"]
                 }
@@ -370,8 +374,10 @@
             "stdout": {
               "hookSpecificOutput": {
                 "hookEventName": "PermissionRequest",
-                "permissionDecision": "deny",
-                "permissionDecisionReason": "nope"
+                "decision": {
+                  "behavior": "deny",
+                  "message": "nope"
+                }
               }
             },
             "stderr": "nope"

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 top-level and `hookSpecificOutput` keys Claude Code's hooks reference
+ * documents for `PreToolUse` (https://code.claude.com/docs/en/hooks). Whether
+ * an unread key fails open, at either level, 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";