agent-control-plane-core 0.6.3 → 0.7.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,6 +229,8 @@ 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.
 

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.3",
+  "version": "0.7.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,6 +56,10 @@
     "./registry": {
       "types": "./types/registry.d.mts",
       "import": "./src/registry.mjs"
+    },
+    "./runtime": {
+      "types": "./types/runtime.d.mts",
+      "import": "./src/runtime.mjs"
     }
   },
   "files": [

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.
@@ -251,6 +260,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,

package/src/conformance.mjs

@@ -22,6 +22,22 @@ const UNENFORCEABLE_DENY_PROBE = Object.freeze({
 });
 const ABSTAINING_ALLOW_PROBE = Object.freeze({ decision: Decision.ALLOW });
 
+/**
+ * The two probe verdicts rule ⑪ renders against the same event, to read whether
+ * this host's transport carries an ask tier of its own. They share one `reason`
+ * on purpose: the rule compares the two RENDERS, and a reason that differed
+ * would make them differ for a reason that is not the decision.
+ */
+const ASK_TIER_REASON = "conformance probe: ask tier";
+const ASK_TIER_ASK_PROBE = Object.freeze({
+  decision: Decision.ASK,
+  reason: ASK_TIER_REASON,
+});
+const ASK_TIER_DENY_PROBE = Object.freeze({
+  decision: Decision.DENY,
+  reason: ASK_TIER_REASON,
+});
+
 /**
  * The payload rule ⑨ drifts an adapter with. No host emits that event name, so
  * an adapter that maps event names must answer {@link EventKind.UNKNOWN}.
@@ -454,6 +470,78 @@ function coherentEvent(adapter, byKind, kind) {
   };
 }
 
+/**
+ * Rule ⑪, for one pre-tool event: the adapter's `NATIVE_ASK_TIER` declaration
+ * agrees with what `render` does with an `ask`.
+ *
+ * The declaration is what lets a consumer stop keeping a hand-typed list of
+ * which hosts honour an ask. A consumer that must not let an ask through
+ * escalates it to a deny on a host with no ask tier — and applying that
+ * uniformly turns every ask into a deny on the hosts that DO have one. So the
+ * declaration has to be checked against the render rather than believed.
+ *
+ * Probed on a NON-vetoable variant of the event, for rule ⑧'s reason and one
+ * more: it makes the deny comparison below an ADVISORY deny, which is the
+ * signal a host with no ask tier has left to spend on an ask.
+ *
+ * What a render can show, and what it cannot. Whether a host suspends the call
+ * for a human lives in the HOST, so no probe reads it off a render. What a probe
+ * does read is each direction's tell:
+ *
+ * - Declared `true`, rendered as the abstaining ALLOW: the consumer is told the
+ *   human will see this call, and the transport carries nothing that says so —
+ *   the tool just runs. That is the lie this rule exists to catch.
+ * - Declared `false`, rendered as something the adapter's own advisory deny is
+ *   not: the render invents a third signal on a transport the declaration says
+ *   has only two, so one of the two is wrong.
+ *
+ * An OBSERVE_ONLY render is exempt, as in rule ⑧: that transport has no
+ * pre-emption channel at all, so its ask, deny and allow coincide by
+ * construction and demanding a distinct ask would demand a fiction.
+ * @param {import("./control-plane.mjs").Adapter} adapter
+ * @param {import("./control-plane.mjs").ToolCallEvent} event a non-vetoable pre-tool event
+ * @param {import("./control-plane.mjs").ToolCallEvent} vetoable the fixture's own pre-tool event, whose veto the block half needs
+ * @param {string} caseName
+ * @param {any} assert
+ */
+function assertAskTier(adapter, event, vetoable, caseName, assert) {
+  const asked = adapter.render(ASK_TIER_ASK_PROBE, event);
+  assert.equal(
+    asked.enforced,
+    false,
+    `an ask rendered as an enforced block: ${caseName}`,
+  );
+  if (asked.transport === IntegrationMode.OBSERVE_ONLY) return;
+  if (adapter.NATIVE_ASK_TIER) {
+    assert.notDeepEqual(
+      asked,
+      adapter.render(ABSTAINING_ALLOW_PROBE, event),
+      `${adapter.AGENT}: NATIVE_ASK_TIER is true, but an ask renders exactly as this host's abstaining allow — nothing in the transport asks anyone: ${caseName}`,
+    );
+    // The other way to declare an ask tier this host has not got: render the ask
+    // as the host's BLOCK. It differs from the allow, so the half above passes,
+    // and the consumer it tells to stop escalating then hands a call to a host
+    // that denies it outright rather than suspending it for a human. Probed on
+    // the vetoable event, because a block is the one signal a non-vetoable
+    // render cannot carry.
+    if (vetoable.this_call_vetoable) {
+      const blocked = adapter.render(ASK_TIER_DENY_PROBE, vetoable);
+      if (blocked.enforced)
+        assert.notDeepEqual(
+          adapter.render(ASK_TIER_ASK_PROBE, vetoable),
+          blocked,
+          `${adapter.AGENT}: NATIVE_ASK_TIER is true, but an ask renders exactly as this host's enforced deny — the call is blocked, not suspended: ${caseName}`,
+        );
+    }
+    return;
+  }
+  assert.deepEqual(
+    asked,
+    adapter.render(ASK_TIER_DENY_PROBE, event),
+    `${adapter.AGENT}: NATIVE_ASK_TIER is false, but an ask renders differently from this host's advisory deny — the render carries an ask signal the declaration says the host has not got: ${caseName}`,
+  );
+}
+
 /**
  * Rule ⑩, for one parsed event: every {@link VERDICT_CONTENT_FIELDS} entry
  * either reaches this host's wire or is DECLARED unreachable in the adapter's
@@ -820,13 +908,23 @@ function assertAliasedInput(agent, caseName, event, assert) {
  *      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 }) {
   assert.equal(
@@ -837,6 +935,14 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
 
   assertCoverageWellFormed(adapter, assert);
   assertEveryKindHasARow(adapter, assert);
+  // Named here rather than left to a `TypeError` inside rule ⑪: a third-party
+  // adapter written against the earlier contract has no such member, and its
+  // author is who reads this.
+  assert.equal(
+    typeof adapter.NATIVE_ASK_TIER,
+    "boolean",
+    `${adapter.AGENT}: adapter declares no NATIVE_ASK_TIER — every adapter needs a boolean saying whether this host honours a distinct "ask the human" tier (false when render collapses ask onto another signal)`,
+  );
 
   /** @type {Set<string>} */
   const decisionsSeen = new Set();
@@ -852,6 +958,7 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
   const parsedByKind = {};
   let preToolCases = 0;
   let unenforceableDenyChecks = 0;
+  let askTierChecks = 0;
   let renders = 0;
 
   for (const testCase of fixtures.cases) {
@@ -991,12 +1098,17 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
     // An OBSERVE_ONLY render is exempt from the ≠-allow half: that transport has
     // no pre-emption channel at all, so its deny and allow are identical by
     // construction. Demanding a distinct signal there would demand a fiction.
-    if (deniedRender.transport === IntegrationMode.OBSERVE_ONLY) continue;
-    assert.notDeepEqual(
-      deniedRender,
-      adapter.render(ABSTAINING_ALLOW_PROBE, unenforceable),
-      `unenforceable deny renders identically to an abstaining allow — the objection is lost: ${testCase.name}`,
-    );
+    if (deniedRender.transport !== IntegrationMode.OBSERVE_ONLY)
+      assert.notDeepEqual(
+        deniedRender,
+        adapter.render(ABSTAINING_ALLOW_PROBE, unenforceable),
+        `unenforceable deny renders identically to an abstaining allow — the objection is lost: ${testCase.name}`,
+      );
+    // Rule ⑪, on the same non-vetoable variant and AFTER rule ⑧: an adapter that
+    // collapses both its deny and its ask onto the host's allow is reported as
+    // the lost objection it is, not as a mis-declared ask tier.
+    assertAskTier(adapter, unenforceable, parsed, testCase.name, assert);
+    askTierChecks += 1;
   }
 
   for (const decision of ["allow", "deny", "ask"]) {
@@ -1055,6 +1167,13 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
     preToolCases,
     `rule ⑧ (unenforceable deny ≠ allow) ran on ${unenforceableDenyChecks} of ${preToolCases} pre-tool cases`,
   );
+  // Same reason as the count above: the rule is in the same loop, so a stray
+  // `continue` would skip it silently on the later cases.
+  assert.equal(
+    askTierChecks,
+    preToolCases,
+    `rule ⑪ (ask-tier declaration) ran on ${askTierChecks} of ${preToolCases} pre-tool cases`,
+  );
 
   return {
     cases: fixtures.cases.length,
@@ -1067,5 +1186,6 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
     unknownKindSeen,
     coverageClassesChecked,
     unenforceableDenyChecks,
+    askTierChecks,
   };
 }

