agent-control-plane-core 0.13.0 → 0.15.0

package/README.md

@@ -193,15 +193,18 @@ monitor) reads `schema/control-plane/v1/agents.json` instead. It is generated
 from the adapters, with one row per agent: its block exit code and reason
 stream, whether a block needs a reason, whether it has an ask tier, the entry's
 default response when the hook breaks, its hook coverage, the verdict
-fields an allow cannot carry, and two pre-tool facts:
-
-- `pre_tool_response`: `hook_specific_output_keys` lists the
-  `hookSpecificOutput` keys the host reads on an exit-0 pre-tool answer.
-  `unread_key_fails_open` says what any other key does there: `true` means the
-  host discards the whole body and runs the call (Codex), `false` means the key
-  is ignored, `null` means unknown. The conformance harness fails an adapter
-  whose pre-tool render emits a key outside the list. Neither field covers the
-  body's top-level keys, which Codex also parses strictly.
+fields an allow cannot carry on each kind's main native event (Codex's
+`PermissionRequest`, which also parses as `pre_tool`, carries none), and two
+pre-tool facts:
+
+- `pre_tool_response`: the keys the host reads on an exit-0 pre-tool answer,
+  as two sorted lists: `top_level_keys` for the body's top level and
+  `hook_specific_output_keys` for `hookSpecificOutput`. Each has a bit saying
+  what any other key there does, `unread_top_level_key_fails_open` and
+  `unread_key_fails_open`: `true` means the host discards the whole body and
+  runs the call (Codex, at both levels), `false` means the key is ignored,
+  `null` means unknown. The conformance harness fails an adapter whose pre-tool
+  render emits a key outside either list.
 - `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

package/package.json

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

@@ -47,7 +47,17 @@
         "permissionDecisionReason",
         "updatedInput"
       ],
-      "unread_key_fails_open": null
+      "unread_key_fails_open": null,
+      "top_level_keys": [
+        "continue",
+        "decision",
+        "hookSpecificOutput",
+        "reason",
+        "stopReason",
+        "suppressOutput",
+        "systemMessage"
+      ],
+      "unread_top_level_key_fails_open": null
     }
   },
   "codex": {
@@ -70,7 +80,6 @@
     },
     "unrendered_fields_on_allow": {
       "pre_tool": [
-        "additional_context",
         "mutated_output"
       ],
       "post_tool": [
@@ -122,7 +131,17 @@
         "permissionDecisionReason",
         "updatedInput"
       ],
-      "unread_key_fails_open": true
+      "unread_key_fails_open": true,
+      "top_level_keys": [
+        "continue",
+        "decision",
+        "hookSpecificOutput",
+        "reason",
+        "stopReason",
+        "suppressOutput",
+        "systemMessage"
+      ],
+      "unread_top_level_key_fails_open": true
     }
   },
   "amp": {
@@ -173,7 +192,9 @@
     "pre_tool_filing": {},
     "pre_tool_response": {
       "hook_specific_output_keys": [],
-      "unread_key_fails_open": false
+      "unread_key_fails_open": false,
+      "top_level_keys": [],
+      "unread_top_level_key_fails_open": false
     }
   },
   "gemini": {
@@ -222,7 +243,17 @@
       "hook_specific_output_keys": [
         "tool_input"
       ],
-      "unread_key_fails_open": false
+      "unread_key_fails_open": false,
+      "top_level_keys": [
+        "continue",
+        "decision",
+        "hookSpecificOutput",
+        "reason",
+        "stopReason",
+        "suppressOutput",
+        "systemMessage"
+      ],
+      "unread_top_level_key_fails_open": false
     }
   }
 }

package/src/adapters/amp.mjs

@@ -184,6 +184,8 @@ export const PRE_TOOL_FILING = Object.freeze({});
 export const PRE_TOOL_RESPONSE = Object.freeze({
   hook_specific_output_keys: Object.freeze([]),
   unread_key_fails_open: false,
+  top_level_keys: Object.freeze([]),
+  unread_top_level_key_fails_open: false,
 });
 
 /**

package/src/adapters/claude.mjs

@@ -133,11 +133,11 @@ export const NATIVE_ASK_TIER = true;
 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.
+ * 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 = Object.freeze({
@@ -149,6 +149,16 @@ export const PRE_TOOL_RESPONSE = Object.freeze({
     "updatedInput",
   ]),
   unread_key_fails_open: null,
+  top_level_keys: Object.freeze([
+    "continue",
+    "decision",
+    "hookSpecificOutput",
+    "reason",
+    "stopReason",
+    "suppressOutput",
+    "systemMessage",
+  ]),
+  unread_top_level_key_fails_open: null,
 });
 
 /** Claude Code native hook event names (the `hook_event_name` field). */

package/src/adapters/codex.mjs

@@ -31,7 +31,6 @@ import {
   makeEvent,
   normalizeVerdict,
   gatedResponse,
-  blockTransportFor,
   blockReason,
   UNRENDERED_ON_UNKNOWN,
   readonlySet,
@@ -91,8 +90,9 @@ export const COVERAGE = Object.freeze({
 });
 
 /**
- * The event kinds this host can actually gate. `PreToolUse`/`PermissionRequest`
- * take a `permissionDecision: "deny"`; `PostToolUse` takes a top-level
+ * The event kinds this host can actually gate. `PreToolUse` takes
+ * `permissionDecision: "deny"`, `PermissionRequest` `decision.behavior: "deny"`;
+ * `PostToolUse` takes a top-level
  * `decision: "block"` (exit 2 "writes the feedback reason to stderr and blocks
  * further processing"), so a post-tool deny stops the turn even though the tool
  * itself already ran — the same shape the Claude adapter gates. Every other
@@ -108,11 +108,15 @@ const GATED_EVENTS = Object.freeze(
 assertGatedKinds(GATED_EVENTS, AGENT);
 
 /**
- * Which {@link VERDICT_CONTENT_FIELDS} have no native channel on each kind, so
- * `render` drops them. Codex splits its two content channels by event:
- * `updatedInput` exists only on PreToolUse (the call has not run yet), and
- * `hookSpecificOutput.additionalContext` only on PostToolUse — Codex documents
- * no context field on PreToolUse, where `updatedInput` is the whole surface.
+ * Which {@link VERDICT_CONTENT_FIELDS} have no native channel on each kind's
+ * {@link NATIVE_EVENT_FOR} event, so `render` drops them. PreToolUse takes
+ * `updatedInput` (applied only beside `permissionDecision: "allow"`) and
+ * `additionalContext`; PostToolUse takes `additionalContext` alone ([X8], read
+ * at `rust-v0.166.0` and identical at `rust-v0.135.0`). `PermissionRequest`,
+ * which also parses as `pre_tool`, takes neither: its schema is
+ * `{hookEventName, decision: {behavior, message}}`, and a body carrying
+ * `updatedInput` is ignored (Codex's own approval flow decides), so
+ * {@link render} drops both there.
  *
  * NEITHER kind can rewrite tool output: PostToolUse "can't undo side effects
  * from a tool that already ran", and Codex rejects `updatedMCPToolOutput`, so
@@ -127,7 +131,7 @@ export const UNRENDERED_FIELDS = Object.freeze({
   ...Object.fromEntries(
     Object.values(EventKind).map((kind) => [kind, UNRENDERED_ON_UNKNOWN]),
   ),
-  [EventKind.PRE_TOOL]: readonlySet(["mutated_output", "additional_context"]),
+  [EventKind.PRE_TOOL]: readonlySet(["mutated_output"]),
   [EventKind.POST_TOOL]: readonlySet(["mutated_input", "mutated_output"]),
 });
 
@@ -173,12 +177,15 @@ export const PRE_TOOL_FILING = Object.freeze({
 });
 
 /**
- * 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.
+ * Codex's `PreToolUse` output parser ([X8], `rust-v0.166.0`) deserializes the
+ * body into `deny_unknown_fields` structs at both levels: these seven top-level
+ * keys (`PreToolUseCommandOutputWire` with its flattened universal fields), and
+ * these five in `hookSpecificOutput`. 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 value or combination (`continue: false`, any
+ * `stopReason`, `suppressOutput: true`, `decision: "approve"`, `updatedInput`
+ * without `permissionDecision: "allow"`), which this declaration does not
+ * describe.
  * @type {import("../control-plane.mjs").PreToolResponse}
  */
 export const PRE_TOOL_RESPONSE = Object.freeze({
@@ -190,6 +197,16 @@ export const PRE_TOOL_RESPONSE = Object.freeze({
     "updatedInput",
   ]),
   unread_key_fails_open: true,
+  top_level_keys: Object.freeze([
+    "continue",
+    "decision",
+    "hookSpecificOutput",
+    "reason",
+    "stopReason",
+    "suppressOutput",
+    "systemMessage",
+  ]),
+  unread_top_level_key_fails_open: true,
 });
 
 /** Minimum Codex version whose hook can actually veto a tool call. */
@@ -361,15 +378,17 @@ export function parse(native, { version } = {}) {
  * on an enforceable deny. On a pre-v0.135 Codex (`this_call_vetoable` false) the
  * body still renders but exit stays 0 and `enforced` is false — advisory only.
  *
- * The two kinds use DIFFERENT native shapes, because Codex does: a pre-tool
- * decision rides `hookSpecificOutput.permissionDecision`, a post-tool one the
- * top-level `decision`/`reason` pair (`permissionDecision` is accepted but inert
- * on PostToolUse, so emitting it there would read as a block that never bites).
+ * Each native event gets its OWN shape, because Codex parses each strictly: a
+ * PreToolUse decision rides `hookSpecificOutput.permissionDecision`, a
+ * PermissionRequest one `hookSpecificOutput.decision.behavior`, and a
+ * post-tool one the top-level `decision`/`reason` pair.
  *
  * `soleGate` (default `false`) is the same dangerous, explicit opt-in as the
- * Claude adapter: when `true` AND the verdict is `allow`, the render emits the
- * real `permissionDecision: "allow"` instead of abstaining. It has no meaning
- * post-tool — there is no approval left to grant — so it is ignored there.
+ * Claude adapter, and acts only on PermissionRequest: there an `allow` renders
+ * `behavior: "allow"`, which grants the approval (except, from 0.166, when the
+ * hook is environment-sourced). PreToolUse has no allow that
+ * approves anything (Codex accepts `"allow"` only beside `updatedInput`, as a
+ * rewrite), and post-tool there is no approval left to grant.
  * @param {Verdict} verdict
  * @param {ToolCallEvent} event
  * @param {{ soleGate?: boolean }} [options]
@@ -395,52 +414,85 @@ export function render(verdict, event, { soleGate = false } = {}) {
     unblocked_exit_code: 0,
     enforced,
     reason: vd.reason,
-    stdout:
-      event.event === EventKind.POST_TOOL
-        ? postToolBody(hookEventName, vd, enforced)
-        : preToolBody(hookEventName, vd, event, enforced, soleGate),
+    stdout: nativeBody(hookEventName, vd, event, soleGate),
   });
 }
 
 /**
- * The `hookSpecificOutput` body for a pre-tool (or unmodelled) event.
+ * The stdout body for `event`, in the schema its native event answers in.
  * @param {string} hookEventName
  * @param {Verdict} vd a normalized verdict
  * @param {ToolCallEvent} event
- * @param {boolean} enforced
  * @param {boolean} soleGate
  * @returns {Record<string, unknown>}
  */
-function preToolBody(hookEventName, vd, event, enforced, soleGate) {
-  // As in the Claude adapter, `allow` omits permissionDecision by default so the
-  // guardrail never auto-approves a call it merely had no objection to; only
-  // deny/ask emit an explicit decision, unless `soleGate` opts into it.
+function nativeBody(hookEventName, vd, event, soleGate) {
+  if (event.event === EventKind.POST_TOOL)
+    return postToolBody(hookEventName, vd);
+  if (hookEventName === HookEvent.PERMISSION_REQUEST)
+    return permissionRequestBody(hookEventName, vd, soleGate);
+  return preToolBody(hookEventName, vd, event);
+}
+
+/**
+ * The body for a PreToolUse (or unmodelled) event. Codex's PreToolUse parser
+ * ([X8]) voids the body, and the call runs, on `"allow"` without `updatedInput`
+ * and on `updatedInput` without `"allow"` — so an allow emits a decision only
+ * to carry a mutation, and a deny never carries one.
+ * @param {string} hookEventName
+ * @param {Verdict} vd a normalized verdict
+ * @param {ToolCallEvent} event
+ * @returns {Record<string, unknown>}
+ */
+function preToolBody(hookEventName, vd, event) {
   /** @type {Record<string, unknown>} */
   const body = { hookEventName };
-  // An UNKNOWN event reaches this body too. It has no established decision
-  // channel, so it carries none: a decision there would act on the host while
-  // the render reports no block.
-  if (
-    event.event === EventKind.PRE_TOOL &&
-    (vd.decision !== Decision.ALLOW || soleGate)
-  ) {
+  // An UNKNOWN event reaches this body too. It has no established channel, so
+  // it carries nothing: a decision or `updatedInput` there would act on the
+  // host, or read to the caller as applied, while the host ignores it.
+  if (event.event !== EventKind.PRE_TOOL) return { hookSpecificOutput: body };
+  if (vd.decision !== Decision.ALLOW) {
+    // Codex voids a deny body whose reason is missing or empty: no block, no
+    // context, and the call runs (`parse_pre_tool_use`, [X8]). That holds on an
+    // advisory render too, so every deny carries a reason.
     body.permissionDecision = vd.decision;
-    if (vd.reason !== undefined) body.permissionDecisionReason = vd.reason;
-  }
-  // Codex FAILS OPEN on an enforced deny whose permissionDecisionReason is missing
-  // or empty: its PreToolUse output parser drops the block (block_reason = None)
-  // and runs the tool (BLOCK_TRANSPORT.codex.reason_required).
-  if (enforced && blockTransportFor(AGENT).reason_required)
     body.permissionDecisionReason = blockReason(vd.reason);
-  // PRE_TOOL only. An UNKNOWN event reaches this body too, and an event the
-  // adapter cannot name has no channel it can claim: emitting `updatedInput`
-  // there names a key the host ignores while reading to the caller as a
-  // mutation applied.
-  if (event.event === EventKind.PRE_TOOL && vd.mutated_input !== undefined)
+  } else if (vd.mutated_input !== undefined) {
+    body.permissionDecision = Decision.ALLOW;
     body.updatedInput = vd.mutated_input;
+  }
+  if (vd.additional_context !== undefined)
+    body.additionalContext = vd.additional_context;
   return { hookSpecificOutput: body };
 }
 
+/**
+ * The body for a PermissionRequest event: Codex's
+ * `PermissionRequestHookSpecificOutputWire` ([X8]), `{hookEventName, decision:
+ * {behavior, message}}`. `behavior: "allow"` GRANTS the approval, so an allow
+ * abstains unless `soleGate` opts in. Content fields have no channel here:
+ * `updatedInput` voids the body and there is no context key.
+ * @param {string} hookEventName
+ * @param {Verdict} vd a normalized verdict
+ * @param {boolean} soleGate
+ * @returns {Record<string, unknown>}
+ */
+function permissionRequestBody(hookEventName, vd, soleGate) {
+  /** @type {Record<string, unknown>} */
+  const hookSpecificOutput = { hookEventName };
+  // Codex substitutes its own text for an empty message
+  // (`permission_request_decision`, [X8]); ours says who denied it.
+  if (vd.decision !== Decision.ALLOW) {
+    hookSpecificOutput.decision = {
+      behavior: Decision.DENY,
+      message: blockReason(vd.reason),
+    };
+  } else if (soleGate) {
+    hookSpecificOutput.decision = { behavior: Decision.ALLOW };
+  }
+  return { hookSpecificOutput };
+}
+
 /**
  * The body for a PostToolUse event: Codex's documented post-tool schema, a
  * top-level `decision`/`reason` beside a `hookSpecificOutput` carrying
@@ -449,27 +501,21 @@ function preToolBody(hookEventName, vd, event, enforced, soleGate) {
  * objection the host understands there, `block`.
  * @param {string} hookEventName
  * @param {Verdict} vd a normalized verdict
- * @param {boolean} enforced
  * @returns {Record<string, unknown>}
  */
-function postToolBody(hookEventName, vd, enforced) {
+function postToolBody(hookEventName, vd) {
   /** @type {Record<string, unknown>} */
   const hookSpecificOutput = { hookEventName };
   if (vd.additional_context !== undefined)
     hookSpecificOutput.additionalContext = vd.additional_context;
   /** @type {Record<string, unknown>} */
   const body = { hookSpecificOutput };
+  // `parse_post_tool_use` ([X8]) voids `decision: "block"` with an empty
+  // reason, and a sync handler's context with it, advisory render or not.
   if (vd.decision !== Decision.ALLOW) {
     body.decision = "block";
-    if (vd.reason !== undefined) body.reason = vd.reason;
-  }
-  // The same guarantee the pre-tool body makes, for the same reason: the
-  // documented post-tool schema pairs `decision` with a `reason`, and a block
-  // whose reason Codex may drop is a block that may not bite. Unverified for
-  // PostToolUse specifically — a non-empty reason is the safe side of that, and
-  // the model needs the text either way.
-  if (enforced && blockTransportFor(AGENT).reason_required)
     body.reason = blockReason(vd.reason);
+  }
   return body;
 }
 

package/src/adapters/gemini.mjs

@@ -371,12 +371,24 @@ export const PRE_TOOL_FILING = Object.freeze({});
  * 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`).
