agent-control-plane-core 0.6.4 → 0.8.0

package/src/json-schema.mjs

@@ -0,0 +1,331 @@
+/**
+ * JSON Schema (draft 2020-12) for the two wire shapes, for a consumer that is
+ * not JavaScript.
+ *
+ * A Python guardrail cannot import {@link ToolCallEvent} from this package, so
+ * it hand-writes the field names it reads and drifts silently: the contract
+ * renames a field, the hand-written reader sees `undefined`, and it takes its
+ * no-value branch instead of failing. These documents are the machine-readable
+ * form of the same contract, so that reader validates against the seam rather
+ * than against its own copy.
+ *
+ * EVERY ENUMERATED VALUE IS DERIVED, never typed a second time — each one is
+ * read off the frozen export that owns it: {@link EventKind},
+ * {@link Decision}, {@link IntegrationMode}, {@link STANDARD_META_FIELDS},
+ * {@link SCHEMA_VERSION}, {@link MODELED_TOOL_INPUT_KEYS}. The files under
+ * `schema/` are generated output that `json-schema.test.mjs` regenerates and
+ * byte-compares, not a second contract.
+ *
+ * FIELD NAMES ARE WRITTEN HERE, because the contract exports no list of them —
+ * the root fields and the always-present `EventMeta` fields are typedefs, which
+ * do not survive to runtime. So a renamed contract field is caught rather than
+ * declared: `json-schema.test.mjs` re-parses every golden native payload through
+ * the LIVE adapter and validates the result, and `additionalProperties: false`
+ * turns the rename into a rejection. {@link VERDICT_CONTENT_FIELDS} is the one
+ * list that does exist, and {@link assertVerdictFieldsDeclared} holds the
+ * verdict document to it — in the ADDING direction only. `reason` is outside
+ * that list (it is not probeable from one abstaining verdict), so its schema
+ * here rests on the `Verdict` typedef alone.
+ *
+ * SCOPE — the documents describe the contract's DECLARED shapes, which `tsc`
+ * checks at build time. `normalizeVerdict` re-checks only `decision` at run
+ * time, so a JavaScript caller who ignores the types can hand it a numeric
+ * `reason` and get one back; that value fails this document, correctly.
+ *
+ * A tool `input` stays unconstrained on purpose: an adapter forwards a native
+ * input object verbatim, so a schema demanding a string `command` on every Bash
+ * event would reject events the library legitimately emits — one golden Codex
+ * fixture carries `command` as an array. The per-tool field a judge should read
+ * is published beside the documents as data instead
+ * ({@link MODELED_TOOL_INPUT_KEYS}, in `tool-input-keys.json`).
+ */
+
+import {
+  CONTROL_PLANE_SCHEMA,
+  Decision,
+  EventKind,
+  IntegrationMode,
+  MODELED_TOOL_INPUT_KEYS,
+  SCHEMA_VERSION,
+  STANDARD_META_FIELDS,
+  VERDICT_CONTENT_FIELDS,
+} from "./control-plane.mjs";
+
+/** The JSON Schema dialect these documents are written in. */
+const JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+
+/**
+ * Package-relative directory the generated files live in, versioned by the WIRE
+ * version. A breaking shape change bumps {@link CONTROL_PLANE_SCHEMA} and so
+ * writes a new directory, leaving the previous one in place for a consumer
+ * still on it.
+ *
+ * A document is THIS RELEASE's rendering of that wire version, not a statement
+ * about every release that will carry it. Adding an optional field is
+ * backward-compatible and stays at v1 (see the README's Versioning section), so
+ * the next release's document may carry a property this one does not. That is
+ * why the files ship inside the package: a consumer reads the schema from the
+ * same installed version that produced the event, and the two move together.
+ * Validate against the installed file, never a copy pinned by hand.
+ *
+ * Neither document carries an `$id`. A URL naming a mutable branch would resolve
+ * to whatever the contract says LATER, and two installed versions declaring one
+ * `$id` collide inside a single validator instance. `$ref` here is
+ * document-relative, so nothing needs one.
+ */
+export const SCHEMA_DIR = `schema/${CONTROL_PLANE_SCHEMA}`;
+
+/** Basename of each generated document, keyed by the shape it describes. */
+export const SCHEMA_FILES = Object.freeze({
+  ToolCallEvent: "tool-call-event.schema.json",
+  Verdict: "verdict.schema.json",
+});
+
+/**
+ * Basename of the per-tool input-key map, published as plain DATA rather than
+ * inside the event document. A vendor keyword there (`x-modeled-tool-input-keys`)
+ * is legal JSON Schema, but ajv refuses an unknown keyword under its default
+ * options, so the document a JavaScript consumer installed would not compile
+ * until that consumer registered a vocabulary it has no reason to know about.
+ */
+export const TOOL_INPUT_KEYS_FILE = "tool-input-keys.json";
+
+/**
+ * The schema for each optional {@link Verdict} field. Kept beside the
+ * assertion below rather than inlined, so a content field added to
+ * {@link VERDICT_CONTENT_FIELDS} fails loud here instead of quietly dropping
+ * out of the published document — a consumer would then read a field the
+ * schema calls forbidden and reject a verdict this library produces.
+ */
+const VERDICT_FIELD_SCHEMAS = Object.freeze({
+  mutated_input: {
+    type: "object",
+    description:
+      "Replacement tool input (pre_tool). A data channel, carried verbatim.",
+  },
+  mutated_output: {
+    description:
+      "Replacement tool output (post_tool): a string or the tool's structured output, verbatim. Any JSON value.",
+  },
+  additional_context: {
+    type: "string",
+    description: "Extra context to splice into the agent's stream.",
+  },
+  reason: {
+    type: "string",
+    description: "Human-readable rationale, shown on deny and ask.",
+  },
+});
+
+/**
+ * Assert every content field the contract models has a schema above. Throws
+ * (fail loud) on the first that does not: `additionalProperties: false` makes an
+ * undeclared field a REJECTION rather than an omission, so a consumer would
+ * refuse a verdict this library produces. Called at import against the live
+ * {@link VERDICT_CONTENT_FIELDS}; exported so a test can drive both branches.
+ * @param {readonly string[]} fields
+ * @param {Record<string, unknown>} declared
+ */
+export function assertVerdictFieldsDeclared(fields, declared) {
+  for (const field of fields)
+    if (!Object.hasOwn(declared, field))
+      throw new Error(
+        `json-schema: verdict content field ${JSON.stringify(field)} has no declared schema — add one to VERDICT_FIELD_SCHEMAS`,
+      );
+}
+
+assertVerdictFieldsDeclared(VERDICT_CONTENT_FIELDS, VERDICT_FIELD_SCHEMAS);
+
+/**
+ * The `EventMeta` subschema. The optional string fields are
+ * {@link STANDARD_META_FIELDS} plus `native_tool`; `string` is not a guess for
+ * them, it is what `baseMeta` enforces (a non-string value leaves the field
+ * absent rather than stamping a number onto a field consumers read as text).
+ * @returns {Record<string, unknown>}
+ */
+function eventMetaSchema() {
+  /** @type {Record<string, unknown>} */
+  const properties = {
+    agent: {
+      type: "string",
+      description: 'Producing agent id ("claude", "codex", …).',
+    },
+    native_event: {
+      type: "string",
+      description: "Original native event name, preserved verbatim.",
+    },
+    integration_mode: {
+      enum: Object.values(IntegrationMode),
+      description: "How the guardrail attaches to the host.",
+    },
+    primary_gate_present: {
+      type: "boolean",
+      description:
+        "The agent's own native gate already ran, so this verdict is a second opinion.",
+    },
+    passthrough: {
+      type: "object",
+      description: "Unmodelled native top-level fields, verbatim.",
+    },
+    native_tool: {
+      type: "string",
+      description:
+        "Original native tool name, present iff the event carries a tool.",
+    },
+  };
+  for (const field of STANDARD_META_FIELDS)
+    properties[field] = { type: "string" };
+  return {
+    type: "object",
+    required: [
+      "agent",
+      "native_event",
+      "integration_mode",
+      "primary_gate_present",
+      "passthrough",
+    ],
+    properties,
+    additionalProperties: false,
+  };
+}
+
+/**
+ * The document describing a normalized {@link ToolCallEvent}.
+ *
+ * `additionalProperties: false` is honest here rather than strict: `makeEvent`
+ * builds every event, and the unmodelled remainder of a native payload lands in
+ * `meta.passthrough`, so an extra key at the root is a hand-rolled event, not a
+ * newer library's.
+ * @returns {Record<string, unknown>}
+ */
+export function toolCallEventSchema() {
+  return {
+    $schema: JSON_SCHEMA_DIALECT,
+    title: "ToolCallEvent",
+    description: `A normalized, agent-agnostic view of one agent event (${CONTROL_PLANE_SCHEMA}).`,
+    type: "object",
+    required: [
+      "schema_version",
+      "event",
+      "tool",
+      "input",
+      "this_call_vetoable",
+      "meta",
+    ],
+    properties: {
+      schema_version: { const: SCHEMA_VERSION },
+      event: { enum: Object.values(EventKind) },
+      tool: {
+        type: ["string", "null"],
+        description:
+          "Canonical tool name; null for prompt and session events. The raw native name is on meta.native_tool.",
+      },
+      input: {
+        type: "object",
+        description:
+          "Passthrough tool input, verbatim; a submitted prompt is folded into input.prompt.",
+      },
+      response: {
+        description: "Tool output, post_tool only: any JSON value, verbatim.",
+      },
+      this_call_vetoable: {
+        type: "boolean",
+        description:
+          "false ⇒ the guardrail cannot veto THIS call, so a deny must degrade to a notification.",
+      },
+      meta: { $ref: "#/$defs/EventMeta" },
+    },
+    additionalProperties: false,
+    // Two claims a producer must not make, both the same fail-open: a veto the
+    // host will never perform, read downstream as a block that happened.
+    //
+    // An event the adapter could not name has no host response to veto, so a
+    // vetoable UNKNOWN is that claim. `makeEvent` throws on one. An OBSERVE_ONLY
+    // transport reads a transcript and cannot pre-empt anything, so a vetoable
+    // event on one is the same claim by a different route — every shipped
+    // adapter derives both flags from one "can this host enforce" answer, but
+    // `makeEvent` does NOT refuse it, so this document is the only place a
+    // producer is held to it.
+    allOf: [
+      vetoImpossibleWhen({ event: { const: EventKind.UNKNOWN } }),
+      vetoImpossibleWhen({
+        meta: {
+          required: ["integration_mode"],
+          properties: {
+            integration_mode: { const: IntegrationMode.OBSERVE_ONLY },
+          },
+        },
+      }),
+    ],
+    $defs: { EventMeta: eventMetaSchema() },
+  };
+}
+
+/**
+ * A conditional subschema forcing `this_call_vetoable: false` wherever `match`
+ * holds. `required` names every key `match` constrains, because an absent key
+ * satisfies a bare `properties` and would leave the `then` branch dead.
+ * @param {Record<string, unknown>} match
+ * @returns {Record<string, unknown>}
+ */
+function vetoImpossibleWhen(match) {
+  return {
+    if: { required: Object.keys(match), properties: match },
+    then: { properties: { this_call_vetoable: { const: false } } },
+  };
+}
+
+/**
+ * The document describing a normalized {@link Verdict}. Only `decision` is
+ * required; `normalizeVerdict` emits the optional fields only when present.
+ * @returns {Record<string, unknown>}
+ */
+export function verdictSchema() {
+  /** @type {Record<string, unknown>} */
+  const properties = { decision: { enum: Object.values(Decision) } };
+  // Cloned, not aliased. `Object.freeze` on VERDICT_FIELD_SCHEMAS freezes the
+  // outer object only, so assigning the nested `{type, description}` objects
+  // hands every caller the same two levels down: a consumer that tightens
+  // `properties.reason` on the document it was given would silently retighten
+  // every document produced afterwards. The other builders return fresh
+  // structures already.
+  for (const [field, schema] of Object.entries(VERDICT_FIELD_SCHEMAS))
+    properties[field] = structuredClone(schema);
+  return {
+    $schema: JSON_SCHEMA_DIALECT,
+    title: "Verdict",
+    description: `A normalized guardrail decision (${CONTROL_PLANE_SCHEMA}).`,
+    type: "object",
+    required: ["decision"],
+    properties,
+    additionalProperties: false,
+  };
+}
+
+/**
+ * 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.
+ * @returns {Record<string, Record<string, unknown>>}
+ */
+export function jsonSchemaDocuments() {
+  return {
+    [`${SCHEMA_DIR}/${SCHEMA_FILES.ToolCallEvent}`]: toolCallEventSchema(),
+    [`${SCHEMA_DIR}/${SCHEMA_FILES.Verdict}`]: verdictSchema(),
+    [`${SCHEMA_DIR}/${TOOL_INPUT_KEYS_FILE}`]: { ...MODELED_TOOL_INPUT_KEYS },
+  };
+}
+
+/**
+ * The bytes a generated file is written as: 2-space JSON with a trailing newline.
+ * This is NOT Prettier's rendering — Prettier collapses a short array onto one
+ * line — so `schema/` is in `.prettierignore` and this function owns the bytes
+ * the freshness test compares. A formatter allowed to rewrite them would red
+ * that test on a change to nothing.
+ * @param {Record<string, unknown>} document
+ * @returns {string}
+ */
+export function serializeSchema(document) {
+  return `${JSON.stringify(document, null, 2)}\n`;
+}

