agent-control-plane-core 0.6.4 → 0.8.0

package/README.md

@@ -91,7 +91,8 @@ pnpm add agent-control-plane-core
 }
 ```
 
-An **Adapter** is `{ AGENT, COVERAGE, UNRENDERED_FIELDS, parse, render }`:
+An **Adapter** is
+`{ AGENT, COVERAGE, UNRENDERED_FIELDS, NATIVE_ASK_TIER, parse, render }`:
 
 ```js
 parse(nativeEvent) -> ToolCallEvent      // never throws on unknown input
@@ -110,6 +111,25 @@ UNRENDERED_FIELDS = Object.freeze({
 })
 ```
 
+```js
+// Does this host carry a distinct "ask the human" tier that it 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's advisory decision: "deny") and an un-escalated
+//         ask lets the tool run.
+NATIVE_ASK_TIER = false;
+```
+
+Read `NATIVE_ASK_TIER` instead of keeping a list of which agents to escalate an
+`ask` to a `deny` on: a guardrail that must not let an ask through escalates it
+where the flag is `false`, and leaves it alone where the host does the asking.
+It describes the HOST, not the verdict — `ask` renders as `enforced: false`
+everywhere — and it names the pre-tool gate, since a tool that already ran has
+nothing left to suspend. Conformance probes your real `render` against it, so a
+`true` whose ask renders as your abstaining allow fails, and so does a `false`
+whose ask renders as anything but your own advisory deny.
+
 `readonlySet([])` is the row for a kind that carries all three;
 `UNRENDERED_ON_UNKNOWN` is the row for one that carries none. Both come from
 `agent-control-plane-core/contract`. Build every row with `readonlySet` — a
@@ -138,6 +158,13 @@ const verdict =
 process.stdout.write(JSON.stringify(claudeAdapter.render(verdict, event)));
 ```
 
+Writing your own hook entry? `agent-control-plane-core/runtime` publishes the
+plumbing the four `bin/*-hook.mjs` entries share — `readStdin`,
+`renderHookResponse` (parse → judge → render, falling back to the failure
+response THAT host expects) and `emit`, whose fully-drained write is what stops
+a large deny body being truncated on a non-blocking pipe and silently becoming
+an allow.
+
 The core contract and every adapter (`claude`, `codex`, `amp`, `gemini`) are
 also on the default entry:
 
@@ -202,9 +229,49 @@ The harness pins both directions and rejects a vacuous suite:
    fixture event, so an adapter that collapses the objection onto "run it" fails
    even with no non-vetoable fixture of its own. `observe_only` renders are
    exempt: that transport has no pre-emption channel to differ in.
+6. Your `NATIVE_ASK_TIER` declaration matches what `render` does with an `ask`,
+   probed on every pre-tool fixture event (both directions, described above).
 
 See `src/fixtures/claude.json` and `src/fixtures/codex.json` for the format.
 
+## Validating from another language
+
+A guardrail that is not JavaScript cannot import `ToolCallEvent`, so it
+hand-writes the field names it reads. It then drifts in the quietest direction:
+the contract renames a field, the hand-written reader sees `undefined`, and it
+takes its no-value branch instead of failing. The package ships the same
+contract as JSON Schema (draft 2020-12), so that reader validates against the
+seam instead of against its own copy.
+
+```python
+import json, pathlib, jsonschema  # a Python guardrail reading the event
+base = pathlib.Path("node_modules/agent-control-plane-core/schema/control-plane/v1")
+schema = json.loads((base / "tool-call-event.schema.json").read_text())
+jsonschema.validate(event, schema)  # raises on a field the contract does not model
+```
+
+`tool-input-keys.json` sits beside them and publishes the input field a judge
+should read per canonical tool (`Bash` → `command`, `Read` → `file_path`), so a
+consumer looks that up rather than hard-coding it. It is plain data, not a
+schema: a validator refuses an unknown keyword under its default options, so a
+document carrying that map inside itself would not compile for the consumer who
+installed it.
+
+The event document also refuses two claims a producer must not make, each one a
+veto the host will never perform: a `this_call_vetoable` `unknown` event, and a
+`this_call_vetoable` event on an `observe_only` transport.
+
+`pnpm gen:schema` generates the files from `src/control-plane.mjs`, and
+`test/json-schema.test.mjs` byte-compares the result, so a stale document reds
+the suite. The same suite validates every adapter's live output against the
+published bytes, so a renamed contract field reds too. A JavaScript caller
+builds the documents in memory from `agent-control-plane-core/json-schema`
+instead of reading the files.
+
+Read the schema from the installed package rather than pinning a copy by hand. A
+document is one release's rendering of the wire version, and an added optional
+field (backward-compatible, below) appears in the next release's document.
+
 ## Versioning
 
 `src/control-plane.mjs` is the frozen contract and its own single source of