+ * `62bab5b2`). The top level is the `HookOutput` interface's seven keys, read
+ * from an unchecked `JSON.parse` cast (`hooks/hookRunner.ts`), so an unknown
+ * top-level key is ignored too.
  * @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,
+  top_level_keys: Object.freeze([
+    "continue",
+    "decision",
+    "hookSpecificOutput",
+    "reason",
+    "stopReason",
+    "suppressOutput",
+    "systemMessage",
+  ]),
+  unread_top_level_key_fails_open: false,
 });
 
 /**

package/src/agent-manifest.mjs

@@ -30,12 +30,13 @@ import { HOST_FAILURE } from "./runtime.mjs";
  *   `ACP_FAIL_CLOSED=1` replaces it with `block`.
  * - `coverage`: `COVERAGE`, per call class.
  * - `unrendered_fields_on_allow`: `UNRENDERED_FIELDS`, each set as a sorted
- *   list. It describes the allow path only: a deny can drop more.
+ *   list. It describes the allow path on each kind's `NATIVE_EVENT_FOR` event
+ *   only: a deny, or another native event of that kind, 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).
+ * - `pre_tool_response`: `PRE_TOOL_RESPONSE`, the top-level and
+ *   `hookSpecificOutput` keys the host reads on an exit-0 pre-tool answer, each
+ *   list with its fail-open bit, as the `PreToolResponse` typedef specifies.
  * @param {string} id
  * @returns {Record<string, unknown>}
  */
