agent-control-plane-core 0.12.0 → 0.14.0

package/README.md

@@ -192,9 +192,48 @@ A consumer that cannot import these modules (a bash hook wrapper, a Python
 monitor) reads `schema/control-plane/v1/agents.json` instead. It is generated
 from the adapters, with one row per agent: its block exit code and reason
 stream, whether a block needs a reason, whether it has an ask tier, the entry's
-default response when the hook breaks, its hook coverage, and the verdict
-fields an allow cannot carry. Read the file from the installed package, so it
-always matches the adapters that version ships.
+default response when the hook breaks, its hook coverage, the verdict
+fields an allow cannot carry 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
+  separator, unless the namespace is empty or Codex's default `functions`
+  (`flatToolName` in `/contract`). Each value is one of:
+  - `null`: no pre-tool hook fires for this call.
+  - `{"tool_name": T, "input": I}`: the hook files `tool_name` T, and builds
+    `tool_input` from I. I is either `"$"`, meaning the call's whole arguments
+    value, or an object whose values are each `"$"` or `"$.<key>"`, meaning
+    that top-level argument. `<key>` is one literal key, non-empty and with no
+    `.`. If a `"$.<key>"` does not resolve (the arguments are not an object,
+    lack the key, or hold `null` there), the hook files nothing.
+
+  A function call the map does not list is filed with the model's own name and
+  arguments. A freeform (custom) call the map does not list files nothing; of
+  the shipped hosts only Codex makes them. The map describes calls the host
+  dispatches: Codex files nothing for a call it rejects first, e.g. a name it
+  has no tool for, a call kind the tool does not take, or arguments a handler
+  refuses before its hook (an `apply_patch` patch that does not parse, an
+  `exec_command` with a non-string `workdir`). On Codex the arguments value is a function call's
+  `arguments` parsed as JSON (an empty or all-whitespace string reads as `{}`,
+  unparseable text stays the raw string), or a freeform call's raw `input`
+  string. `fileModelCall` in `/contract` is the reference implementation; it
+  takes the call's kind, `"function"` or `"freeform"`. The map does not model
+  Codex's MCP names: Codex files an MCP call as `mcp__<namespace>__<tool>`,
+  which can differ from the flat name.
+
+Read the file from the installed package, so it always matches the adapters
+that version ships.
 
 Each entry fails the way its host expects when the hook itself breaks: claude,
 codex and gemini run the call, and amp asks. Set `ACP_FAIL_CLOSED=1` to block

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-control-plane-core",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Vendor-neutral control-plane contract for coding agents: a normalized ToolCallEvent/Verdict schema with per-agent adapters (Claude Code, Codex, Amp, Gemini CLI) and a conformance suite.",
   "type": "module",
   "repository": {

package/schema/control-plane/v1/agents.json

@@ -37,6 +37,27 @@
         "mutated_input",
         "mutated_output"
       ]
+    },
+    "pre_tool_filing": {},
+    "pre_tool_response": {
+      "hook_specific_output_keys": [
+        "additionalContext",
+        "hookEventName",
+        "permissionDecision",
+        "permissionDecisionReason",
+        "updatedInput"
+      ],
+      "unread_key_fails_open": null,
+      "top_level_keys": [
+        "continue",
+        "decision",
+        "hookSpecificOutput",
+        "reason",
+        "stopReason",
+        "suppressOutput",
+        "systemMessage"
+      ],
+      "unread_top_level_key_fails_open": null
     }
   },
   "codex": {
@@ -59,7 +80,6 @@
     },
     "unrendered_fields_on_allow": {
       "pre_tool": [
-        "additional_context",
         "mutated_output"
       ],
       "post_tool": [
@@ -81,6 +101,47 @@
         "mutated_input",
         "mutated_output"
       ]
+    },
+    "pre_tool_filing": {
+      "exec_command": {
+        "tool_name": "Bash",
+        "input": {
+          "command": "$.cmd"
+        }
+      },
+      "apply_patch": {
+        "tool_name": "apply_patch",
+        "input": {
+          "command": "$"
+        }
+      },
+      "multi_agent_v1spawn_agent": {
+        "tool_name": "spawn_agent",
+        "input": "$"
+      },
+      "write_stdin": null,
+      "wait": null,
+      "exec": null
+    },
+    "pre_tool_response": {
+      "hook_specific_output_keys": [
+        "additionalContext",
+        "hookEventName",
+        "permissionDecision",
+        "permissionDecisionReason",
+        "updatedInput"
+      ],
+      "unread_key_fails_open": true,
+      "top_level_keys": [
+        "continue",
+        "decision",
+        "hookSpecificOutput",
+        "reason",
+        "stopReason",
+        "suppressOutput",
+        "systemMessage"
+      ],
+      "unread_top_level_key_fails_open": true
     }
   },
   "amp": {
@@ -127,6 +188,13 @@
         "mutated_input",
         "mutated_output"
       ]
