agent-control-plane-core 0.4.2 → 0.5.0

package/README.md

@@ -167,6 +167,12 @@ The harness pins both directions and rejects a vacuous suite:
 3. The fixture set collectively renders an `allow`, a `deny`, an `ask`, **and** a
    `mutated_input` — so a suite can't pass while skipping a decision the contract
    requires every adapter to express.
+4. A deny the adapter cannot enforce (`this_call_vetoable: false`) must render as
+   something OTHER than that host's allow signal — an ask, or an advisory body.
+   The harness probes this itself on a non-vetoable variant of every pre-tool
+   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.
 
 See `src/fixtures/claude.json` and `src/fixtures/codex.json` for the format.
 

package/bin/hook-runtime.mjs

@@ -95,6 +95,48 @@ export function renderHookResponse(
   }
 }
 
+/**
+ * A one-millisecond synchronous sleep buffer for the EAGAIN retry in
+ * {@link writeAllSync}. Allocated once at module scope: the retry path must not
+ * allocate per iteration while it is draining a full pipe.
+ */
+const RETRY_SLEEP = new Int32Array(new SharedArrayBuffer(4));
+
+/**
+ * Write `text` to `fd` IN FULL, looping until every byte lands.
+ *
+ * A single `writeSync` is not enough. When the host captures the hook, fd 1/2 is
+ * a pipe, and libuv puts that pipe in NON-BLOCKING mode the moment anything
+ * initializes `process.stdout`/`process.stderr` (a `console.log` in a judge, the
+ * fail-safe stderr diagnostic in {@link renderHookResponse}). A non-blocking
+ * `write(2)` returns a SHORT COUNT once the kernel pipe buffer fills — measured
+ * at ~143 KiB here — so a deny body larger than that (a long `reason`, a big
+ * `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.
+ * @param {number} fd
+ * @param {string} text
+ */
+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;
+      Atomics.wait(RETRY_SLEEP, 0, 0, 1);
+    }
+  }
+}
+
 /**
  * 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.
@@ -102,18 +144,18 @@ export function renderHookResponse(
  * @returns {never}
  */
 export function emit(response) {
-  // `writeSync` (not `process.stdout.write`) so the body is flushed to fd 1
+  // `writeAllSync` (not `process.stdout.write`) so the body is flushed to fd 1
   // BEFORE `process.exit`. On a pipe — which stdout is when the host captures the
   // hook — `process.stdout.write` is asynchronous and `process.exit` does not
   // drain it, so an enforced-deny body (Claude/Codex `hookSpecificOutput`) could
   // be truncated; the host then reads a block-less exit and runs the tool. A
-  // synchronous write closes that silent deny→allow window.
+  // synchronous, fully-drained write closes that silent deny→allow window.
   if (response.stdout !== undefined)
-    writeSync(1, JSON.stringify(response.stdout));
+    writeAllSync(1, JSON.stringify(response.stdout));
   // A host that reads the block reason from STDERR (Gemini's exit-2 System Block)
   // gets it here — written synchronously to fd 2 before exit, for the same
   // flush-before-exit reason as stdout above, so an enforced deny is never shown
   // with no rationale.
-  if (response.stderr !== undefined) writeSync(2, response.stderr);
+  if (response.stderr !== undefined) writeAllSync(2, response.stderr);
   process.exit(response.exit_code);
 }

package/package.json

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

package/src/adapters/amp.mjs