@@ -61,7 +62,13 @@ function manifestRow(id) {
       ]),
     ),
     pre_tool_filing: adapter.PRE_TOOL_FILING,
-    pre_tool_response: adapter.PRE_TOOL_RESPONSE,
+    pre_tool_response: {
+      ...adapter.PRE_TOOL_RESPONSE,
+      hook_specific_output_keys: [
+        ...adapter.PRE_TOOL_RESPONSE.hook_specific_output_keys,
+      ].sort(),
+      top_level_keys: [...adapter.PRE_TOOL_RESPONSE.top_level_keys].sort(),
+    },
   };
 }
 

package/src/conformance.mjs

@@ -11,9 +11,9 @@ import {
   isCoverageStatus,
   lookup,
   VERDICT_CONTENT_FIELDS,
-  WHOLE_ARGUMENTS,
   FILING_RULE_GRAMMAR,
   isFilingRule,
+  isPlainObject,
 } from "./control-plane.mjs";
 
 /**
@@ -407,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,
     );
+  }
 }
 
 /**
@@ -578,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
@@ -589,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.
@@ -717,14 +728,49 @@ 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 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.
+ * 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
@@ -733,47 +779,41 @@ function assertContentChannels(adapter, event, caseName, assert, seen) {
  * @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;
+  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.
-  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}`,
-  );
+  // 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;
 }
 
 /**
  * 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.
+ * `PRE_TOOL_RESPONSE`: every filing rule `null` or in the mini-language
+ * {@link fileModelCall} reads, and each response key list an array of strings
+ * beside a boolean-or-null fail-open bit. `agents.json` publishes both, so a
+ * shape a Python consumer cannot apply is refused here, not discovered there.
  * @param {import("./control-plane.mjs").Adapter} adapter
  * @param {any} assert
  */