+    },
+    "pre_tool_filing": {},
+    "pre_tool_response": {
+      "hook_specific_output_keys": [],
+      "unread_key_fails_open": false,
+      "top_level_keys": [],
+      "unread_top_level_key_fails_open": false
     }
   },
   "gemini": {
@@ -169,6 +237,23 @@
         "mutated_input",
         "mutated_output"
       ]
+    },
+    "pre_tool_filing": {},
+    "pre_tool_response": {
+      "hook_specific_output_keys": [
+        "tool_input"
+      ],
+      "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

@@ -169,6 +169,25 @@ export function parse(native) {
  */
 export const NATIVE_ASK_TIER = true;
 
+/**
+ * No rename is modelled: no source shows Amp filing a call under a
+ * name or input other than the model's.
+ * @type {import("../control-plane.mjs").PreToolFiling}
+ */
+export const PRE_TOOL_FILING = Object.freeze({});
+
+/**
+ * Amp reads only the hook's exit code and no body, so no key in one can change
+ * the outcome.
+ * @type {import("../control-plane.mjs").PreToolResponse}
+ */
+export const PRE_TOOL_RESPONSE = Object.freeze({
+  hook_specific_output_keys: Object.freeze([]),
+  unread_key_fails_open: false,
+  top_level_keys: Object.freeze([]),
+  unread_top_level_key_fails_open: false,
+});
+
 /**
  * The EXHAUSTIVE (decision × `this_call_vetoable`) → exit-code table for Amp's
  * pure exit-code transport: 0 allow / 1 ask / 2 reject.
@@ -288,6 +307,8 @@ export const ampAdapter = {
   UNRENDERED_FIELDS,
   NATIVE_ASK_TIER,
   NATIVE_EVENT_FOR,
+  PRE_TOOL_FILING,
+  PRE_TOOL_RESPONSE,
   parse,
   render,
 };

package/src/adapters/claude.mjs

@@ -125,6 +125,42 @@ export const UNRENDERED_FIELDS = Object.freeze({
  */
 export const NATIVE_ASK_TIER = true;
 
+/**
+ * No rename is modelled: no source shows Claude Code filing a call under a
+ * name or input other than the model's.
+ * @type {import("../control-plane.mjs").PreToolFiling}
+ */
+export const PRE_TOOL_FILING = Object.freeze({});
+
+/**
+ * The 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({
+  hook_specific_output_keys: Object.freeze([
+    "additionalContext",
+    "hookEventName",
+    "permissionDecision",
+    "permissionDecisionReason",
+    "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). */
 export const HookEvent = Object.freeze({
   PRE_TOOL_USE: "PreToolUse",
@@ -339,6 +375,8 @@ export const claudeAdapter = {
   UNRENDERED_FIELDS,
   NATIVE_ASK_TIER,
   NATIVE_EVENT_FOR,
+  PRE_TOOL_FILING,
+  PRE_TOOL_RESPONSE,
   parse,
   render,
 };

package/src/adapters/codex.mjs

@@ -31,7 +31,6 @@ import {
   makeEvent,
   normalizeVerdict,
   gatedResponse,
-  blockTransportFor,
   blockReason,
   UNRENDERED_ON_UNKNOWN,
   readonlySet,
@@ -39,6 +38,7 @@ import {
   asObject,
   asString,
   asStringOrNull,
+  WHOLE_ARGUMENTS,
 } from "../control-plane.mjs";
 
 /** @typedef {import("../control-plane.mjs").ToolCallEvent} ToolCallEvent */
@@ -90,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
@@ -107,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
@@ -126,10 +131,84 @@ 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"]),
 });
 
+/**
+ * How Codex's `PreToolUse` hook files a model tool call ([X7], read from
+ * Codex's source at `rust-v0.166.0`). A function tool is filed under its flat
+ * name (namespace + name) with its parsed arguments by default; these
+ * handlers supply their own payload or none:
+ * - `exec_command` → `Bash` with `{command: <cmd>}`; arguments Codex cannot
+ *   parse as `ExecCommandArgs` file nothing, which this table models only for
+ *   a missing or null `cmd` or scalar arguments. Not modelled: other type
+ *   errors, and a positional array, which serde reads (`["ls"]` is `cmd: "ls"`).
+ * - `apply_patch` (a freeform tool) → `apply_patch` with its raw patch text as
+ *   `command`.
+ * - `spawn_agent` in the `multi_agent_v1` namespace → `spawn_agent`.
+ * - `write_stdin`, code mode's `wait`, and code mode's freeform `exec` → no hook.
+ *   These rules assume the named tool owns the name; a client-defined tool
+ *   called `wait` with code mode off takes the default payload.
+ *   The default payload is function-only, so a freeform extension tool files
+ *   nothing too — the mini-language's rule for an unlisted freeform call.
+ * NOT MODELLED: Codex files an MCP call as `mcp__<namespace>__<tool>`, with
+ * `_` trimmed from the namespace's end and the tool's start (`mcp.rs`
+ * `hook_tool_name`), which can differ from the flat name — a rule keyed by
+ * one name cannot express that.
+ * @type {import("../control-plane.mjs").PreToolFiling}
+ */
+export const PRE_TOOL_FILING = Object.freeze({
+  exec_command: Object.freeze({
+    tool_name: "Bash",
+    input: Object.freeze({ command: "$.cmd" }),
+  }),
+  apply_patch: Object.freeze({
+    tool_name: "apply_patch",
+    input: Object.freeze({ command: WHOLE_ARGUMENTS }),
+  }),
+  multi_agent_v1spawn_agent: Object.freeze({
+    tool_name: "spawn_agent",
+    input: WHOLE_ARGUMENTS,
+  }),
+  write_stdin: null,
+  wait: null,
+  exec: null,
+});
+
+/**
+ * Codex's `PreToolUse` output parser ([X8], `rust-v0.166.0`) deserializes 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({
+  hook_specific_output_keys: Object.freeze([
+    "additionalContext",
+    "hookEventName",
+    "permissionDecision",
+    "permissionDecisionReason",
+    "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. */
 export const MIN_ENFORCING_VERSION = Object.freeze([0, 135]);
 
@@ -299,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]
@@ -333,15 +414,12 @@ 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, enforced, 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
@@ -349,36 +427,73 @@ export function render(verdict, event, { soleGate = false } = {}) {
  * @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, enforced, soleGate) {
+  if (event.event === EventKind.POST_TOOL)
+    return postToolBody(hookEventName, vd);
+  if (hookEventName === HookEvent.PERMISSION_REQUEST)
+    return permissionRequestBody(hookEventName, vd, enforced, 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} enforced
+ * @param {boolean} soleGate
+ * @returns {Record<string, unknown>}
+ */
+function permissionRequestBody(hookEventName, vd, enforced, soleGate) {
+  /** @type {Record<string, unknown>} */
+  const hookSpecificOutput = { hookEventName };
+  if (vd.decision !== Decision.ALLOW) {
+    const message = enforced ? blockReason(vd.reason) : vd.reason;
+    hookSpecificOutput.decision = {
+      behavior: Decision.DENY,
+      ...(message === undefined ? {} : { message }),
+    };
+  } 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
@@ -387,27 +502,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;
 }
 
@@ -440,6 +549,8 @@ export function createCodexAdapter(options = {}) {
     UNRENDERED_FIELDS,
     NATIVE_ASK_TIER,
     NATIVE_EVENT_FOR,
+    PRE_TOOL_FILING,
+    PRE_TOOL_RESPONSE,
     parse: (native) => parse(native, { version }),
     render,
   };

package/src/adapters/gemini.mjs

@@ -357,6 +357,40 @@ export function parse(native) {
  */
 export const NATIVE_ASK_TIER = false;
 
+/**
+ * No rename is modelled. Gemini CLI hands `BeforeTool` the invocation's tool
+ * name beside an `originalRequestName`, so an aliased call may be filed under
+ * a name the model did not use; that is unverified, so not published.
+ * @type {import("../control-plane.mjs").PreToolFiling}
+ */
+export const PRE_TOOL_FILING = Object.freeze({});
+
+/**
+ * Gemini CLI keeps `hookSpecificOutput` as a `Record<string, unknown>` and its
+ * `BeforeTool` path reads only `tool_input` from it, by `in` lookup, so any
+ * other key is ignored (`packages/core/src/hooks/types.ts`
+ * `BeforeToolHookOutput`; both firing paths, `core/coreToolHookTriggers.ts`
+ * and `scheduler/hook-utils.ts` `evaluateBeforeToolHook`, read at gemini-cli
+ * `62bab5b2`). 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,
+});
+
 /**
  * Render into Gemini CLI's native external-hook transport. An enforceable deny
  * renders as exit 2 (the System Block on BeforeTool; documented on BeforeAgent
@@ -477,6 +511,8 @@ export const geminiAdapter = {
   UNRENDERED_FIELDS,
   NATIVE_ASK_TIER,
   NATIVE_EVENT_FOR,
+  PRE_TOOL_FILING,
+  PRE_TOOL_RESPONSE,
   parse,
   render,
 };

package/src/agent-manifest.mjs

@@ -30,7 +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 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>}
  */
@@ -55,6 +61,8 @@ function manifestRow(id) {
         ].sort(),
       ]),
     ),
+    pre_tool_filing: adapter.PRE_TOOL_FILING,
+    pre_tool_response: adapter.PRE_TOOL_RESPONSE,
   };
 }