@@ -220,6 +287,7 @@ and bumps the version.
 pnpm test           # node --test
 pnpm test:coverage  # c8, 100% lines/branches/functions per file
 pnpm check          # tsc --noEmit (JSDoc types)
+pnpm gen:schema     # regenerate schema/ from the contract
 pnpm lint           # eslint
 pnpm build          # emit .d.mts declarations into types/
 ```

package/bin/amp-hook.mjs

@@ -13,7 +13,7 @@
  * Usage: `node bin/amp-hook.mjs < payload.json`
  */
 import { ampAdapter } from "../src/adapters/amp.mjs";
-import { readStdin, renderHookResponse, emit } from "./hook-runtime.mjs";
+import { readStdin, renderHookResponse, emit } from "../src/runtime.mjs";
 
 /** @type {import("../src/control-plane.mjs").NativeResponse} */
 const FAIL_ASK = { transport: "external_hook", exit_code: 1, enforced: false };

package/bin/claude-hook.mjs

@@ -12,7 +12,7 @@
  * Usage: `node bin/claude-hook.mjs < payload.json`
  */
 import { claudeAdapter } from "../src/adapters/claude.mjs";
-import { readStdin, renderHookResponse, emit } from "./hook-runtime.mjs";
+import { readStdin, renderHookResponse, emit } from "../src/runtime.mjs";
 
 /** @type {import("../src/control-plane.mjs").NativeResponse} */
 const FAIL_OPEN = { transport: "external_hook", exit_code: 0, enforced: false };

package/bin/codex-hook.mjs

@@ -13,7 +13,7 @@
  * Usage: `node bin/codex-hook.mjs < payload.json`
  */
 import { codexAdapter } from "../src/adapters/codex.mjs";
-import { readStdin, renderHookResponse, emit } from "./hook-runtime.mjs";
+import { readStdin, renderHookResponse, emit } from "../src/runtime.mjs";
 
 /** @type {import("../src/control-plane.mjs").NativeResponse} */
 const FAIL_OPEN = { transport: "external_hook", exit_code: 0, enforced: false };

package/bin/gemini-hook.mjs

@@ -11,7 +11,7 @@
  * Usage: `node bin/gemini-hook.mjs < payload.json`
  */
 import { geminiAdapter } from "../src/adapters/gemini.mjs";
-import { readStdin, renderHookResponse, emit } from "./hook-runtime.mjs";
+import { readStdin, renderHookResponse, emit } from "../src/runtime.mjs";
 
 /** @type {import("../src/control-plane.mjs").NativeResponse} */
 const FAIL_OPEN = { transport: "external_hook", exit_code: 0, enforced: false };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-control-plane-core",
-  "version": "0.6.4",
+  "version": "0.8.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": {
@@ -56,12 +56,21 @@
     "./registry": {
       "types": "./types/registry.d.mts",
       "import": "./src/registry.mjs"
+    },
+    "./runtime": {
+      "types": "./types/runtime.d.mts",
+      "import": "./src/runtime.mjs"
+    },
+    "./json-schema": {
+      "types": "./types/json-schema.d.mts",
+      "import": "./src/json-schema.mjs"
     }
   },
   "files": [
     "src",
     "types",
-    "bin"
+    "bin",
+    "schema"
   ],
   "keywords": [
     "claude",
@@ -113,6 +122,7 @@
     "@eslint/js": "^9.13.0",
     "@types/node": "^22.7.0",
     "@types/semver": "^7.5.8",
+    "ajv": "^8.20.0",
     "c8": "^10.1.2",
     "eslint": "^9.13.0",
     "fast-check": "^3.22.0",
@@ -123,6 +133,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
+    "gen:schema": "node scripts/gen-json-schema.mjs",
     "test": "node --test test/*.test.mjs",
     "test:coverage": "c8 node --test test/*.test.mjs",
     "check": "tsc --noEmit",

package/schema/control-plane/v1/tool-call-event.schema.json

@@ -0,0 +1,152 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "ToolCallEvent",
+  "description": "A normalized, agent-agnostic view of one agent event (control-plane/v1).",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "event",
+    "tool",
+    "input",
+    "this_call_vetoable",
+    "meta"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "event": {
+      "enum": [
+        "pre_tool",
+        "post_tool",
+        "prompt_submit",
+        "session_start",
+        "unknown"
+      ]
+    },
+    "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,
+  "allOf": [
+    {
+      "if": {
+        "required": [
+          "event"
+        ],
+        "properties": {
+          "event": {
+            "const": "unknown"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "this_call_vetoable": {
+            "const": false
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "required": [
+          "meta"
+        ],
+        "properties": {
+          "meta": {
+            "required": [
+              "integration_mode"
+            ],
+            "properties": {
+              "integration_mode": {
+                "const": "observe_only"
+              }
+            }
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "this_call_vetoable": {
+            "const": false
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "EventMeta": {
+      "type": "object",
+      "required": [
+        "agent",
+        "native_event",
+        "integration_mode",
+        "primary_gate_present",
+        "passthrough"
+      ],
+      "properties": {
+        "agent": {
+          "type": "string",
+          "description": "Producing agent id (\"claude\", \"codex\", …)."
+        },
+        "native_event": {
+          "type": "string",
+          "description": "Original native event name, preserved verbatim."
+        },
+        "integration_mode": {
+          "enum": [
+            "external_hook",
+            "in_process",
+            "observe_only"
+          ],
+          "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."
+        },
+        "session_id": {
+          "type": "string"
+        },
+        "cwd": {
+          "type": "string"
+        },
+        "permission_mode": {
+          "type": "string"
+        },
+        "transcript_path": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schema/control-plane/v1/tool-input-keys.json

@@ -0,0 +1,7 @@
+{
+  "Bash": "command",
+  "Edit": "file_path",
+  "Write": "file_path",
+  "Read": "file_path",
+  "WebFetch": "url"
+}

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

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Verdict",
+  "description": "A normalized guardrail decision (control-plane/v1).",
+  "type": "object",
+  "required": [
+    "decision"
+  ],
+  "properties": {
+    "decision": {
+      "enum": [
+        "allow",
+        "deny",
+        "ask"
+      ]
+    },
+    "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."
+    }
+  },
+  "additionalProperties": false
+}

package/src/adapters/amp.mjs

@@ -156,6 +156,15 @@ export function parse(native) {
   });
 }
 
+/**
+ * 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;
+
 /**
  * The EXHAUSTIVE (decision × `this_call_vetoable`) → exit-code table for Amp's
  * pure exit-code transport: 0 allow / 1 ask / 2 reject.
@@ -181,22 +190,52 @@ const EXIT_CODE_BY_DECISION = Object.freeze({
 });
 
 /**
- * Totality check at IMPORT: every {@link Decision} must have a row and every row
- * both vetoable columns. A decision added to the contract breaks this module
- * loudly at load instead of silently defaulting to exit 0.
+ * 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
  */
-for (const decision of Object.values(Decision)) {
-  const row = lookup(EXIT_CODE_BY_DECISION, decision);
-  if (row === undefined)
-    throw new Error(
-      `amp adapter: exit-code table has no row for decision ${JSON.stringify(decision)}`,
-    );
-  for (const vetoable of ["true", "false"]) {
-    if (typeof lookup(row, vetoable) === "number") continue;
+export function assertExitCodeTableTotal(decisions, table) {
+  for (const decision of decisions) {
+    const row = lookup(table, decision);
+    if (row === undefined)
+      throw new Error(
+        `amp adapter: exit-code table has no row for decision ${JSON.stringify(decision)}`,
+      );
+    for (const vetoable of ["true", "false"]) {
+      if (typeof lookup(row, vetoable) === "number") continue;
+      throw new Error(
+        `amp adapter: exit-code table row ${JSON.stringify(decision)} has no this_call_vetoable=${vetoable} column`,
+      );
+    }
+  }
+}
+
+assertExitCodeTableTotal(Object.values(Decision), EXIT_CODE_BY_DECISION);
+
+/**
+ * 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, decision, vetoable) {
+  const exit_code = lookup(lookup(table, decision) ?? {}, String(vetoable));
+  if (exit_code === undefined)
     throw new Error(
-      `amp adapter: exit-code table row ${JSON.stringify(decision)} has no this_call_vetoable=${vetoable} column`,
+      `amp adapter: exit-code table has no entry for decision ${JSON.stringify(decision)} / this_call_vetoable ${JSON.stringify(vetoable)}`,
     );
-  }
+  return exit_code;
 }
 
 /**
@@ -225,18 +264,7 @@ export function render(verdict, event) {
       `amp adapter: this_call_vetoable must be a boolean, got ${JSON.stringify(vetoable)}`,
     );
   const enforced = vd.decision === Decision.DENY && vetoable;
-  const exit_code = lookup(
-    lookup(EXIT_CODE_BY_DECISION, vd.decision) ?? {},
-    String(vetoable),
-  );
-  // Unreachable while the import-time totality check and `normalizeVerdict` both
-  // hold; kept because the alternative to throwing is `exit_code: undefined`,
-  // which `process.exit` renders as 0 — the exact silent allow this table exists
-  // to eliminate.
-  if (exit_code === undefined)
-    throw new Error(
-      `amp adapter: exit-code table has no entry for decision ${JSON.stringify(vd.decision)} / this_call_vetoable ${JSON.stringify(vetoable)}`,
-    );
+  const exit_code = exitCodeFor(EXIT_CODE_BY_DECISION, vd.decision, vetoable);
   return nativeResponse({
     transport: INTEGRATION_MODE,
     exit_code,
@@ -251,6 +279,7 @@ export const ampAdapter = {
   INTEGRATION_MODE,
   COVERAGE,
   UNRENDERED_FIELDS,
+  NATIVE_ASK_TIER,
   NATIVE_EVENT_FOR,
   parse,
   render,

package/src/adapters/claude.mjs

@@ -7,7 +7,8 @@
  * agent shells out with stdin JSON and reads a deny body / exit code back.
  *
  * Deny signal (PreToolUse): `hookSpecificOutput.permissionDecision = "deny"`
- * AND exit 2. this_call_vetoable is true, but per the doctrine that is a
+ * AND exit 2. Exit 2 discards stdout, so an enforced deny repeats its reason on
+ * STDERR, which is where the host reads a block rationale. this_call_vetoable is true, but per the doctrine that is a
  * useful FIRST filter, never the boundary — the Verdict stays advisory to the
  * sandbox.
  */
@@ -114,6 +115,16 @@ export const UNRENDERED_FIELDS = Object.freeze({
   [EventKind.UNKNOWN]: UNRENDERED_ON_UNKNOWN,
 });
 
+/**
+ * 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 = Object.freeze({
   PRE_TOOL_USE: "PreToolUse",
@@ -221,7 +232,8 @@ export function parse(native) {
  * 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
@@ -253,6 +265,15 @@ export function render(verdict, event, { soleGate = false } = {}) {
     exit_code: enforced ? 2 : 0,
     enforced,
     stdout,
+    // An ENFORCED deny exits 2, and Claude Code parses hook stdout as JSON only
+    // on exit 0: on an exit-2 PreToolUse block it discards the body and reads
+    // STDERR instead. So `permissionDecisionReason` never reached the model on
+    // the one path that actually blocks, and the call was refused with no
+    // rationale. Carry the reason on `NativeResponse.stderr`, which `emit`
+    // writes to fd 2 — the same block-reason channel the Amp and Gemini
+    // adapters use. ONLY the enforced path: an allow, an ask, and a deny this
+    // call cannot veto have blocked nothing, and their exit-0 body is read.
+    ...(enforced && vd.reason !== undefined ? { stderr: vd.reason } : {}),
   });
 }
 
@@ -318,6 +339,7 @@ export const claudeAdapter = {
   INTEGRATION_MODE,
   COVERAGE,
   UNRENDERED_FIELDS,
+  NATIVE_ASK_TIER,
   NATIVE_EVENT_FOR,
   parse,
   render,

package/src/adapters/codex.mjs

@@ -146,8 +146,9 @@ const HookEvent = Object.freeze({
 
 /**
  * Native event name → normalized {@link EventKind}. `PreToolUse` and
- * `PermissionRequest` both gate a tool call before it runs (PermissionRequest is
- * the ask-tier veto), so both normalize to `pre_tool`. Codex emits more events
+ * `PermissionRequest` both gate a tool call before it runs, so both normalize to
+ * `pre_tool`. Neither carries an ask tier: Codex's `PermissionRequestBehaviorWire`
+ * has two variants, allow and deny. Codex emits more events
  * than these — SessionStart/SessionEnd/Stop/PreCompact/… — and every one of them
  * still routes to `unknown`: this adapter models an event only once its host
  * response is established, and an unmodelled event parses non-vetoable.
@@ -171,6 +172,18 @@ export const NATIVE_EVENT_FOR = Object.freeze({
   [EventKind.POST_TOOL]: HookEvent.POST_TOOL_USE,
 });
 
+/**
+ * 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;
+
 // Codex drops an enforced deny that carries no (or an empty) reason and runs the
 // tool, so a reasonless enforced deny still renders a non-empty one.
 export const DEFAULT_DENY_REASON = "blocked by monitor";
@@ -303,7 +316,15 @@ export function parse(native) {
  * @returns {NativeResponse}
  */
 export function render(verdict, event, { soleGate = false } = {}) {
-  const vd = normalizeVerdict(verdict);
+  const normalized = normalizeVerdict(verdict);
+  // An `ask` becomes a deny on the PRE-TOOL path, because this host acts on no
+  // other objection: emitting its own `"ask"` leaves the tool running with the
+  // run marked failed, which is the fail-open {@link NATIVE_ASK_TIER} records.
+  // The post-tool path maps it to `block` on its own, below.
+  const vd =
+    normalized.decision === Decision.ASK && event.event !== EventKind.POST_TOOL
+      ? { ...normalized, decision: Decision.DENY }
+      : normalized;
   const enforced = vd.decision === Decision.DENY && event.this_call_vetoable;
   // The native name is preserved rather than derived from the kind, so a
   // PermissionRequest answers as itself; NATIVE_EVENT_FOR names the fallback.
@@ -392,6 +413,7 @@ export const codexAdapter = {
   INTEGRATION_MODE,
   COVERAGE,
   UNRENDERED_FIELDS,
+  NATIVE_ASK_TIER,
   NATIVE_EVENT_FOR,
   parse,
   render,

package/src/adapters/gemini.mjs

@@ -347,6 +347,16 @@ export function parse(native) {
   });
 }
 
+/**
+ * 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;
+
 /**
  * Render into Gemini CLI's native external-hook transport. An enforceable deny
  * renders as exit 2 (the System Block on BeforeTool; documented on BeforeAgent
@@ -470,6 +480,7 @@ export const geminiAdapter = {
   INTEGRATION_MODE,
   COVERAGE,
   UNRENDERED_FIELDS,
+  NATIVE_ASK_TIER,
   NATIVE_EVENT_FOR,
   parse,
   render,