@@ -781,41 +821,32 @@ 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`,
+    isPlainObject(filing),
+    `${agent}: adapter declares no PRE_TOOL_FILING — every adapter needs one: {} 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`);
+  for (const [name, rule] of Object.entries(filing))
     assert.ok(
-      isFilingRule(rule),
-      `${where} is ${JSON.stringify(rule)}, not ${FILING_RULE_GRAMMAR}`,
+      rule === null || isFilingRule(rule),
+      `${agent}: PRE_TOOL_FILING[${JSON.stringify(name)}] is ${JSON.stringify(rule)}, not null or ${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`,
+    isPlainObject(response),
+    `${agent}: adapter declares no 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 = lookup(response, level.keys);
+    assert.ok(
+      Array.isArray(keys) && keys.every((key) => typeof key === "string"),
+      `${agent}: PRE_TOOL_RESPONSE.${level.keys} is not an array of strings`,
+    );
+    assert.ok(
+      [true, false, null].includes(
+        /** @type {any} */ (lookup(response, level.failsOpen)),
+      ),
+      `${agent}: PRE_TOOL_RESPONSE.${level.failsOpen} must be true, false or null`,
+    );
+  }
 }
 
 /**
@@ -1237,7 +1268,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,

package/src/control-plane.mjs

@@ -496,9 +496,6 @@ 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
@@ -544,90 +541,52 @@ export function flatToolName(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
+ * What a host reads from an exit-0 answer to its pre-tool event (`PreToolUse`,
+ * `BeforeTool`), as two 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}
+ * Whether `value` is a plain object: not null, not an array.
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
  */
