agent-control-plane-core 0.8.2 → 0.9.1

package/README.md

@@ -32,7 +32,7 @@ removes.
   declaration of what that agent's transport cannot carry. `parse` turns that
   agent's raw hook payload into a `ToolCallEvent`; `render` turns your `Verdict`
   back into the **real** native signal that agent enforces (the right JSON body,
-  exit code, or thrown error — not just a print).
+  exit code and stderr reason — not just a print).
 
 You write your logic **once** against the normalized types. Adding support for a
 new agent is a new adapter (~one file + fixtures), not a rewrite of your tool.
@@ -85,7 +85,8 @@ pnpm add agent-control-plane-core
 // Verdict — a normalized guardrail decision.
 {
   decision: "allow" | "deny" | "ask",
-  mutated_input?: object,           // replacement tool input
+  mutated_input?: object,           // replacement tool input (pre_tool)
+  mutated_output?: unknown,         // replacement tool output the model sees (post_tool)
   additional_context?: string,      // extra context to splice into the agent's stream
   reason?: string,                  // shown on deny/ask
 }
@@ -144,9 +145,10 @@ the render does not carry.
 
 ```js
 import { claudeAdapter } from "agent-control-plane-core/claude";
+import { readStdin, emit } from "agent-control-plane-core/runtime";
 
 // 1. Normalize the agent's raw hook payload.
-const event = claudeAdapter.parse(rawHookJson);
+const event = claudeAdapter.parse(JSON.parse(await readStdin()));
 
 // 2. Your guardrail decides, using only the normalized types.
 const verdict =
@@ -154,16 +156,22 @@ const verdict =
     ? { decision: "deny", reason: "destructive command blocked" }
     : { decision: "allow" };
 
-// 3. Render back to the agent's native response.
-process.stdout.write(JSON.stringify(claudeAdapter.render(verdict, event)));
+// 3. Send the native response: the stdout body, the block reason on stderr,
+//    and the exit code (2 on this deny), which is what makes Claude Code block.
+emit(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.
+`render` returns the whole native response, not a body to print. Writing
+`JSON.stringify(render(...))` to stdout exits 0, so the host never blocks.
+
+`agent-control-plane-core/runtime` publishes the rest of the plumbing the four
+hook entries share. `renderHookResponse` runs parse → judge → render, and returns
+the failure response THAT host expects when the payload does not parse. `emit`
+drains the whole body before it exits, so a large deny body is never truncated
+on a non-blocking pipe. The entries ship as `acp-claude-hook`, `acp-codex-hook`,
+`acp-amp-hook` and `acp-gemini-hook`. Codex's hook stdin carries no version, so
+set `ACP_CODEX_VERSION` to the Codex version your launcher pins (or call
+`createCodexAdapter({ version })`); without it, Codex calls parse advisory.
 
 The core contract and every adapter (`claude`, `codex`, `amp`, `gemini`) are
 also on the default entry:
@@ -285,7 +293,7 @@ and bumps the version.
 ```bash
 ./setup.sh          # install deps + git hooks
 pnpm test           # node --test
-pnpm test:coverage  # c8, 100% lines/branches/functions per file
+pnpm test:coverage  # c8, the per-file floor .c8rc.json sets
 pnpm check          # tsc --noEmit (JSDoc types)
 pnpm gen:schema     # regenerate schema/ from the contract
 pnpm lint           # eslint

package/bin/codex-hook.mjs

@@ -4,18 +4,22 @@
  * PreToolUse/PermissionRequest/PostToolUse payload on stdin, applies the demo
  * judge, and emits Codex's native response.
  *
+ * CODEX VERSION — set `ACP_CODEX_VERSION` to the version of the Codex binary
+ * the launcher pinned (for example `ACP_CODEX_VERSION=0.151.0`). Codex's hook
+ * stdin carries no version, so without it every call parses observe-only and a
+ * deny renders advisory (exit 0). Below v0.135 the render is advisory too,
+ * because Codex has no hook veto there.
+ *
  * FAILURE POSTURE — fail OPEN (exit 0), like Claude Code: Codex treats a