package/src/control-plane.mjs

@@ -38,9 +38,10 @@
  * {@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: adding it 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` 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.
  */
 
 /** Wire identifier for this schema version; bump on a breaking shape change. */
@@ -501,6 +502,7 @@ export const UNRENDERED_ON_UNKNOWN = readonlySet(VERDICT_CONTENT_FIELDS);
  * @property {(native: any) => ToolCallEvent} parse
  * @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 {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.
  */
 

package/src/fixtures/claude.json

@@ -67,7 +67,8 @@
                 "permissionDecision": "deny",
                 "permissionDecisionReason": "blocked rm"
               }
-            }
+            },
+            "stderr": "blocked rm"
           }
         },
         "ask": {
@@ -244,7 +245,8 @@
               },
               "decision": "block",
               "reason": "leak"
-            }
+            },
+            "stderr": "leak"
           }
         },
         "ask": {

package/src/fixtures/codex.json

@@ -109,12 +109,13 @@
           },
           "native": {
             "transport": "external_hook",
-            "exit_code": 0,
-            "enforced": false,
+            "exit_code": 2,
+            "enforced": true,
             "stdout": {
               "hookSpecificOutput": {
                 "hookEventName": "PreToolUse",
-                "permissionDecision": "ask"
+                "permissionDecision": "deny",
+                "permissionDecisionReason": "blocked by monitor"
               }
             }
           }
@@ -315,12 +316,13 @@
           },
           "native": {
             "transport": "external_hook",
-            "exit_code": 0,
-            "enforced": false,
+            "exit_code": 2,
+            "enforced": true,
             "stdout": {
               "hookSpecificOutput": {
                 "hookEventName": "PreToolUse",
-                "permissionDecision": "ask"
+                "permissionDecision": "deny",
+                "permissionDecisionReason": "blocked by monitor"
               }
             }
           }

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,
@@ -140,7 +158,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

@@ -72,6 +72,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

@@ -111,13 +111,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 +144,5 @@ export function runAdapterConformance({ adapter, fixtures, assert }: {
     unknownKindSeen: boolean;
     coverageClassesChecked: Set<string>;
     unenforceableDenyChecks: number;
+    askTierChecks: number;
 };

package/types/control-plane.d.mts

@@ -136,6 +136,7 @@ export function readonlySet(values: Iterable<string>): ReadonlySet<string>;
  * @property {(native: any) => ToolCallEvent} parse
  * @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 {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.
  */
 /**
@@ -293,9 +294,10 @@ export function nativeResponse({ transport, exit_code, enforced, stdout, stderr,
  * {@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: adding it 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` 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.
  */
 /** Wire identifier for this schema version; bump on a breaking shape change. */
 export const CONTROL_PLANE_SCHEMA: "control-plane/v1";
@@ -515,6 +517,10 @@ export type Adapter = {
      * 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`.
      */
     NATIVE_EVENT_FOR?: Record<string, string | undefined> | undefined;
+    /**
+     * 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;
     /**
      * 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.
      */

package/types/runtime.d.mts

@@ -0,0 +1,45 @@
+/**
+ * Read all of stdin to a string.
+ * @returns {Promise<string>}
+ */
+export function readStdin(): Promise<string>;
+/**
+ * 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("./control-plane.mjs").ToolCallEvent} event
+ * @returns {import("./control-plane.mjs").Verdict}
+ */
+export function demoJudge(event: import("./control-plane.mjs").ToolCallEvent): import("./control-plane.mjs").Verdict;
+/**
+ * Run one host's parse→judge→render pipe over a raw stdin payload. If the payload
+ * can't be parsed or the pipe throws, return `onFailure` — the host's OWN
+ * fail-safe response — so a crashed hook degrades the way THAT host expects
+ * (claude/codex fail OPEN = exit 0; amp fails to ASK = exit 1) instead of a
+ * single shared default. This is the deliberate, necessary recovery the whole
+ * per-host split exists for, not a blanket swallow.
+ *
+ * Before returning the fail-safe, the error is written to STDERR (never stdout,
+ * which belongs to the host transport) so a regression that silently disables
+ * enforcement leaves a 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 — none of
+ * these fail-safe exits is a 2 for a stdout-carrying transport, and amp's ask
+ * (exit 1) shows the diagnostic alongside the prompt, which is the point.
+ * `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("./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}
+ */
+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;
+/**
+ * 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("./control-plane.mjs").NativeResponse} response
+ * @returns {never}
+ */
+export function emit(response: import("./control-plane.mjs").NativeResponse): never;