@@ -18,8 +18,10 @@ import {
   CallClass,
   CoverageStatus,
   classifyCallClass,
-  coverageAllowsVeto,
+  vetoableFor,
+  assertGatedKinds,
   canonicalTool,
+  lookup,
   makeEvent,
   normalizeVerdict,
   nativeResponse,
@@ -52,6 +54,14 @@ export const COVERAGE = Object.freeze({
   [CallClass.RESUMED]: CoverageStatus.UNKNOWN,
 });
 
+/**
+ * The event kinds this host can actually gate. Amp invokes the delegate for a tool call and nothing else, so parse only ever emits PRE_TOOL.
+ * A kind absent here parses non-vetoable, so an unmodelled event never renders as
+ * an enforced block the host will not perform.
+ */
+export const GATED_EVENTS = Object.freeze(new Set([EventKind.PRE_TOOL]));
+assertGatedKinds(GATED_EVENTS, AGENT);
+
 // Amp invokes the delegate for a tool call; the payload carries the tool name +
 // input and the session context. Pinned by fixtures/amp.json.
 const CONSUMED = new Set(["tool", "input", "session_id", "cwd"]);
@@ -80,13 +90,58 @@ export function parse(native) {
     input: asObject(raw.input),
     response: undefined,
     // Classify on the NATIVE name (MCP detection keys on `mcp__…`).
-    this_call_vetoable: coverageAllowsVeto(
+    this_call_vetoable: vetoableFor(
+      EventKind.PRE_TOOL,
+      GATED_EVENTS,
       COVERAGE[classifyCallClass(nativeTool, raw)],
     ),
     meta,
   });
 }
 
+/**
+ * The EXHAUSTIVE (decision × `this_call_vetoable`) → exit-code table for Amp's
+ * pure exit-code transport: 0 allow / 1 ask / 2 reject.
+ *
+ * Written as a total table rather than a ternary chain because the chain's
+ * fall-through case was ALLOW: an unenforceable deny — a deny on a call this
+ * guardrail cannot veto — silently rendered as exit 0, Amp's "run it". A
+ * combination this table forgets is a construction error (below), not a silent
+ * approval.
+ *
+ * The non-vetoable DENY row is exit 1 (ask), not 0. Amp has a real ask tier, so
+ * the honest render of "I object but cannot block" is to put the call in front
+ * of the human rather than wave it through. It is still `enforced: false` — the
+ * guardrail is not claiming a veto it does not have; it is declining to spend
+ * its one remaining signal on an approval.
+ *
+ * @type {Readonly<Record<string, Readonly<Record<string, number>>>>}
+ */
+const EXIT_CODE_BY_DECISION = Object.freeze({
+  [Decision.ALLOW]: Object.freeze({ true: 0, false: 0 }),
+  [Decision.DENY]: Object.freeze({ true: 2, false: 1 }),
+  [Decision.ASK]: Object.freeze({ true: 1, false: 1 }),
+});
+
+/**
+ * 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.
+ */
+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;
+    throw new Error(
+      `amp adapter: exit-code table row ${JSON.stringify(decision)} has no this_call_vetoable=${vetoable} column`,
+    );
+  }
+}
+
 /**
  * Render into Amp's pure exit-code transport: the decision is the exit code,
  * with no stdout body. `reason` has no native channel here, so it is dropped
@@ -99,8 +154,28 @@ export function parse(native) {
  */
 export function render(verdict, event) {
   const vd = normalizeVerdict(verdict);
-  const enforced = vd.decision === Decision.DENY && event.this_call_vetoable;
-  const exit_code = enforced ? 2 : vd.decision === Decision.ASK ? 1 : 0;
+  const vetoable = event.this_call_vetoable;
+  // `makeEvent` already rejects a non-boolean, so reaching this means a
+  // hand-built event — and guessing whether it can be vetoed is how fail-open
+  // starts. The string "true" is the case that makes this a real check rather
+  // than a formality: it would otherwise index the vetoable column.
+  if (typeof vetoable !== "boolean")
+    throw new Error(
+      `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)}`,
+    );
   return nativeResponse({ transport: INTEGRATION_MODE, exit_code, enforced });
 }
 

package/src/adapters/claude.mjs