-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(".");
+export function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-/**
- * 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)
-  );
-}
+/** A {@link PreToolFiling} reference to one top-level argument; group 1 is the key. */
+const ARGUMENT_REF = /^\$\.([^.]+)$/u;
 
 /** 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 ".")}`;
+export const FILING_RULE_GRAMMAR = `{tool_name: <non-empty string>, input: "${WHOLE_ARGUMENTS}" or an object of "${WHOLE_ARGUMENTS}"/"$.<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.
+ * Whether `rule` is a non-null {@link PreToolFiling} rule: exactly a non-empty
+ * string `tool_name` and an `input` that is `"$"` or an object of `"$"` /
+ * `"$.<key>"` references. 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);
+  if (!isPlainObject(rule)) return false;
+  const { tool_name, input, ...extra } = rule;
+  const isRef = (/** @type {unknown} */ ref) =>
+    ref === WHOLE_ARGUMENTS ||
+    (typeof ref === "string" && ARGUMENT_REF.test(ref));
   return (
-    keys.length === 2 &&
-    keys[0] === "input" &&
-    keys[1] === "tool_name" &&
+    Object.keys(extra).length === 0 &&
     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),
+    (input === WHOLE_ARGUMENTS ||
+      (isPlainObject(input) && Object.values(input).every(isRef)))
   );