package/{bin/hook-runtime.mjs → src/runtime.mjs}

@@ -1,21 +1,39 @@
 /**
- * Shared plumbing for the per-host EXTERNAL_HOOK entries — NOT a runtime host
- * multiplexer. Each host has its OWN entry (`bin/<host>-hook.mjs`) that hardcodes
- * its adapter and declares its OWN failure posture; this module only holds the
- * transport mechanics they genuinely share (stdin read, the demo judge, the
- * parse→judge→render pipe with a host-supplied fail-safe, and stdout+exit
- * emission). The thing item ② deleted was the `--agent` switch that let one
- * binary impersonate every host and so had to pick a single shared failure
- * behavior; sharing pure plumbing across distinct entries is not that.
+ * The EXTERNAL_HOOK runtime, published at `agent-control-plane-core/runtime` —
+ * NOT a runtime host multiplexer. Each host has its OWN entry
+ * (`bin/<host>-hook.mjs`) that hardcodes its adapter and declares its OWN
+ * failure posture; this module only holds the transport mechanics they
+ * genuinely share (stdin read, the demo judge, the parse→judge→render pipe with
+ * a host-supplied fail-safe, and stdout+exit emission). The thing item ②
+ * deleted was the `--agent` switch that let one binary impersonate every host
+ * and so had to pick a single shared failure behavior; sharing pure plumbing
+ * across distinct entries is not that.
+ *
+ * It is exported because every consumer writing its own hook entry had to
+ * re-implement the same two things, and both fail silently when they are wrong:
+ * draining stdin before parsing, and flushing the response IN FULL before
+ * `process.exit` (see {@link writeAllSync}).
  */
 import { writeSync } from "node:fs";