@@ -19,7 +19,8 @@ import {
   CallClass,
   CoverageStatus,
   classifyCallClass,
-  coverageAllowsVeto,
+  vetoableFor,
+  assertGatedKinds,
   canonicalTool,
   lookup,
   makeEvent,
@@ -57,6 +58,18 @@ export const COVERAGE = Object.freeze({
   [CallClass.RESUMED]: CoverageStatus.COVERED,
 });
 
+/**
+ * The event kinds this host can actually gate. Claude Code honours a deny on these three. SESSION_START is left out: exit 2 does
+ * not abort a session start, and the matrix documents no host response for it — an
+ * undocumented kind is fail-closed to non-vetoable, the same rule coverage uses.
+ * A kind absent here parses non-vetoable, so an unmodelled event never renders as
+ * an enforced block the host will not perform.
+ */
+export const GATED_EVENTS = Object.freeze(
+  new Set([EventKind.PRE_TOOL, EventKind.POST_TOOL, EventKind.PROMPT_SUBMIT]),
+);
+assertGatedKinds(GATED_EVENTS, AGENT);
+
 /** Claude Code native hook event names (the `hook_event_name` field). */
 export const HookEvent = Object.freeze({
   PRE_TOOL_USE: "PreToolUse",
@@ -162,7 +175,9 @@ export function parse(native) {
     response,
     // Classify on the NATIVE name — MCP detection keys on `mcp__…`, which a
     // canonical builtin name would never carry.
-    this_call_vetoable: coverageAllowsVeto(
+    this_call_vetoable: vetoableFor(
+      kind,
+      GATED_EVENTS,
       COVERAGE[classifyCallClass(nativeTool, raw)],
     ),
     meta,

package/src/adapters/codex.mjs

@@ -20,7 +20,8 @@ import {
   CallClass,
   CoverageStatus,
   classifyCallClass,
-  coverageAllowsVeto,
+  vetoableFor,
+  assertGatedKinds,
   canonicalTool,
   makeEvent,
   normalizeVerdict,
@@ -54,6 +55,15 @@ export const COVERAGE = Object.freeze({
   [CallClass.RESUMED]: CoverageStatus.UNKNOWN,
 });
 
+/**
+ * The event kinds this host can actually gate. `PreToolUse` is the one event Codex can veto. Every other native event parses as
+ * UNKNOWN today, so without this set each of them reported an enforced block.
+ * A kind absent here parses non-vetoable, so an unmodelled event never renders as
+ * an enforced block the host will not perform.
+ */
+export const GATED_EVENTS = Object.freeze(new Set([EventKind.PRE_TOOL]));
+assertGatedKinds(GATED_EVENTS, AGENT);
+
 /** Minimum Codex version whose hook can actually veto a tool call. */
 export const MIN_ENFORCING_VERSION = Object.freeze([0, 135]);
 
@@ -140,7 +150,12 @@ export function parse(native) {
   const nativeTool = asStringOrNull(raw.tool_name);
   if (nativeTool !== null) meta.native_tool = nativeTool;
   const vetoable =
-    enforce && coverageAllowsVeto(COVERAGE[classifyCallClass(nativeTool, raw)]);
+    enforce &&
+    vetoableFor(
+      kind,
+      GATED_EVENTS,
+      COVERAGE[classifyCallClass(nativeTool, raw)],
+    );
 
   return makeEvent({
     event: kind,

package/src/adapters/gemini.mjs

@@ -35,7 +35,8 @@ import {
   CallClass,
   CoverageStatus,
   classifyCallClass,
-  coverageAllowsVeto,
+  vetoableFor,
+  assertGatedKinds,
   canonicalTool,
   lookup,
   assertAliasTargetsModeled,
@@ -72,6 +73,16 @@ export const COVERAGE = Object.freeze({
   [CallClass.RESUMED]: CoverageStatus.UNKNOWN,
 });
 
+/**
+ * The event kinds this host can actually gate. Gemini CLI honours a deny on each of the three events NATIVE_TO_KIND maps.
+ * A kind absent here parses non-vetoable, so an unmodelled event never renders as
+ * an enforced block the host will not perform.
+ */
+export const GATED_EVENTS = Object.freeze(
+  new Set([EventKind.PRE_TOOL, EventKind.POST_TOOL, EventKind.PROMPT_SUBMIT]),
+);
+assertGatedKinds(GATED_EVENTS, AGENT);
+
 /** Gemini CLI native hook event names (the `hook_event_name` field). */
 export const HookEvent = Object.freeze({
   BEFORE_TOOL: "BeforeTool",
@@ -236,7 +247,7 @@ export function parse(native) {
     tool: geminiCanonicalTool(nativeTool, callClass),
     input: geminiInput(kind, raw, nativeTool, callClass),
     response,
-    this_call_vetoable: coverageAllowsVeto(COVERAGE[callClass]),
+    this_call_vetoable: vetoableFor(kind, GATED_EVENTS, COVERAGE[callClass]),
     meta,
   });
 }

package/src/conformance.mjs

@@ -1,5 +1,8 @@
 import {
   CALL_CLASSES,
+  Decision,
+  EventKind,
+  IntegrationMode,
   MODELED_TOOL_INPUT_KEYS,
   TOOL_ALIASES,
   canonicalTool,
@@ -8,6 +11,22 @@ import {
   lookup,
 } from "./control-plane.mjs";
 
+/**
+ * The two probe verdicts rule ⑧ renders against a non-vetoable variant of each
+ * pre-tool fixture event. Frozen so a mutating adapter cannot poison later cases.
+ */
+const UNENFORCEABLE_DENY_PROBE = Object.freeze({
+  decision: Decision.DENY,
+  reason: "conformance probe: unenforceable deny",
+});
+const ABSTAINING_ALLOW_PROBE = Object.freeze({ decision: Decision.ALLOW });
+
+/**
+ * The native event name rule ⑨ drifts an adapter with. No host emits it, so an
+ * adapter that maps event names must answer {@link EventKind.UNKNOWN} for it.
+ */
+const UNMODELLED_EVENT_NAME = "ConformanceProbeUnmodelledEvent";
+
 /**
  * Assert an adapter's {@link import("./control-plane.mjs").Adapter.COVERAGE}
  * hook-coverage matrix is well-formed: it classifies EXACTLY the canonical
@@ -66,14 +85,17 @@ export function assertToolAliasesCovered(
     let witnessed = witnessedByAgent.get(fixtures.agent);
     if (witnessed === undefined)
       witnessedByAgent.set(fixtures.agent, (witnessed = new Map()));
-    const scopedMap = adapterAliases[fixtures.agent] ?? {};
+    // `fixtures.agent` and the native tool names below are ADAPTER-SUPPLIED
+    // strings; a bare index would resolve `constructor`/`__proto__` to an
+    // inherited Object.prototype member instead of missing. See `lookup`.
+    const scopedMap = lookup(adapterAliases, fixtures.agent) ?? {};
     for (const testCase of fixtures.cases) {
       const nativeTool = testCase.event?.meta?.native_tool;
       if (typeof nativeTool !== "string") continue;
       const canon = testCase.event.tool;
       const allowed = new Set([canonicalTool(nativeTool)]);
-      if (scopedMap[nativeTool] !== undefined)
-        allowed.add(scopedMap[nativeTool]);
+      const scopedTarget = lookup(scopedMap, nativeTool);
+      if (scopedTarget !== undefined) allowed.add(scopedTarget);
       assert.ok(
         allowed.has(canon),
         `fixture '${testCase.name}' (${fixtures.agent}): native_tool ${JSON.stringify(nativeTool)} normalized to ${JSON.stringify(canon)}, but only ${JSON.stringify([...allowed])} are valid canonicalizations for this agent`,
@@ -195,13 +217,21 @@ function assertAliasedInput(agent, caseName, event, assert) {
  *      permit a veto (uncovered/unknown — an ❓ is treated as ❌) MUST parse to
  *      `this_call_vetoable: false`. An adapter cannot claim a class is un-gated
  *      while parsing its calls as vetoable.
+ *   8. unenforceable deny ≠ allow: for every pre-tool fixture event, rendering a
+ *      DENY over a non-vetoable variant of that event must produce a response
+ *      that differs from the same adapter's abstaining `allow` render. Rule ⑤
+ *      only says such a deny is not `enforced`; without this, an adapter is free
+ *      to collapse it onto the host's literal "run it" signal (Amp's exit 0),
+ *      throwing away the objection entirely. The strongest honest signal a
+ *      transport has left — an ask, an advisory body — must survive. An
+ *      OBSERVE_ONLY render is exempt: it has no pre-emption channel to differ in.
  *
  * `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, enforcedDenySeen: boolean, vetoableDenySeen: boolean, coverageClassesChecked: Set<string> }}
+ * @returns {{ cases: number, renders: number, decisionsSeen: Set<string>, mutationSeen: boolean, enforcedDenySeen: boolean, vetoableDenySeen: boolean, unknownKindSeen: boolean, coverageClassesChecked: Set<string>, unenforceableDenyChecks: number }}
  */
 export function runAdapterConformance({ adapter, fixtures, assert }) {
   assert.equal(
@@ -219,6 +249,9 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
   let mutationSeen = false;
   let enforcedDenySeen = false;
   let vetoableDenySeen = false;
+  let unknownKindSeen = false;
+  let preToolCases = 0;
+  let unenforceableDenyChecks = 0;
   let renders = 0;
 
   for (const testCase of fixtures.cases) {
@@ -234,16 +267,32 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
     // a rename-without-its-input land by editing the expectation.
     assertAliasedInput(adapter.AGENT, testCase.name, parsed, assert);
 
+    // An event the adapter could not name is one whose host response nobody has
+    // established, so claiming a veto for it is the one error that lies to a
+    // guardrail: the transcript shows a block and the host runs the tool anyway.
+    if (parsed.event === EventKind.UNKNOWN) {
+      assert.equal(
+        parsed.this_call_vetoable,
+        false,
+        `unmodelled event parsed as vetoable: ${testCase.name}`,
+      );
+      unknownKindSeen = true;
+    }
+
     if (testCase.call_class !== undefined) {
       assert.ok(
         CALL_CLASSES.includes(testCase.call_class),
         `unknown call_class '${testCase.call_class}': ${testCase.name}`,
       );
-      if (!coverageAllowsVeto(adapter.COVERAGE[testCase.call_class])) {
+      // Fixture-supplied key ⇒ prototype-safe read (see `lookup`): a
+      // `call_class` naming an Object.prototype member must MISS, not resolve a
+      // function that `coverageAllowsVeto` would then reject or accept by luck.
+      const coverage = lookup(adapter.COVERAGE, testCase.call_class);
+      if (!coverageAllowsVeto(coverage)) {
         assert.equal(
           parsed.this_call_vetoable,
           false,
-          `call_class '${testCase.call_class}' is ${adapter.COVERAGE[testCase.call_class]} (no veto) but parsed this_call_vetoable !== false: ${testCase.name}`,
+          `call_class '${testCase.call_class}' is ${coverage} (no veto) but parsed this_call_vetoable !== false: ${testCase.name}`,
         );
       }
       coverageClassesChecked.add(testCase.call_class);
@@ -307,6 +356,38 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
       if (spec.verdict.mutated_input !== undefined) mutationSeen = true;
       renders += 1;
     }
+
+    // Rule ⑧, probed on a synthesized non-vetoable variant rather than on a
+    // fixture flag: an adapter whose COVERAGE marks every reachable call class
+    // as gated can never PARSE a non-vetoable event, so a fixture-driven check
+    // would sit vacuous on exactly the adapters this rule exists for. Only
+    // pre-tool events are probed — a post-tool/prompt event has no veto to lose,
+    // so its deny and allow renders may legitimately coincide.
+    if (parsed.event !== EventKind.PRE_TOOL) continue;
+    preToolCases += 1;
+    const unenforceable = { ...parsed, this_call_vetoable: false };
+    const deniedRender = adapter.render(
+      UNENFORCEABLE_DENY_PROBE,
+      unenforceable,
+    );
+    assert.equal(
+      deniedRender.enforced,
+      false,
+      `unenforceable deny rendered as enforced: ${testCase.name}`,
+    );
+    // Counted before the OBSERVE_ONLY exemption: the honesty half above ran, so
+    // an adapter whose every pre-tool case is observe-only has still been
+    // checked and must not fail the non-vacuity assertion below.
+    unenforceableDenyChecks += 1;
+    // 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}`,
+    );
   }
 
   for (const decision of ["allow", "deny", "ask"]) {
@@ -323,7 +404,34 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
     enforcedDenySeen,
     "no enforced deny rendered — enforcement honesty is untested",
   );
+  // Rule ⑨, probed on a synthesized payload rather than a fixture flag: an
+  // adapter whose parse can never emit UNKNOWN — amp routes every payload to
+  // pre_tool — has no such fixture to write, so a fixture-driven check would sit
+  // vacuous on exactly the adapters this rule covers.
+  const drifted = adapter.parse({ hook_event_name: UNMODELLED_EVENT_NAME });
+  if (drifted.event === EventKind.UNKNOWN) {
+    assert.equal(
+      drifted.this_call_vetoable,
+      false,
+      "an unmodelled event parsed as vetoable",
+    );
+    assert.equal(
+      adapter.render(UNENFORCEABLE_DENY_PROBE, drifted).enforced,
+      false,
+      "a deny on an unmodelled event rendered as an enforced block",
+    );
+    unknownKindSeen = true;
+  }
   assert.ok(renders > 0, "conformance fixtures render nothing");
+  // EVERY pre-tool case, not merely one: the count is what catches rule ⑧ being
+  // skipped by a stray `continue` rather than merely present somewhere. A suite
+  // with no pre-tool case has no veto surface to lose, and rule ⑤'s own
+  // `vetoableDenySeen` guard already forces enforcement honesty there.
+  assert.equal(
+    unenforceableDenyChecks,
+    preToolCases,
+    `rule ⑧ (unenforceable deny ≠ allow) ran on ${unenforceableDenyChecks} of ${preToolCases} pre-tool cases`,
+  );
 
   return {
     cases: fixtures.cases.length,
@@ -332,6 +440,8 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
     mutationSeen,
     enforcedDenySeen,
     vetoableDenySeen,
+    unknownKindSeen,
     coverageClassesChecked,
+    unenforceableDenyChecks,
   };
 }

package/src/control-plane.mjs

@@ -242,11 +242,15 @@ const COVERAGE_STATUS_VALUES = new Set(Object.values(CoverageStatus));
  * forbid it — an unknown is fail-closed to uncovered, which is the whole point
  * of the matrix. Throws on an unrecognized status (fail loud — a typo must not
  * quietly read as "permitted").
- * @param {string} status a {@link CoverageStatus} value
+ *
+ * `undefined` is accepted as an INPUT type — that is what a prototype-safe
+ * `lookup` of a missing key yields — and takes the same throw: a coverage a
+ * caller could not resolve must never read as "permitted" either.
+ * @param {string|undefined} status a {@link CoverageStatus} value
  * @returns {boolean}
  */
 export function coverageAllowsVeto(status) {
-  if (!COVERAGE_STATUS_VALUES.has(status)) {
+  if (!COVERAGE_STATUS_VALUES.has(/** @type {string} */ (status))) {
     throw new Error(
       `control-plane: invalid coverage status ${JSON.stringify(status)}`,
     );
@@ -254,6 +258,52 @@ export function coverageAllowsVeto(status) {
   return status === CoverageStatus.COVERED || status === CoverageStatus.PARTIAL;
 }
 
+/**
+ * The event kinds a host can gate at all. {@link EventKind.UNKNOWN} is absent by
+ * construction, and that absence is the point: an event this package could not
+ * name is one whose host response nobody has established.
+ */
+/** @type {Set<string>} */
+const GATEABLE_KINDS = new Set([
+  EventKind.PRE_TOOL,
+  EventKind.POST_TOOL,
+  EventKind.PROMPT_SUBMIT,
+  EventKind.SESSION_START,
+]);
+
+/**
+ * Whether an event may be marked `this_call_vetoable`.
+ *
+ * INVARIANT: an event whose kind the adapter's `GATED_EVENTS` does not name is
+ * never vetoable, whatever its coverage says. Coverage answers whether the
+ * host's hook fires for a CLASS of call and says nothing about a kind the
+ * adapter could not model — so keying on coverage alone reported an enforced
+ * block for every unmodelled event, which is the one direction that lies to a
+ * guardrail: the transcript shows a block and the host runs the tool.
+ * @param {string} kind an {@link EventKind} value
+ * @param {Set<string>} gatedKinds the adapter's own gated set
+ * @param {string|undefined} coverage a {@link CoverageStatus} value
+ * @returns {boolean}
+ */
+export function vetoableFor(kind, gatedKinds, coverage) {
+  if (!gatedKinds.has(kind)) return false;
+  return coverageAllowsVeto(coverage);
+}
+
+/**
+ * Refuse a gated-kind set naming a kind no host can gate. Called at module load
+ * by each adapter, so `EventKind.UNKNOWN` cannot be added to one by hand.
+ * @param {Set<string>} kinds an adapter's `GATED_EVENTS`
+ * @param {string} agent the adapter's agent id, for the message
+ */
+export function assertGatedKinds(kinds, agent) {
+  for (const kind of kinds)
+    if (!GATEABLE_KINDS.has(kind))
+      throw new Error(
+        `${agent} adapter: ${JSON.stringify(kind)} is not a gateable event kind`,
+      );
+}
+
 /**
  * True when `status` is a recognized {@link CoverageStatus} value.
  * @param {unknown} status

package/src/fixtures/claude.json

@@ -318,7 +318,7 @@
         "event": "session_start",
         "tool": null,
         "input": {},
-        "this_call_vetoable": true,
+        "this_call_vetoable": false,
         "meta": {
           "agent": "claude",
           "native_event": "SessionStart",
@@ -344,6 +344,24 @@
               }
             }
           }
+        },
+        "deny": {
+          "verdict": {
+            "decision": "deny",
+            "reason": "not a gateable event"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false,
+            "stdout": {
+              "hookSpecificOutput": {
+                "hookEventName": "SessionStart"
+              },
+              "decision": "block",
+              "reason": "not a gateable event"
+            }
+          }
         }
       }
     }

package/types/adapters/amp.d.mts

@@ -30,6 +30,12 @@ export const INTEGRATION_MODE: "external_hook";
  */
 /** @type {import("../control-plane.mjs").CoverageMap} */
 export const COVERAGE: import("../control-plane.mjs").CoverageMap;
+/**
+ * The event kinds this host can actually gate. Amp invokes the delegate for a tool call and nothing else, so parse only ever emits PRE_TOOL.
+ * A kind absent here parses non-vetoable, so an unmodelled event never renders as
+ * an enforced block the host will not perform.
+ */
+export const GATED_EVENTS: Readonly<Set<"pre_tool">>;
 /** @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

@@ -41,6 +41,14 @@ export const INTEGRATION_MODE: "external_hook";
  */
 /** @type {import("../control-plane.mjs").CoverageMap} */
 export const COVERAGE: import("../control-plane.mjs").CoverageMap;
+/**
+ * The event kinds this host can actually gate. Claude Code honours a deny on these three. SESSION_START is left out: exit 2 does
+ * not abort a session start, and the matrix documents no host response for it — an
+ * undocumented kind is fail-closed to non-vetoable, the same rule coverage uses.
+ * A kind absent here parses non-vetoable, so an unmodelled event never renders as
+ * an enforced block the host will not perform.
+ */
+export const GATED_EVENTS: Readonly<Set<"pre_tool" | "post_tool" | "prompt_submit">>;
 /** 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

@@ -59,6 +59,13 @@ export const INTEGRATION_MODE: "external_hook";
  */
 /** @type {import("../control-plane.mjs").CoverageMap} */
 export const COVERAGE: import("../control-plane.mjs").CoverageMap;
+/**
+ * The event kinds this host can actually gate. `PreToolUse` is the one event Codex can veto. Every other native event parses as
+ * UNKNOWN today, so without this set each of them reported an enforced block.
+ * A kind absent here parses non-vetoable, so an unmodelled event never renders as
+ * an enforced block the host will not perform.
+ */
+export const GATED_EVENTS: Readonly<Set<"pre_tool">>;
 /** Minimum Codex version whose hook can actually veto a tool call. */
 export const MIN_ENFORCING_VERSION: readonly number[];
 export const DEFAULT_DENY_REASON: "blocked by monitor";

package/types/adapters/gemini.d.mts

@@ -43,6 +43,12 @@ export const INTEGRATION_MODE: "external_hook";
  */
 /** @type {import("../control-plane.mjs").CoverageMap} */
 export const COVERAGE: import("../control-plane.mjs").CoverageMap;
+/**
+ * The event kinds this host can actually gate. Gemini CLI honours a deny on each of the three events NATIVE_TO_KIND maps.
+ * A kind absent here parses non-vetoable, so an unmodelled event never renders as
+ * an enforced block the host will not perform.
+ */
+export const GATED_EVENTS: Readonly<Set<"pre_tool" | "post_tool" | "prompt_submit">>;
 /** Gemini CLI native hook event names (the `hook_event_name` field). */
 export const HookEvent: Readonly<{
     BEFORE_TOOL: "BeforeTool";

package/types/conformance.d.mts

@@ -89,13 +89,21 @@ export function assertAliasedInputsCanonical(fixturesList: any[], assert: any):
  *      permit a veto (uncovered/unknown — an ❓ is treated as ❌) MUST parse to
  *      `this_call_vetoable: false`. An adapter cannot claim a class is un-gated
  *      while parsing its calls as vetoable.
+ *   8. unenforceable deny ≠ allow: for every pre-tool fixture event, rendering a
+ *      DENY over a non-vetoable variant of that event must produce a response
+ *      that differs from the same adapter's abstaining `allow` render. Rule ⑤
+ *      only says such a deny is not `enforced`; without this, an adapter is free
+ *      to collapse it onto the host's literal "run it" signal (Amp's exit 0),
+ *      throwing away the objection entirely. The strongest honest signal a
+ *      transport has left — an ask, an advisory body — must survive. An
+ *      OBSERVE_ONLY render is exempt: it has no pre-emption channel to differ in.
  *
  * `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, enforcedDenySeen: boolean, vetoableDenySeen: boolean, coverageClassesChecked: Set<string> }}
+ * @returns {{ cases: number, renders: number, decisionsSeen: Set<string>, mutationSeen: boolean, enforcedDenySeen: boolean, vetoableDenySeen: boolean, unknownKindSeen: boolean, coverageClassesChecked: Set<string>, unenforceableDenyChecks: number }}
  */
 export function runAdapterConformance({ adapter, fixtures, assert }: {
     adapter: import("./control-plane.mjs").Adapter;
@@ -108,5 +116,7 @@ export function runAdapterConformance({ adapter, fixtures, assert }: {
     mutationSeen: boolean;
     enforcedDenySeen: boolean;
     vetoableDenySeen: boolean;
+    unknownKindSeen: boolean;
     coverageClassesChecked: Set<string>;
+    unenforceableDenyChecks: number;
 };

package/types/control-plane.d.mts

@@ -38,10 +38,36 @@ export function lookup<T>(map: Record<string, T>, key: string): T | undefined;
  * forbid it — an unknown is fail-closed to uncovered, which is the whole point
  * of the matrix. Throws on an unrecognized status (fail loud — a typo must not
  * quietly read as "permitted").
- * @param {string} status a {@link CoverageStatus} value
+ *
+ * `undefined` is accepted as an INPUT type — that is what a prototype-safe
+ * `lookup` of a missing key yields — and takes the same throw: a coverage a
+ * caller could not resolve must never read as "permitted" either.
+ * @param {string|undefined} status a {@link CoverageStatus} value
  * @returns {boolean}
  */
-export function coverageAllowsVeto(status: string): boolean;
+export function coverageAllowsVeto(status: string | undefined): boolean;
+/**
+ * Whether an event may be marked `this_call_vetoable`.
+ *
+ * INVARIANT: an event whose kind the adapter's `GATED_EVENTS` does not name is
+ * never vetoable, whatever its coverage says. Coverage answers whether the
+ * host's hook fires for a CLASS of call and says nothing about a kind the
+ * adapter could not model — so keying on coverage alone reported an enforced
+ * block for every unmodelled event, which is the one direction that lies to a
+ * guardrail: the transcript shows a block and the host runs the tool.
+ * @param {string} kind an {@link EventKind} value
+ * @param {Set<string>} gatedKinds the adapter's own gated set
+ * @param {string|undefined} coverage a {@link CoverageStatus} value
+ * @returns {boolean}
+ */
+export function vetoableFor(kind: string, gatedKinds: Set<string>, coverage: string | undefined): boolean;
+/**
+ * Refuse a gated-kind set naming a kind no host can gate. Called at module load
+ * by each adapter, so `EventKind.UNKNOWN` cannot be added to one by hand.
+ * @param {Set<string>} kinds an adapter's `GATED_EVENTS`
+ * @param {string} agent the adapter's agent id, for the message
+ */
+export function assertGatedKinds(kinds: Set<string>, agent: string): void;
 /**
  * True when `status` is a recognized {@link CoverageStatus} value.
  * @param {unknown} status