-  return value === null ? undefined : value;
 }
 
 /**
@@ -635,7 +594,7 @@ function resolveArgument(ref, args) {
  * 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}.
+ * grammar or a kind other than `"function"` or `"freeform"`.
  * @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}
@@ -643,7 +602,7 @@ function resolveArgument(ref, args) {
  * @returns {{ tool_name: string, tool_input: unknown } | null}
  */
 export function fileModelCall(filing, kind, name, args) {
-  if (!MODEL_CALL_KINDS.has(kind))
+  if (kind !== "function" && kind !== "freeform")
     throw new Error(
       `control-plane: model call kind ${JSON.stringify(kind)} is neither "function" nor "freeform"`,
     );
@@ -657,10 +616,13 @@ export function fileModelCall(filing, kind, name, args) {
     );
   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),
-  ]);
+  const entries = Object.entries(rule.input).map(([key, ref]) => {
+    const argument = ARGUMENT_REF.exec(ref)?.[1];
+    if (argument === undefined) return [key, args];
+    // A missing key, a null value, or non-object arguments all fail to resolve.
+    const value = isPlainObject(args) ? lookup(args, argument) : undefined;
+    return [key, value === null ? undefined : value];
+  });
   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.
@@ -705,8 +667,8 @@ export const VETO_IMPOSSIBLE = Object.freeze([
  * @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.
+ * @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.
  */
 
 /**
@@ -1050,6 +1012,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/claude.d.mts

@@ -82,11 +82,11 @@ export const NATIVE_ASK_TIER: true;
  */
 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.
+ * 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;

package/types/adapters/codex.d.mts

@@ -36,15 +36,17 @@ export function parse(native: any, { version }?: {
  * on an enforceable deny. On a pre-v0.135 Codex (`this_call_vetoable` false) the
  * body still renders but exit stays 0 and `enforced` is false — advisory only.
  *
- * The two kinds use DIFFERENT native shapes, because Codex does: a pre-tool
- * decision rides `hookSpecificOutput.permissionDecision`, a post-tool one the
- * top-level `decision`/`reason` pair (`permissionDecision` is accepted but inert
- * on PostToolUse, so emitting it there would read as a block that never bites).
+ * Each native event gets its OWN shape, because Codex parses each strictly: a
+ * PreToolUse decision rides `hookSpecificOutput.permissionDecision`, a
+ * PermissionRequest one `hookSpecificOutput.decision.behavior`, and a
+ * post-tool one the top-level `decision`/`reason` pair.
  *
  * `soleGate` (default `false`) is the same dangerous, explicit opt-in as the
- * Claude adapter: when `true` AND the verdict is `allow`, the render emits the
- * real `permissionDecision: "allow"` instead of abstaining. It has no meaning
- * post-tool — there is no approval left to grant — so it is ignored there.
+ * Claude adapter, and acts only on PermissionRequest: there an `allow` renders
+ * `behavior: "allow"`, which grants the approval (except, from 0.166, when the
+ * hook is environment-sourced). PreToolUse has no allow that
+ * approves anything (Codex accepts `"allow"` only beside `updatedInput`, as a
+ * rewrite), and post-tool there is no approval left to grant.
  * @param {Verdict} verdict
  * @param {ToolCallEvent} event
  * @param {{ soleGate?: boolean }} [options]
@@ -103,11 +105,15 @@ export const INTEGRATION_MODE: "external_hook";
 /** @type {import("../control-plane.mjs").CoverageMap} */
 export const COVERAGE: import("../control-plane.mjs").CoverageMap;
 /**
- * Which {@link VERDICT_CONTENT_FIELDS} have no native channel on each kind, so
- * `render` drops them. Codex splits its two content channels by event:
- * `updatedInput` exists only on PreToolUse (the call has not run yet), and
- * `hookSpecificOutput.additionalContext` only on PostToolUse — Codex documents
- * no context field on PreToolUse, where `updatedInput` is the whole surface.
+ * Which {@link VERDICT_CONTENT_FIELDS} have no native channel on each kind's
+ * {@link NATIVE_EVENT_FOR} event, so `render` drops them. PreToolUse takes
+ * `updatedInput` (applied only beside `permissionDecision: "allow"`) and
+ * `additionalContext`; PostToolUse takes `additionalContext` alone ([X8], read
+ * at `rust-v0.166.0` and identical at `rust-v0.135.0`). `PermissionRequest`,
+ * which also parses as `pre_tool`, takes neither: its schema is
+ * `{hookEventName, decision: {behavior, message}}`, and a body carrying
+ * `updatedInput` is ignored (Codex's own approval flow decides), so
+ * {@link render} drops both there.
  *
  * NEITHER kind can rewrite tool output: PostToolUse "can't undo side effects
  * from a tool that already ran", and Codex rejects `updatedMCPToolOutput`, so
@@ -144,12 +150,15 @@ export const UNRENDERED_FIELDS: Record<string, ReadonlySet<string> | undefined>;
  */
 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.
+ * Codex's `PreToolUse` output parser ([X8], `rust-v0.166.0`) deserializes the
+ * body into `deny_unknown_fields` structs at both levels: these seven top-level
+ * keys (`PreToolUseCommandOutputWire` with its flattened universal fields), and
+ * these five in `hookSpecificOutput`. 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 value or combination (`continue: false`, any
+ * `stopReason`, `suppressOutput: true`, `decision: "approve"`, `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;

package/types/adapters/gemini.d.mts

@@ -139,7 +139,9 @@ export const PRE_TOOL_FILING: import("../control-plane.mjs").PreToolFiling;
  * 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`).
+ * `62bab5b2`). The top level is the `HookOutput` interface's seven keys, read
+ * from an unchecked `JSON.parse` cast (`hooks/hookRunner.ts`), so an unknown
+ * top-level key is ignored too.
  * @type {import("../control-plane.mjs").PreToolResponse}
  */
 export const PRE_TOOL_RESPONSE: import("../control-plane.mjs").PreToolResponse;

package/types/control-plane.d.mts

@@ -135,9 +135,26 @@ export function readonlySet(values: Iterable<string>): ReadonlySet<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.
+ * What a host reads from an exit-0 answer to its pre-tool event (`PreToolUse`,
+ * `BeforeTool`), as two 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 `value` is a plain object: not null, not an array.
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+export function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Whether `rule` is a non-null {@link PreToolFiling} rule: exactly a non-empty
+ * string `tool_name` and an `input` that is `"$"` or an object of `"$"` /
+ * `"$.<key>"` references. The one grammar both {@link fileModelCall} and the
+ * conformance harness hold a rule to.
  * @param {unknown} rule
  * @returns {boolean}
  */
@@ -147,7 +164,7 @@ export function isFilingRule(rule: unknown): boolean;
  * 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}.
+ * grammar or a kind other than `"function"` or `"freeform"`.
  * @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}
@@ -172,8 +189,8 @@ export function fileModelCall(filing: PreToolFiling, kind: "function" | "freefor
  * @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.
+ * @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.
  */
 /**
  * Build a normalized {@link ToolCallEvent}, stamping the schema version. Pure —
@@ -582,12 +599,8 @@ export const VERDICT_CONTENT_FIELDS: readonly string[];
 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.
@@ -634,6 +647,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.
@@ -645,17 +660,19 @@ export const BLOCK_TRANSPORT: Readonly<Record<string, Readonly<{
     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]).
+ * What a host reads from an exit-0 answer to its pre-tool event (`PreToolUse`,
+ * `BeforeTool`), as two 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.
  */
 export type PreToolResponse = 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;
 }>;
 /**
  * The translator for one agent's protocol. `parse` maps a native event to a
@@ -687,11 +704,11 @@ export type Adapter = {
      */
     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.
+     * 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.
      */
     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.
+     * 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.
      */
     UNRENDERED_FIELDS: Record<string, ReadonlySet<string> | undefined>;
 };