-import { Decision, sanitizeVerdict } from "../src/control-plane.mjs";
+import { Decision, sanitizeVerdict } from "./control-plane.mjs";
 
-/** Read all of stdin to a string. */
+/**
+ * Read all of stdin to a string.
+ * @returns {Promise<string>}
+ */
 export function readStdin() {
   return new Promise((resolve, reject) => {
+    /** @type {Buffer[]} */
     const chunks = [];
-    process.stdin.on("data", (chunk) => chunks.push(chunk));
+    // A consumer that set an encoding on stdin hands STRINGS to this listener, and
+    // Buffer.concat throws on one. That throw escapes from the stream's callback,
+    // not from this promise, so it never reaches the caller's fail-safe: the hook
+    // dies with no response and a fail-open host runs the unjudged call.
+    process.stdin.on("data", (chunk) =>
+      chunks.push(
+        typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk,
+      ),
+    );
     process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString()));
     process.stdin.on("error", reject);
   });
@@ -25,8 +43,8 @@ export function readStdin() {
  * The DEMO policy standing in for a real guardrail judge: deny any command
  * matching /rm -rf/, allow everything else. A real deployment swaps this for its
  * own judge over the normalized {@link ToolCallEvent}.
- * @param {import("../src/control-plane.mjs").ToolCallEvent} event
- * @returns {import("../src/control-plane.mjs").Verdict}
+ * @param {import("./control-plane.mjs").ToolCallEvent} event
+ * @returns {import("./control-plane.mjs").Verdict}
  */
 export function demoJudge(event) {
   const command =
@@ -54,11 +72,11 @@ export function demoJudge(event) {
  * `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).
- * @param {import("../src/control-plane.mjs").Adapter} adapter
+ * @param {import("./control-plane.mjs").Adapter} adapter
  * @param {string} rawInput
- * @param {import("../src/control-plane.mjs").NativeResponse} onFailure
- * @param {(event: import("../src/control-plane.mjs").ToolCallEvent) => import("../src/control-plane.mjs").Verdict} [judge]
- * @returns {import("../src/control-plane.mjs").NativeResponse}
+ * @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}
  */
 export function renderHookResponse(
   adapter,
@@ -102,6 +120,24 @@ export function renderHookResponse(
  */
 const RETRY_SLEEP = new Int32Array(new SharedArrayBuffer(4));
 
+/**
+ * Whether a failed `writeSync` is the one recoverable case: EAGAIN, meaning the
+ * non-blocking pipe is momentarily full because the host has not drained it
+ * yet. The caller sleeps 1ms and retries — the same wait a blocking write would
+ * have done in the kernel. Every other errno (EPIPE, EBADF, ...) propagates.
+ *
+ * A non-Error throw is NOT retryable, and is checked separately rather than
+ * left to the `code` comparison: a plain object carrying `code: "EAGAIN"` is
+ * not a write that the kernel asked us to repeat, and retrying one forever is a
+ * hang rather than a short write. Exported so a test can drive every branch —
+ * the real `writeSync` only ever throws an Error.
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isRetryableWriteError(err) {
+  return err instanceof Error && /** @type {any} */ (err).code === "EAGAIN";
+}
+
 /**
  * Write `text` to `fd` IN FULL, looping until every byte lands.
  *
@@ -114,24 +150,23 @@ const RETRY_SLEEP = new Int32Array(new SharedArrayBuffer(4));
  * `mutated_input`) was silently truncated and the process still exited 0/2 with
  * a half-written JSON the host cannot parse: an enforced deny degrading to a
  * run. Looping restores the blocking-write semantics the caller assumes.
+ *
+ * Exported so a test can drive the propagation path against a real closed
+ * descriptor; {@link emit} is the only caller a consumer needs.
  * @param {number} fd
  * @param {string} text
  */
-function writeAllSync(fd, text) {
+export function writeAllSync(fd, text) {
   const buf = Buffer.from(text, "utf8");
   let written = 0;
   while (written < buf.length) {
     try {
       written += writeSync(fd, buf, written);
     } catch (err) {
-      // EAGAIN is the one recoverable case: the non-blocking pipe is momentarily
-      // full because the host has not drained it yet. Sleep 1ms and retry — the
-      // same wait a blocking write would have done in the kernel. Every other
-      // errno (EPIPE, EBADF, ...) propagates. There is deliberately no retry cap:
-      // a cap would reintroduce exactly the silent truncation this loop exists to
-      // kill, and a host that never reads would have blocked us forever anyway.
-      if (!(err instanceof Error) || /** @type {any} */ (err).code !== "EAGAIN")
-        throw err;
+      // There is deliberately no retry cap: a cap would reintroduce exactly the
+      // silent truncation this loop exists to kill, and a host that never reads
+      // would have blocked us forever anyway.
+      if (!isRetryableWriteError(err)) throw err;
       Atomics.wait(RETRY_SLEEP, 0, 0, 1);
     }
   }
@@ -140,7 +175,7 @@ function writeAllSync(fd, text) {
 /**
  * Emit a {@link NativeResponse} to the host: write the native stdout body when
  * the transport has one, then exit with the transport's exit code.
- * @param {import("../src/control-plane.mjs").NativeResponse} response
+ * @param {import("./control-plane.mjs").NativeResponse} response
  * @returns {never}
  */
 export function emit(response) {

package/types/adapters/amp.d.mts

@@ -3,6 +3,30 @@
  * @returns {ToolCallEvent}
  */
 export function parse(native: any): ToolCallEvent;
+/**
+ * Totality check: every `decision` in `decisions` must have a row in `table`
+ * and every row both vetoable columns. A decision added to the contract with
+ * no matching row breaks loudly instead of silently defaulting to exit 0.
+ * Called at import against {@link Decision} and {@link EXIT_CODE_BY_DECISION};
+ * exported so a test can drive both branches.
+ * @param {readonly string[]} decisions
+ * @param {Readonly<Record<string, Readonly<Record<string, number>>>>} table
+ */
+export function assertExitCodeTableTotal(decisions: readonly string[], table: Readonly<Record<string, Readonly<Record<string, number>>>>): void;
+/**
+ * Look up the exit code for `decision`/`vetoable` in `table`. Throws instead of
+ * returning `undefined`: the alternative is `exit_code: undefined`, which
+ * `process.exit` renders as 0 — the exact silent allow this table exists to
+ * eliminate. Unreachable from {@link render} on the real
+ * {@link EXIT_CODE_BY_DECISION} while {@link assertExitCodeTableTotal} holds at
+ * load; exported so a test can drive both branches against a synthetic,
+ * deliberately incomplete table.
+ * @param {Readonly<Record<string, Readonly<Record<string, number>>>>} table
+ * @param {string} decision
+ * @param {boolean} vetoable
+ * @returns {number}
+ */
+export function exitCodeFor(table: Readonly<Record<string, Readonly<Record<string, number>>>>, decision: string, vetoable: boolean): number;
 /**
  * Render into Amp's pure exit-code transport: the decision is the exit code,
  * with no stdout body. An ENFORCED deny also carries its `reason` on
@@ -72,6 +96,14 @@ export const NATIVE_EVENT_FOR: Record<string, string | undefined>;
  * @type {Record<string, ReadonlySet<string>|undefined>}
  */
 export const UNRENDERED_FIELDS: Record<string, ReadonlySet<string> | undefined>;
+/**
+ * Amp honours a distinct ask tier: exit 1 is its "ask the user", a code Amp
+ * treats as neither the allow (0) nor the reject (2). {@link render} emits it
+ * for every `ask`, so a consumer must NOT escalate an `ask` to a `deny` here.
+ * The table below leans on the same tier for the non-vetoable deny, which is
+ * only honest because the tier is real.
+ */
+export const NATIVE_ASK_TIER: true;
 /** @type {import("../control-plane.mjs").Adapter} */
 export const ampAdapter: import("../control-plane.mjs").Adapter;
 export type ToolCallEvent = import("../control-plane.mjs").ToolCallEvent;

package/types/adapters/claude.d.mts

@@ -9,7 +9,8 @@ export function parse(native: any): ToolCallEvent;
  * Render into Claude Code's native external-hook transport: a
  * `hookSpecificOutput` JSON body on stdout plus the exit code that carries the
  * decision (deny ⇒ exit 2). A deny only counts as `enforced` when the event's
- * `this_call_vetoable` holds.
+ * `this_call_vetoable` holds, and an enforced deny also carries its `reason` on
+ * `NativeResponse.stderr` (see below).
  *
  * `soleGate` (default `false`) is a dangerous, explicit opt-in: when `true` AND
  * the verdict is `allow`, the render emits Claude Code's REAL
@@ -65,6 +66,15 @@ export const COVERAGE: import("../control-plane.mjs").CoverageMap;
  * @type {Record<string, ReadonlySet<string>|undefined>}
  */
 export const UNRENDERED_FIELDS: Record<string, ReadonlySet<string> | undefined>;
+/**
+ * Claude Code honours a distinct ask tier: `hookSpecificOutput.permissionDecision
+ * = "ask"` suspends the call and puts it in front of the user, and {@link render}
+ * emits exactly that (see {@link gatingBody}). So a consumer must NOT escalate an
+ * `ask` to a `deny` here — the human already sees it. `render` still reports the
+ * ask as `enforced: false`, because this guardrail did not block the call; the
+ * host did, pending an answer.
+ */
+export const NATIVE_ASK_TIER: true;
 /** Claude Code native hook event names (the `hook_event_name` field). */
 export const HookEvent: Readonly<{
     PRE_TOOL_USE: "PreToolUse";

package/types/adapters/codex.d.mts

@@ -113,6 +113,17 @@ export const MIN_ENFORCING_VERSION: readonly number[];
  * @type {Record<string, string|undefined>}
  */
 export const NATIVE_EVENT_FOR: Record<string, string | undefined>;
+/**
+ * Codex has NO ask tier. Its pre-tool output parser decodes
+ * `permissionDecision: "ask"`, classifies it unsupported, sets no block reason
+ * and runs the tool — upstream's own unit test for that path is named
+ * `unsupported_permission_decision_fails_open` (read at `rust-v0.155.1`, and
+ * byte-identical at `rust-v0.151.0`). `PermissionRequest` is no ask tier either:
+ * its behavior enum carries allow and deny only. So a verdict of `ask` has no
+ * channel here, and {@link render} sends it down the deny path rather than
+ * naming a key the host discards.
+ */
+export const NATIVE_ASK_TIER: false;
 export const DEFAULT_DENY_REASON: "blocked by monitor";
 /** @type {import("../control-plane.mjs").Adapter} */
 export const codexAdapter: import("../control-plane.mjs").Adapter;

package/types/adapters/gemini.d.mts

@@ -117,6 +117,15 @@ export const NATIVE_EVENT_FOR: Record<string, string | undefined>;
  * @type {Readonly<Record<string, string>>}
  */
 export const GEMINI_TOOL_ALIASES: Readonly<Record<string, string>>;
+/**
+ * Gemini CLI has NO ask tier: its hook vocabulary is `decision: "allow"` /
+ * `decision: "deny"` plus the exit-2 System Block, and nothing there suspends a
+ * call for a human. {@link applyAdvisoryDeny} therefore renders `ask` as the
+ * advisory `decision: "deny"`, byte-identical to a deny this call cannot veto.
+ * A consumer that must not let an ask through has to escalate it to a deny
+ * here, because an un-escalated ask lets Gemini run the tool.
+ */
+export const NATIVE_ASK_TIER: false;
 /** @type {import("../control-plane.mjs").Adapter} */
 export const geminiAdapter: import("../control-plane.mjs").Adapter;
 export type ToolCallEvent = import("../control-plane.mjs").ToolCallEvent;

package/types/conformance.d.mts

@@ -1,3 +1,13 @@
+/**
+ * A field added to VERDICT_CONTENT_FIELDS with no probe value would be dropped
+ * by normalizeVerdict and then reported as "reaches no native channel" against
+ * every adapter, naming the adapter for the harness's own omission. Called at
+ * import against the live {@link CONTENT_PROBE_VALUES}; exported so a test can
+ * drive both branches.
+ * @param {readonly string[]} fields
+ * @param {Record<string, readonly unknown[]>} values
+ */
+export function assertContentProbeValuesComplete(fields: readonly string[], values: Record<string, readonly unknown[]>): void;
 /**
  * Assert an adapter's {@link import("./control-plane.mjs").Adapter.COVERAGE}
  * hook-coverage matrix is well-formed: it classifies EXACTLY the canonical
@@ -111,13 +121,23 @@ export function assertAliasedInputsCanonical(fixturesList: any[], assert: any):
  *      that DID reach a wire come back as `contentFieldsSeen`; a suite covering
  *      several adapters asserts their union to keep the positive half of the
  *      rule non-vacuous, since no single host has a channel for all three.
+ *  11. ask-tier honesty: the adapter declares whether this host carries a
+ *      distinct "ask the human" tier it honours (`NATIVE_ASK_TIER`), and the
+ *      render is held to that declaration on every pre-tool event. A declared
+ *      tier whose `ask` renders as the host's abstaining allow fails — the
+ *      consumer is told a human will see the call while the tool just runs —
+ *      and so does a declared-absent tier whose `ask` renders as anything but
+ *      the adapter's own advisory deny. A consumer reads the declaration to
+ *      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 ⑧.
  *
  * `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 }}
+ * @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 }}
  */
 export function runAdapterConformance({ adapter, fixtures, assert }: {
     adapter: import("./control-plane.mjs").Adapter;
@@ -134,4 +154,5 @@ export function runAdapterConformance({ adapter, fixtures, assert }: {
     unknownKindSeen: boolean;
     coverageClassesChecked: Set<string>;
     unenforceableDenyChecks: number;
+    askTierChecks: number;
 };