- * non-conforming hook as non-blocking. On a pre-v0.135 Codex the render is
- * advisory anyway (the adapter marks it observe-only), so a failure and a
- * successful advisory both leave the tool to proceed — the sandbox is the
- * backstop.
+ * non-conforming hook as non-blocking. The sandbox is the backstop.
  *
- * Usage: `node bin/codex-hook.mjs < payload.json`
+ * Usage: `ACP_CODEX_VERSION=0.151.0 node bin/codex-hook.mjs < payload.json`
  */
-import { codexAdapter } from "../src/adapters/codex.mjs";
+import { createCodexAdapter } from "../src/adapters/codex.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 };
 
-emit(renderHookResponse(codexAdapter, await readStdin(), FAIL_OPEN));
+const adapter = createCodexAdapter({ version: process.env.ACP_CODEX_VERSION });
+emit(renderHookResponse(adapter, await readStdin(), FAIL_OPEN));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-control-plane-core",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "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": {
@@ -24,6 +24,12 @@
   },
   "main": "./src/index.mjs",
   "types": "./types/index.d.mts",
+  "bin": {
+    "acp-claude-hook": "./bin/claude-hook.mjs",
+    "acp-codex-hook": "./bin/codex-hook.mjs",
+    "acp-amp-hook": "./bin/amp-hook.mjs",
+    "acp-gemini-hook": "./bin/gemini-hook.mjs"
+  },
   "exports": {
     ".": {
       "types": "./types/index.d.mts",

package/src/adapters/amp.mjs

@@ -25,7 +25,8 @@ import {
   lookup,
   makeEvent,
   normalizeVerdict,
-  nativeResponse,
+  gatedResponse,
+  blockTransportFor,
   readonlySet,
   VERDICT_CONTENT_FIELDS,
   baseMeta,
@@ -185,7 +186,10 @@ export const NATIVE_ASK_TIER = true;
  */
 const EXIT_CODE_BY_DECISION = Object.freeze({
   [Decision.ALLOW]: Object.freeze({ true: 0, false: 0 }),
-  [Decision.DENY]: Object.freeze({ true: 2, false: 1 }),
+  [Decision.DENY]: Object.freeze({
+    true: blockTransportFor(AGENT).exit_code,
+    false: 1,
+  }),
   [Decision.ASK]: Object.freeze({ true: 1, false: 1 }),
 });
 
@@ -265,11 +269,11 @@ export function render(verdict, event) {
     );
   const enforced = vd.decision === Decision.DENY && vetoable;
   const exit_code = exitCodeFor(EXIT_CODE_BY_DECISION, vd.decision, vetoable);
-  return nativeResponse({
+  return gatedResponse(AGENT, {
     transport: INTEGRATION_MODE,
-    exit_code,
+    unblocked_exit_code: exit_code,
     enforced,
-    ...(enforced && vd.reason !== undefined ? { stderr: vd.reason } : {}),
+    reason: vd.reason,
   });
 }
 

package/src/adapters/claude.mjs

@@ -26,7 +26,7 @@ import {
   lookup,
   makeEvent,
   normalizeVerdict,
-  nativeResponse,
+  gatedResponse,
   UNRENDERED_ON_UNKNOWN,
   readonlySet,
   baseMeta,
@@ -260,20 +260,15 @@ export function render(verdict, event, { soleGate = false } = {}) {
       ? gatingBody(hookEventName, vd, soleGate)
       : nonGatingBody(hookEventName, kind, vd);
 
-  return nativeResponse({
+  // Claude Code parses hook stdout as JSON only on exit 0: on an exit-2 block it
+  // discards the body and reads STDERR, which `gatedResponse` fills from the
+  // BLOCK_TRANSPORT row.
+  return gatedResponse(AGENT, {
     transport: INTEGRATION_MODE,
-    exit_code: enforced ? 2 : 0,
+    unblocked_exit_code: 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 } : {}),
+    reason: vd.reason,
   });
 }
 
@@ -326,7 +321,10 @@ function nonGatingBody(hookEventName, kind, vd) {
     hookSpecificOutput.additionalContext = vd.additional_context;
   /** @type {Record<string, unknown>} */
   const out = { hookSpecificOutput };
-  if (vd.decision !== Decision.ALLOW) {
+  // Not on an UNKNOWN kind either: Claude Code honours `decision: "block"` on
+  // events this adapter does not model (on Stop it keeps the agent running),
+  // so writing it there acts on the host while the render reports no block.
+  if (kind !== EventKind.UNKNOWN && vd.decision !== Decision.ALLOW) {
     out.decision = "block";
     if (vd.reason !== undefined) out.reason = vd.reason;
   }

package/src/adapters/codex.mjs

@@ -10,7 +10,9 @@
  *
  * VERSION GATE: hook enforcement only exists in v0.135+. Below that, there is no
  * veto, so parse marks the event OBSERVE_ONLY with this_call_vetoable=false —
- * the adapter must not pretend to enforce on an old Codex.
+ * the adapter must not pretend to enforce on an old Codex. Codex's hook stdin
+ * carries no version, so the launcher that pins the binary supplies it through
+ * {@link createCodexAdapter}.
  */
 
 import semver from "semver";
@@ -28,7 +30,9 @@ import {
   lookup,
   makeEvent,
   normalizeVerdict,
-  nativeResponse,
+  gatedResponse,
+  blockTransportFor,
+  blockReason,
   UNRENDERED_ON_UNKNOWN,
   readonlySet,
   baseMeta,
@@ -184,10 +188,6 @@ export const NATIVE_EVENT_FOR = Object.freeze({
  */
 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";
-
 // The STANDARD_META_FIELDS are consumed by `baseMeta`, not listed here.
 const CONSUMED = new Set([
   "hook_event_name",
@@ -203,16 +203,12 @@ const CONSUMED = new Set([
  * release core; anything it can't coerce to a valid version (missing, empty,
  * garbage) yields `null` and is treated as too old — fail closed to advisory.
  *
- * TRUST BOUNDARY (sandbox, not adapter): `version` is read from the hook stdin
- * payload, so a payload that under-reports it downgrades enforcement to advisory
- * (a deny renders exit 0). The adapter cannot distinguish a spoofed version from
- * a genuinely old Codex — the ground-truth version lives outside the payload —
- * so anti-spoofing belongs to the sandbox that controls what the hook is fed
- * (the same "pin it from outside" posture the managed-config mount enforces for
- * the hook binary; see docs/monitor-invariants.md §Invariant 1). Coercing an
- * absent/garbage version to enforcing HERE would break the legitimate old-Codex
- * case (rendering an exit-2 block a pre-0.135 Codex ignores, while dishonestly
- * marking it `enforced`), so the adapter stays faithful to what the payload says.
+ * WHERE THE VERSION COMES FROM: Codex's PreToolUse stdin carries no `version`
+ * field, so the launcher that pins the Codex binary supplies it, through
+ * {@link createCodexAdapter}. A payload `version` is a fallback only, and the
+ * payload is untrusted: one that under-reports downgrades a deny to advisory. Coercing an absent version to enforcing HERE would
+ * break the legitimate old-Codex case (an exit-2 block a pre-0.135 Codex
+ * ignores, dishonestly marked `enforced`), so an unknown version stays advisory.
  * @param {unknown} version
  * @returns {boolean}
  */
@@ -254,10 +250,16 @@ function vetoableCall(kind, nativeTool, raw) {
  * Parse a raw Codex hook payload. Never throws on unmodelled input. Marks the
  * event observe-only (this_call_vetoable=false) when the Codex version
  * predates hook enforcement.
+ *
+ * `version` is the Codex version the LAUNCHER pinned, and it wins. Codex's
+ * hook stdin documents no version field, so a payload `version` is read only
+ * when no launcher version was given: a wrapper that injects one into stdin
+ * keeps working. With neither, the event is advisory.
  * @param {any} native
+ * @param {{ version?: string }} [options]
  * @returns {ToolCallEvent}
  */
-export function parse(native) {
+export function parse(native, { version } = {}) {
   const raw = asObject(native);
   const nativeEvent = asString(raw.hook_event_name, "");
   const kind =
@@ -265,7 +267,7 @@ export function parse(native) {
       /** @type {Record<string, string>} */ (NATIVE_TO_KIND),
       nativeEvent,
     ) ?? EventKind.UNKNOWN;
-  const enforce = canEnforce(raw.version);
+  const enforce = canEnforce(version ?? raw.version);
 
   const meta = baseMeta({
     agent: AGENT,
@@ -330,10 +332,11 @@ export function render(verdict, event, { soleGate = false } = {}) {
   // PermissionRequest answers as itself; NATIVE_EVENT_FOR names the fallback.
   const hookEventName = event.meta.native_event || HookEvent.PRE_TOOL_USE;
 
-  return nativeResponse({
+  return gatedResponse(AGENT, {
     transport: event.meta.integration_mode,
-    exit_code: enforced ? 2 : 0,
+    unblocked_exit_code: 0,
     enforced,
+    reason: vd.reason,
     stdout:
       event.event === EventKind.POST_TOOL
         ? postToolBody(hookEventName, vd, enforced)
@@ -356,17 +359,21 @@ function preToolBody(hookEventName, vd, event, enforced, soleGate) {
   // deny/ask emit an explicit decision, unless `soleGate` opts into it.
   /** @type {Record<string, unknown>} */
   const body = { hookEventName };
-  if (vd.decision !== Decision.ALLOW || soleGate) {
+  // An UNKNOWN event reaches this body too. It has no established decision
+  // channel, so it carries none: a decision there would act on the host while
+  // the render reports no block.
+  if (
+    event.event === EventKind.PRE_TOOL &&
+    (vd.decision !== Decision.ALLOW || soleGate)
+  ) {
     body.permissionDecision = vd.decision;
     if (vd.reason !== undefined) body.permissionDecisionReason = vd.reason;
   }
   // Codex FAILS OPEN on an enforced deny whose permissionDecisionReason is missing
   // or empty: its PreToolUse output parser drops the block (block_reason = None)
-  // and runs the tool. Unlike Claude, which honours a bare deny, Codex needs a
-  // non-empty reason for the block to bite — so guarantee one on every enforced
-  // deny, whatever the judge supplied.
-  if (enforced && !body.permissionDecisionReason)
-    body.permissionDecisionReason = DEFAULT_DENY_REASON;
+  // and runs the tool (BLOCK_TRANSPORT.codex.reason_required).
+  if (enforced && blockTransportFor(AGENT).reason_required)
+    body.permissionDecisionReason = blockReason(vd.reason);
   // PRE_TOOL only. An UNKNOWN event reaches this body too, and an event the
   // adapter cannot name has no channel it can claim: emitting `updatedInput`
   // there names a key the host ignores while reading to the caller as a
@@ -403,18 +410,37 @@ function postToolBody(hookEventName, vd, enforced) {
   // whose reason Codex may drop is a block that may not bite. Unverified for
   // PostToolUse specifically — a non-empty reason is the safe side of that, and
   // the model needs the text either way.
-  if (enforced && !body.reason) body.reason = DEFAULT_DENY_REASON;
+  if (enforced && blockTransportFor(AGENT).reason_required)
+    body.reason = blockReason(vd.reason);
   return body;
 }
 
-/** @type {import("../control-plane.mjs").Adapter} */
-export const codexAdapter = {
-  AGENT,
-  INTEGRATION_MODE,
-  COVERAGE,
-  UNRENDERED_FIELDS,
-  NATIVE_ASK_TIER,
-  NATIVE_EVENT_FOR,
-  parse,
-  render,
-};
+/**
+ * Build a Codex adapter whose `parse` judges every payload against `version`,
+ * the Codex version the launcher pinned (Codex's hook stdin carries none).
+ * Below {@link MIN_ENFORCING_VERSION} every event parses observe-only and a
+ * deny renders advisory. With no `version`, `parse` falls back to a payload
+ * `version` (see {@link parse}).
+ * @param {{ version?: string }} [options]
+ * @returns {import("../control-plane.mjs").Adapter}
+ */
+export function createCodexAdapter({ version } = {}) {
+  return {
+    AGENT,
+    INTEGRATION_MODE,
+    COVERAGE,
+    UNRENDERED_FIELDS,
+    NATIVE_ASK_TIER,
+    NATIVE_EVENT_FOR,
+    parse: (native) => parse(native, { version }),
+    render,
+  };
+}
+
+/**
+ * The Codex adapter with no launcher-pinned version. Real Codex sends no
+ * version, so every event it sends parses observe-only here. A deployment that
+ * runs Codex ≥ v0.135 builds its own with {@link createCodexAdapter}.
+ * @type {import("../control-plane.mjs").Adapter}
+ */
+export const codexAdapter = createCodexAdapter();

package/src/adapters/gemini.mjs

@@ -43,7 +43,7 @@ import {
   MODELED_TOOL_INPUT_KEYS,
   makeEvent,
   normalizeVerdict,
-  nativeResponse,
+  gatedResponse,
   UNRENDERED_ON_UNKNOWN,
   readonlySet,
   baseMeta,
@@ -374,31 +374,23 @@ export function render(verdict, event, { soleGate = false } = {}) {
   const vd = normalizeVerdict(verdict);
   const enforced = vd.decision === Decision.DENY && event.this_call_vetoable;
 
-  // Enforced deny is a System Block: exit 2, reason carried on STDERR (Gemini
-  // reads its block rationale from stderr, not the ignored stdout body). Carry it
-  // on NativeResponse.stderr so `emit` writes it to fd 2 — a genuine block is
-  // never surfaced to the user/model with no explanation.
-  // No stdout body at all on this path, so EVERY content field is dropped here,
-  // whatever UNRENDERED_FIELDS says for the kind — that map describes the allow
-  // path. Nothing is lost that a blocked call could still use: the tool never
-  // runs, so only `additional_context` had anywhere to go.
-  if (enforced)
-    return nativeResponse({
-      transport: INTEGRATION_MODE,
-      exit_code: 2,
-      enforced: true,
-      ...(vd.reason !== undefined ? { stderr: vd.reason } : {}),
-    });
-
-  const body =
-    event.event === EventKind.PROMPT_SUBMIT
-      ? promptSubmitBody(vd)
-      : decisionBody(vd, event.event, soleGate);
-  return nativeResponse({
+  // An enforced deny is a System Block: `gatedResponse` writes the exit code
+  // and the stderr reason from the BLOCK_TRANSPORT row, and there is no stdout
+  // body, so EVERY content field is dropped whatever UNRENDERED_FIELDS says —
+  // that map describes the allow path. The tool never runs, so only
+  // `additional_context` had anywhere to go.
+  let body;
+  if (!enforced)
+    body =
+      event.event === EventKind.PROMPT_SUBMIT
+        ? promptSubmitBody(vd)
+        : decisionBody(vd, event.event, soleGate);
+  return gatedResponse(AGENT, {
     transport: INTEGRATION_MODE,
-    exit_code: 0,
-    enforced: false,
-    ...(body === undefined ? {} : { stdout: body }),
+    unblocked_exit_code: 0,
+    enforced,
+    stdout: body,
+    reason: vd.reason,
   });
 }
 
@@ -436,7 +428,10 @@ function applyAdvisoryDeny(out, vd) {
 function decisionBody(vd, kind, soleGate) {
   /** @type {Record<string, unknown>} */
   const out = {};
-  if (!applyAdvisoryDeny(out, vd) && soleGate) out.decision = "allow";
+  // An UNKNOWN kind has no established decision channel, and Gemini acts on a
+  // `decision` it does see (AfterAgent's deny forces a retry), so it gets none.
+  if (kind !== EventKind.UNKNOWN && !applyAdvisoryDeny(out, vd) && soleGate)
+    out.decision = "allow";
   if (kind === EventKind.PRE_TOOL && vd.mutated_input !== undefined)
     out.hookSpecificOutput = { tool_input: vd.mutated_input };
   // `systemMessage` is documented on the TOOL events. An UNKNOWN kind is an

package/src/conformance.mjs

@@ -5,6 +5,7 @@ import {
   IntegrationMode,
   MODELED_TOOL_INPUT_KEYS,
   TOOL_ALIASES,
+  BLOCK_TRANSPORT,
   canonicalTool,
   coverageAllowsVeto,
   isCoverageStatus,
@@ -860,6 +861,33 @@ function assertAliasedInput(agent, caseName, event, assert) {
   );
 }
 
+/**
+ * Hold an enforced render to its host's {@link BLOCK_TRANSPORT} row: the row's
+ * exit code, and a non-empty reason on the row's reason stream. An adapter with
+ * no row (one this package does not ship) is held to the reason on `stderr`,
+ * the contract's block-reason channel. A block with no reason reaches the
+ * model with no rationale, and Codex drops it and runs the tool.
+ * @param {string} agent
+ * @param {import("./control-plane.mjs").NativeResponse} rendered
+ * @param {string} label
+ * @param {any} assert
+ */
+function assertBlockTransport(agent, rendered, label, assert) {
+  const row = lookup(BLOCK_TRANSPORT, agent);
+  if (row !== undefined)
+    assert.equal(
+      rendered.exit_code,
+      row.exit_code,
+      `enforced deny exits ${rendered.exit_code}, but ${agent} blocks on exit ${row.exit_code}: ${label}`,
+    );
+  const stream = row?.reason_stream ?? "stderr";
+  const reason = rendered[stream];
+  assert.ok(
+    typeof reason === "string" && reason.trim() !== "",
+    `enforced deny carries no reason on ${stream}: ${label}`,
+  );
+}
+
 /**
  * The control-plane conformance harness.
  *
@@ -879,7 +907,8 @@ function assertAliasedInput(agent, caseName, event, assert) {
  *      decision the contract requires every adapter to express.
  *   4. enforcement honesty: an enforceable deny (`rendered.enforced === true`)
  *      MUST carry a real block signal — a non-zero `exit_code` — not just a JSON
- *      body the agent is free to ignore. At least one enforced deny must appear,
+ *      body the agent is free to ignore — plus a non-empty reason on the
+ *      reason stream its {@link BLOCK_TRANSPORT} row names. At least one enforced deny must appear,
  *      so the honesty check is never vacuous.
  *   5. vetoability honesty, BOTH directions. When the parsed event's
  *      `this_call_vetoable` is false, EVERY render for that case must be
@@ -1033,6 +1062,12 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
           rendered.exit_code !== 0,
           `enforced deny carries no block signal: ${testCase.name} / ${scenario}`,
         );
+        assertBlockTransport(
+          adapter.AGENT,
+          rendered,
+          `${testCase.name} / ${scenario}`,
+          assert,
+        );
         enforcedDenySeen = true;
       }
       if (parsed.this_call_vetoable === false) {