agent-control-plane-core 0.4.2 → 0.4.3

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.4.3",
   "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

@@ -20,6 +20,7 @@ import {
   classifyCallClass,
   coverageAllowsVeto,
   canonicalTool,
+  lookup,
   makeEvent,
   normalizeVerdict,
   nativeResponse,
@@ -87,6 +88,49 @@ export function parse(native) {
   });
 }
 
+/**
+ * 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 +143,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/conformance.mjs

@@ -1,5 +1,8 @@
 import {
   CALL_CLASSES,
+  Decision,
+  EventKind,
+  IntegrationMode,
   MODELED_TOOL_INPUT_KEYS,
   TOOL_ALIASES,
   canonicalTool,
@@ -8,6 +11,16 @@ 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 });
+
 /**
  * Assert an adapter's {@link import("./control-plane.mjs").Adapter.COVERAGE}
  * hook-coverage matrix is well-formed: it classifies EXACTLY the canonical
@@ -66,14 +79,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 +211,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, coverageClassesChecked: Set<string>, unenforceableDenyChecks: number }}
  */
 export function runAdapterConformance({ adapter, fixtures, assert }) {
   assert.equal(
@@ -219,6 +243,8 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
   let mutationSeen = false;
   let enforcedDenySeen = false;
   let vetoableDenySeen = false;
+  let preToolCases = 0;
+  let unenforceableDenyChecks = 0;
   let renders = 0;
 
   for (const testCase of fixtures.cases) {
@@ -239,11 +265,15 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
         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 +337,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"]) {
@@ -324,6 +386,15 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
     "no enforced deny rendered — enforcement honesty is untested",
   );
   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,
@@ -333,5 +404,6 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
     enforcedDenySeen,
     vetoableDenySeen,
     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)}`,
     );

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, coverageClassesChecked: Set<string>, unenforceableDenyChecks: number }}
  */
 export function runAdapterConformance({ adapter, fixtures, assert }: {
     adapter: import("./control-plane.mjs").Adapter;
@@ -109,4 +117,5 @@ export function runAdapterConformance({ adapter, fixtures, assert }: {
     enforcedDenySeen: boolean;
     vetoableDenySeen: boolean;
     coverageClassesChecked: Set<string>;
+    unenforceableDenyChecks: number;
 };

package/types/control-plane.d.mts

@@ -38,10 +38,14 @@ 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;
 /**
  * True when `status` is a recognized {@link CoverageStatus} value.
  * @param {unknown} status