agent-control-plane-core 0.11.2 → 0.13.0

package/types/adapters/codex.d.mts

@@ -58,11 +58,12 @@ export function render(verdict: Verdict, event: ToolCallEvent, { soleGate }?: {
  * the Codex version the launcher pinned (Codex's hook stdin carries none).
  * Below {@link MIN_ENFORCING_VERSION} every event parses observe-only and a
  * deny renders advisory. With no `version`, `parse` falls back to a payload
- * `version` (see {@link parse}).
+ * `version` (see {@link parse}). An option outside {@link OPTION_NAMES} throws,
+ * so a misspelled setting is never dropped in silence.
  * @param {{ version?: string }} [options]
  * @returns {import("../control-plane.mjs").Adapter}
  */
-export function createCodexAdapter({ version }?: {
+export function createCodexAdapter(options?: {
     version?: string;
 }): import("../control-plane.mjs").Adapter;
 /** @typedef {import("../control-plane.mjs").ToolCallEvent} ToolCallEvent */
@@ -118,6 +119,40 @@ export const COVERAGE: import("../control-plane.mjs").CoverageMap;
  * @type {Record<string, ReadonlySet<string>|undefined>}
  */
 export const UNRENDERED_FIELDS: Record<string, ReadonlySet<string> | undefined>;
+/**
+ * How Codex's `PreToolUse` hook files a model tool call ([X7], read from
+ * Codex's source at `rust-v0.166.0`). A function tool is filed under its flat
+ * name (namespace + name) with its parsed arguments by default; these
+ * handlers supply their own payload or none:
+ * - `exec_command` → `Bash` with `{command: <cmd>}`; arguments Codex cannot
+ *   parse as `ExecCommandArgs` file nothing, which this table models only for
+ *   a missing or null `cmd` or scalar arguments. Not modelled: other type
+ *   errors, and a positional array, which serde reads (`["ls"]` is `cmd: "ls"`).
+ * - `apply_patch` (a freeform tool) → `apply_patch` with its raw patch text as
+ *   `command`.
+ * - `spawn_agent` in the `multi_agent_v1` namespace → `spawn_agent`.
+ * - `write_stdin`, code mode's `wait`, and code mode's freeform `exec` → no hook.
+ *   These rules assume the named tool owns the name; a client-defined tool
+ *   called `wait` with code mode off takes the default payload.
+ *   The default payload is function-only, so a freeform extension tool files
+ *   nothing too — the mini-language's rule for an unlisted freeform call.
+ * NOT MODELLED: Codex files an MCP call as `mcp__<namespace>__<tool>`, with
+ * `_` trimmed from the namespace's end and the tool's start (`mcp.rs`
+ * `hook_tool_name`), which can differ from the flat name — a rule keyed by
+ * one name cannot express that.
+ * @type {import("../control-plane.mjs").PreToolFiling}
+ */
+export const PRE_TOOL_FILING: import("../control-plane.mjs").PreToolFiling;
+/**
+ * Codex's `PreToolUse` output parser ([X8], `rust-v0.166.0`) deserializes
+ * `hookSpecificOutput` into a `deny_unknown_fields` struct of exactly these
+ * five keys. Any other key fails the whole body: the run is marked failed, no
+ * block is set, and the call RUNS. A known key can still void the body by its
+ * combination (`updatedInput` without `permissionDecision: "allow"`), which
+ * this declaration does not describe.
+ * @type {import("../control-plane.mjs").PreToolResponse}
+ */
+export const PRE_TOOL_RESPONSE: import("../control-plane.mjs").PreToolResponse;
 /** Minimum Codex version whose hook can actually veto a tool call. */
 export const MIN_ENFORCING_VERSION: readonly number[];
 /**
@@ -140,6 +175,8 @@ export const NATIVE_EVENT_FOR: Record<string, string | undefined>;
  * naming a key the host discards.
  */
 export const NATIVE_ASK_TIER: false;
+/** The launcher option names {@link createCodexAdapter} reads. */
+export const OPTION_NAMES: readonly string[];
 /**
  * The Codex adapter with no launcher-pinned version. Real Codex sends no
  * version, so every event it sends parses observe-only here. A deployment that

package/types/adapters/gemini.d.mts

@@ -126,6 +126,23 @@ export const GEMINI_TOOL_ALIASES: Readonly<Record<string, string>>;
  * here, because an un-escalated ask lets Gemini run the tool.
  */
 export const NATIVE_ASK_TIER: false;
+/**
+ * No rename is modelled. Gemini CLI hands `BeforeTool` the invocation's tool
+ * name beside an `originalRequestName`, so an aliased call may be filed under
+ * a name the model did not use; that is unverified, so not published.
+ * @type {import("../control-plane.mjs").PreToolFiling}
+ */
+export const PRE_TOOL_FILING: import("../control-plane.mjs").PreToolFiling;
+/**
+ * Gemini CLI keeps `hookSpecificOutput` as a `Record<string, unknown>` and its
+ * `BeforeTool` path reads only `tool_input` from it, by `in` lookup, so any
+ * other key is ignored (`packages/core/src/hooks/types.ts`
+ * `BeforeToolHookOutput`; both firing paths, `core/coreToolHookTriggers.ts`
+ * and `scheduler/hook-utils.ts` `evaluateBeforeToolHook`, read at gemini-cli
+ * `62bab5b2`).
+ * @type {import("../control-plane.mjs").PreToolResponse}
+ */
+export const PRE_TOOL_RESPONSE: import("../control-plane.mjs").PreToolResponse;
 /** @type {import("../control-plane.mjs").Adapter} */
 export const geminiAdapter: import("../control-plane.mjs").Adapter;
 export type ToolCallEvent = import("../control-plane.mjs").ToolCallEvent;

package/types/agent-manifest.d.mts

@@ -0,0 +1,8 @@
+/**
+ * Every generated file, keyed by its package-relative path: the JSON Schema
+ * documents and their data maps, plus `agents.json`, keyed by agent id in
+ * {@link AGENT_IDS} order. The SSOT the generator writes and the freshness test
+ * reads, so neither carries its own list of filenames.
+ * @returns {Record<string, Record<string, unknown>>}
+ */
+export function generatedDocuments(): Record<string, Record<string, unknown>>;

package/types/conformance.d.mts

@@ -132,13 +132,18 @@ export function assertAliasedInputsCanonical(fixturesList: any[], assert: any):
  *      decide where an `ask` must be escalated to a `deny`, so a wrong one
  *      either lets a call through or denies every asked call on the hosts that
  *      do ask. OBSERVE_ONLY renders are exempt, as in rule ⑧.
+ *  12. pre-tool key honesty: the adapter declares a well-formed
+ *      `PRE_TOOL_FILING` and `PRE_TOOL_RESPONSE`, and every render on the host's
+ *      native pre-tool event — fixture, rule ⑧ and rule ⑩ probes alike — puts
+ *      in `hookSpecificOutput` only keys `PRE_TOOL_RESPONSE` says the host
+ *      reads. At least one such render must be checked.
  *
  * `assert` is injected (node:assert/strict) so the harness stays test-framework
  * neutral; it throws on the first mismatch. Returns a summary the caller can
  * assert further on.
  *
  * @param {{ adapter: import("./control-plane.mjs").Adapter, fixtures: any, assert: any }} args
- * @returns {{ cases: number, renders: number, decisionsSeen: Set<string>, mutationSeen: boolean, contentFieldsSeen: Set<string>, enforcedDenySeen: boolean, vetoableDenySeen: boolean, unknownKindSeen: boolean, coverageClassesChecked: Set<string>, unenforceableDenyChecks: number, askTierChecks: number }}
+ * @returns {{ cases: number, renders: number, decisionsSeen: Set<string>, mutationSeen: boolean, contentFieldsSeen: Set<string>, enforcedDenySeen: boolean, vetoableDenySeen: boolean, unknownKindSeen: boolean, coverageClassesChecked: Set<string>, unenforceableDenyChecks: number, askTierChecks: number, preToolKeyChecks: number }}
  */
 export function runAdapterConformance({ adapter, fixtures, assert }: {
     adapter: import("./control-plane.mjs").Adapter;
@@ -156,4 +161,5 @@ export function runAdapterConformance({ adapter, fixtures, assert }: {
     coverageClassesChecked: Set<string>;
     unenforceableDenyChecks: number;
     askTierChecks: number;
+    preToolKeyChecks: number;
 };

package/types/control-plane.d.mts

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

package/types/json-schema.d.mts

@@ -25,10 +25,10 @@ export function toolCallEventSchema(): Record<string, unknown>;
  */
 export function verdictSchema(): Record<string, unknown>;
 /**
- * Every generated file, keyed by its package-relative path — the SSOT the
- * generator writes and the freshness test reads, so neither carries its own
- * list of filenames. The two `.schema.json` entries are JSON Schema documents;
- * `tool-input-keys.json` is the data map {@link TOOL_INPUT_KEYS_FILE} describes.
+ * The contract's generated files, keyed by package-relative path. The two
+ * `.schema.json` entries are JSON Schema documents; `tool-input-keys.json` is
+ * the data map {@link TOOL_INPUT_KEYS_FILE} describes. `agent-manifest.mjs`'s
+ * `generatedDocuments` adds the per-agent manifest to these.
  * @returns {Record<string, Record<string, unknown>>}
  */
 export function jsonSchemaDocuments(): Record<string, Record<string, unknown>>;

package/types/registry.d.mts

@@ -13,9 +13,10 @@ export function assertRegistryConsistent(adapters: Record<string, Adapter>): voi
  * reason to silently fall back to a default agent (which would run the wrong
  * translator against the payloads and mis-render every verdict).
  *
- * `options` are the launcher's settings for that adapter (Codex:
- * `{ version }`). Passing options to an adapter that takes none throws, so a
- * setting the launcher believes it applied cannot be dropped in silence.
+ * `options` are the launcher's settings for that adapter, named by its
+ * {@link LAUNCHER_OPTIONS} row. Options for an adapter that takes none throw
+ * here, and an option a configurable adapter does not read throws in its
+ * factory, so a setting the launcher believes it applied is never dropped.
  * @param {string} id agent id (a {@link AGENT_IDS} member)
  * @param {Record<string, unknown>} [options]
  * @returns {Adapter}
@@ -37,4 +38,11 @@ export const ADAPTERS: Readonly<Record<string, Adapter>>;
  * @type {readonly string[]}
  */
 export const AGENT_IDS: readonly string[];
+/**
+ * The launcher option names each agent's adapter reads, for EVERY agent id (an
+ * empty list when it reads none). A launcher builds the options for any agent
+ * from this instead of naming the agents that take a version.
+ * @type {Readonly<Record<string, readonly string[]>>}
+ */
+export const LAUNCHER_OPTIONS: Readonly<Record<string, readonly string[]>>;
 export type Adapter = import("./control-plane.mjs").Adapter;

package/types/runtime.d.mts

@@ -1,3 +1,8 @@
+/**
+ * A guardrail judge: one normalized event in, its verdict out, synchronously or
+ * as a promise. Its answer is untrusted either way (see {@link renderHookResponse}).
+ * @typedef {(event: import("./control-plane.mjs").ToolCallEvent) => import("./control-plane.mjs").Verdict | Promise<import("./control-plane.mjs").Verdict>} Judge
+ */
 /**
  * Read all of stdin to a string.
  * @returns {Promise<string>}
@@ -31,16 +36,18 @@ export function demoJudge(event: import("./control-plane.mjs").ToolCallEvent): i
  * greppable trace. Every host tolerates hook stderr: claude/codex surface it
  * only in verbose/debug on a 0 exit, amp forwards the helper's stderr, and
  * gemini reads stderr as a reason only on exit 2.
- * `judge` is the seam a real deployment fills — {@link demoJudge} is a stand-in,
- * so the guardrail is supplied here rather than by forking this file. Whatever
- * it returns is treated as untrusted (see the clamp below).
+ * `judge` is the seam a real deployment fills, so the guardrail is supplied here
+ * rather than by forking this file ({@link demoJudge} is a stand-in). It may
+ * return a promise (a judge that asks a remote monitor); a rejection takes the
+ * same path as a throw. Whatever it returns is treated as untrusted (see the
+ * clamp below).
  * @param {import("./control-plane.mjs").Adapter} adapter
  * @param {string} rawInput
  * @param {import("./control-plane.mjs").NativeResponse} onFailure
- * @param {(event: import("./control-plane.mjs").ToolCallEvent) => import("./control-plane.mjs").Verdict} [judge]
- * @returns {import("./control-plane.mjs").NativeResponse}
+ * @param {Judge} [judge]
+ * @returns {Promise<import("./control-plane.mjs").NativeResponse>}
  */
-export function renderHookResponse(adapter: import("./control-plane.mjs").Adapter, rawInput: string, onFailure: import("./control-plane.mjs").NativeResponse, judge?: (event: import("./control-plane.mjs").ToolCallEvent) => import("./control-plane.mjs").Verdict): import("./control-plane.mjs").NativeResponse;
+export function renderHookResponse(adapter: import("./control-plane.mjs").Adapter, rawInput: string, onFailure: import("./control-plane.mjs").NativeResponse, judge?: Judge): Promise<import("./control-plane.mjs").NativeResponse>;
 /**
  * The response that BLOCKS the call on `agent`'s host: its
  * {@link BLOCK_TRANSPORT} row's exit code, with `reason` on the row's reason
@@ -69,12 +76,14 @@ export function failurePosture(agent: string, env?: NodeJS.ProcessEnv): import("
  * {@link renderHookResponse} with that host's {@link failurePosture}, and
  * {@link emit} the result. Every `bin/<host>-hook.mjs` is this one call. The
  * failure response also answers a stdin read error and, when
- * {@link hookDeadlineMs} is set, a hook still running at that deadline.
+ * {@link hookDeadlineMs} is set, a hook still running at that deadline. It also
+ * answers a judge promise that never settles once nothing else keeps node alive,
+ * which would otherwise end the process with no response.
  * @param {import("./control-plane.mjs").Adapter} adapter
- * @param {(event: import("./control-plane.mjs").ToolCallEvent) => import("./control-plane.mjs").Verdict} [judge]
+ * @param {Judge} [judge]
  * @returns {Promise<never>}
  */
-export function runHookEntry(adapter: import("./control-plane.mjs").Adapter, judge?: (event: import("./control-plane.mjs").ToolCallEvent) => import("./control-plane.mjs").Verdict): Promise<never>;
+export function runHookEntry(adapter: import("./control-plane.mjs").Adapter, judge?: Judge): Promise<never>;
 /**
  * `ACP_HOOK_TIMEOUT_MS` as a positive integer, or `undefined` when unset. Set it
  * below the host's own hook timeout, so the hook's failure response lands
@@ -135,3 +144,8 @@ export function emit(response: import("./control-plane.mjs").NativeResponse): ne
  * @type {Readonly<Record<string, import("./control-plane.mjs").NativeResponse>>}
  */
 export const HOST_FAILURE: Readonly<Record<string, import("./control-plane.mjs").NativeResponse>>;
+/**
+ * A guardrail judge: one normalized event in, its verdict out, synchronously or
+ * as a promise. Its answer is untrusted either way (see {@link renderHookResponse}).
+ */
+export type Judge = (event: import("./control-plane.mjs").ToolCallEvent) => import("./control-plane.mjs").Verdict | Promise<import("./control-plane.mjs").Verdict>;