agent-control-plane-core 0.10.0 → 0.11.1

package/README.md

@@ -168,14 +168,32 @@ emit(claudeAdapter.render(verdict, event));
 `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`
+hook entries share. `runHookEntry(adapter, judge)` is a whole entry: each
+`bin/<host>-hook.mjs` is that one call. `renderHookResponse` runs parse → judge
+→ `renderEscalated`, so a judge's `ask` on a host with no ask tier blocks a
+vetoable call instead of running it. It 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.
 
+Each entry fails the way its host expects when the hook itself breaks: claude,
+codex and gemini run the call, and amp asks. Set `ACP_FAIL_CLOSED=1` to block
+instead, on every host. The entry then exits 2 with the reason on stderr when
+the payload does not parse, or when the judge throws or answers no decision.
+Register a fail-closed entry on tool-call events only. On a Stop event, exit 2
+means "keep working".
+
+A host that kills a hook on its timeout runs the call. Set
+`ACP_HOOK_TIMEOUT_MS` below the host's hook timeout, and the entry gives its
+failure response at that deadline instead. A judge that blocks the event loop
+past the deadline still loses to the host's timeout. Nothing in the entry can
+answer for a process that never starts (no `node`, a module that fails to
+load). Claude Code covers that case with `"onFailure": "block"` on the hook
+entry. Codex has no such option, so it still runs the call.
+
 The core contract and every adapter (`claude`, `codex`, `amp`, `gemini`) are
 also on the default entry:
 

package/bin/amp-hook.mjs

@@ -4,18 +4,12 @@
  * delegate payload on stdin, applies the demo judge, and exits with Amp's
  * decision code (0 allow / 1 ask / 2 reject).
  *
- * FAILURE POSTURE — fail to ASK (exit 1), NOT allow. Amp's delegate reads exit 1
- * as "ask the human," which is the safe degradation when the guardrail itself is
- * broken: neither silently allowing (exit 0) nor hard-denying (exit 2) a call it
- * never actually judged. This is the asymmetry the per-host split exists for —
- * Amp has a safe "ask" failure code that Claude Code's transport does not.
+ * FAILURE POSTURE — fail to ASK (exit 1), its `HOST_FAILURE` row in
+ * `src/runtime.mjs`. `ACP_FAIL_CLOSED=1` blocks instead (exit 2).
  *
  * Usage: `node bin/amp-hook.mjs < payload.json`
  */
 import { ampAdapter } from "../src/adapters/amp.mjs";
-import { readStdin, renderHookResponse, emit } from "../src/runtime.mjs";
+import { runHookEntry } from "../src/runtime.mjs";
 
-/** @type {import("../src/control-plane.mjs").NativeResponse} */
-const FAIL_ASK = { transport: "external_hook", exit_code: 1, enforced: false };
-
-emit(renderHookResponse(ampAdapter, await readStdin(), FAIL_ASK));
+await runHookEntry(ampAdapter);

package/bin/claude-hook.mjs

@@ -3,18 +3,12 @@
  * Claude Code EXTERNAL_HOOK entry. Reads a native PreToolUse payload on stdin,
  * applies the demo judge, and emits Claude Code's native response.
  *
- * FAILURE POSTURE — fail OPEN. Claude Code treats a hook that crashes, times out,
- * or emits a non-conforming body as "no objection" and runs the tool anyway, so
- * on any internal failure this exits 0 with no body rather than pretending to a
- * decision it couldn't compute. A broken guardrail must not wedge the user; the
- * sandbox is the real backstop, not this hook.
+ * FAILURE POSTURE — fail OPEN (exit 0), its `HOST_FAILURE` row in
+ * `src/runtime.mjs`. `ACP_FAIL_CLOSED=1` blocks instead (exit 2).
  *
  * Usage: `node bin/claude-hook.mjs < payload.json`
  */
 import { claudeAdapter } from "../src/adapters/claude.mjs";
-import { readStdin, renderHookResponse, emit } from "../src/runtime.mjs";
+import { runHookEntry } from "../src/runtime.mjs";
 
-/** @type {import("../src/control-plane.mjs").NativeResponse} */
-const FAIL_OPEN = { transport: "external_hook", exit_code: 0, enforced: false };
-
-emit(renderHookResponse(claudeAdapter, await readStdin(), FAIL_OPEN));
+await runHookEntry(claudeAdapter);

package/bin/codex-hook.mjs

@@ -10,16 +10,14 @@
  * 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. The sandbox is the backstop.
+ * FAILURE POSTURE — fail OPEN (exit 0), its `HOST_FAILURE` row in
+ * `src/runtime.mjs`. `ACP_FAIL_CLOSED=1` blocks instead (exit 2).
  *
  * Usage: `ACP_CODEX_VERSION=0.151.0 node bin/codex-hook.mjs < payload.json`
  */
 import { createCodexAdapter } from "../src/adapters/codex.mjs";
-import { readStdin, renderHookResponse, emit } from "../src/runtime.mjs";
+import { runHookEntry } from "../src/runtime.mjs";
 
-/** @type {import("../src/control-plane.mjs").NativeResponse} */
-const FAIL_OPEN = { transport: "external_hook", exit_code: 0, enforced: false };
-
-const adapter = createCodexAdapter({ version: process.env.ACP_CODEX_VERSION });
-emit(renderHookResponse(adapter, await readStdin(), FAIL_OPEN));
+await runHookEntry(
+  createCodexAdapter({ version: process.env.ACP_CODEX_VERSION }),
+);

package/bin/gemini-hook.mjs

@@ -3,17 +3,12 @@
  * Gemini CLI EXTERNAL_HOOK entry. Reads a native BeforeTool payload on stdin,
  * applies the demo judge, and emits Gemini's native response.
  *
- * FAILURE POSTURE — fail OPEN (exit 0). Gemini CLI treats a non-2 / crashed hook
- * exit as a non-fatal warning and continues, so on any internal failure this
- * exits 0 rather than emitting a spurious System Block (only a clean deny exits
- * 2). A broken guardrail must not wedge the user; the sandbox is the backstop.
+ * FAILURE POSTURE — fail OPEN (exit 0), its `HOST_FAILURE` row in
+ * `src/runtime.mjs`. `ACP_FAIL_CLOSED=1` blocks instead (exit 2).
  *
  * Usage: `node bin/gemini-hook.mjs < payload.json`
  */
 import { geminiAdapter } from "../src/adapters/gemini.mjs";
-import { readStdin, renderHookResponse, emit } from "../src/runtime.mjs";
+import { runHookEntry } from "../src/runtime.mjs";
 
-/** @type {import("../src/control-plane.mjs").NativeResponse} */
-const FAIL_OPEN = { transport: "external_hook", exit_code: 0, enforced: false };
-
-emit(renderHookResponse(geminiAdapter, await readStdin(), FAIL_OPEN));
+await runHookEntry(geminiAdapter);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-control-plane-core",
-  "version": "0.10.0",
+  "version": "0.11.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": {

package/src/runtime.mjs

@@ -1,13 +1,11 @@
 /**
  * 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.
+ * (`bin/<host>-hook.mjs`) that hardcodes its adapter; {@link runHookEntry}
+ * runs it with that host's OWN failure posture from {@link HOST_FAILURE}. 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;
+ * a per-host table keyed by the adapter's own AGENT 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:
@@ -15,7 +13,12 @@
  * `process.exit` (see {@link writeAllSync}).
  */
 import { writeSync } from "node:fs";
-import { Decision, sanitizeVerdict } from "./control-plane.mjs";
+import {
+  Decision,
+  gatedResponse,
+  renderEscalated,
+  sanitizeVerdict,
+} from "./control-plane.mjs";
 
 /**
  * Read all of stdin to a string.
@@ -57,15 +60,17 @@ export function demoJudge(event) {
 /**
  * Run one host's parse→judge→render pipe over a raw stdin payload. If the payload
  * can't be parsed or the render 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.
+ * fail-safe response from {@link failurePosture} — so a crashed hook degrades
+ * the way THAT host expects instead of a single shared default. This is the
+ * deliberate, necessary recovery the whole per-host split exists for, not a
+ * blanket swallow.
  *
  * A judge that THROWS is not a malformed payload: the call parsed, and the judge
  * failed to answer. That takes the same path as a judge that answers garbage —
  * the clamp's `ask` (see below) — so a crashing guardrail puts the call in front
- * of a human instead of taking an exit-0 fail-safe that runs it.
+ * of a human instead of taking an exit-0 fail-safe that runs it. The verdict
+ * renders through `renderEscalated`, so on a host with no ask tier that ask
+ * blocks a vetoable call rather than running it.
  *
  * Every error is written to STDERR (never stdout, which belongs to the host
  * transport) so a regression that silently disables enforcement leaves a
@@ -108,6 +113,11 @@ export function renderHookResponse(
       answer = { reason: `hook judge threw: ${describe(err).split("\n")[0]}` };
       report("hook judge error", err);
     }
+    // A host-supplied `onFailure` that BLOCKS (see {@link failurePosture}) wins
+    // over the clamp's ask. `renderEscalated` keeps an ask on a host that
+    // honours one (Claude, Amp), so without this a fail-closed entry would ask
+    // about a call no judge approved instead of blocking it.
+    if (onFailure.enforced && !isDecision(answer)) return onFailure;
     // A judge's answer is clamped, not trusted. `normalizeVerdict` (inside
     // every adapter's render) THROWS on a decision outside allow/deny/ask, and
     // that throw would land in the catch below — the host's fail-safe, exit 0
@@ -116,13 +126,158 @@ export function renderHookResponse(
     // in front of a human. Prose is passed through: scrubbing monitor-authored
     // text needs a scrubber this transport module has no business choosing.
     const verdict = sanitizeVerdict(answer, (text) => text);
-    return adapter.render(verdict, event);
+    return renderEscalated(adapter, verdict, event);
   } catch (err) {
     report("hook pipeline error", err);
     return onFailure;
   }
 }
 
+/**
+ * Whether `answer` carries one of the three decisions a judge may return.
+ * @param {unknown} answer
+ * @returns {boolean}
+ */
+function isDecision(answer) {
+  const decision =
+    answer !== null && typeof answer === "object"
+      ? /** @type {{ decision?: unknown }} */ (answer).decision
+      : undefined;
+  return Object.values(Decision).includes(/** @type {any} */ (decision));
+}
+
+/**
+ * The response that BLOCKS the call on `agent`'s host: its
+ * {@link BLOCK_TRANSPORT} row's exit code, with `reason` on the row's reason
+ * stream. Every row blocks, so this is the one fail-closed response for all hosts.
+ * @param {string} agent
+ * @param {string} reason
+ * @returns {import("./control-plane.mjs").NativeResponse}
+ */
+export function failClosedResponse(agent, reason) {
+  return gatedResponse(agent, {
+    transport: "external_hook",
+    enforced: true,
+    unblocked_exit_code: 0,
+    reason,
+  });
+}
+
+/** @type {import("./control-plane.mjs").NativeResponse} */
+const RUN = Object.freeze({
+  transport: "external_hook",
+  exit_code: 0,
+  enforced: false,
+});
+
+/**
+ * Each host's DEFAULT response when its hook breaks, which is how that host
+ * degrades a hook it cannot read:
+ * - claude, codex, gemini: exit 0, so the call runs. Each host treats a crashed
+ *   or non-conforming hook as no objection, and a spurious block would wedge the
+ *   user. The sandbox is the backstop.
+ * - amp: exit 1, which Amp's delegate reads as "ask the human". That neither
+ *   runs nor rejects a call no judge saw.
+ * @type {Readonly<Record<string, import("./control-plane.mjs").NativeResponse>>}
+ */
+export const HOST_FAILURE = Object.freeze({
+  claude: RUN,
+  codex: RUN,
+  gemini: RUN,
+  amp: Object.freeze({
+    transport: "external_hook",
+    exit_code: 1,
+    enforced: false,
+  }),
+});
+
+/**
+ * The failure response for `agent`: its {@link HOST_FAILURE} row, or
+ * {@link failClosedResponse} when `ACP_FAIL_CLOSED=1`. A blocking failure
+ * response also blocks a call whose judge threw or answered no decision.
+ * Register a fail-closed entry on tool-call events only: on a Stop event,
+ * exit 2 means "keep working". {@link runHookEntry} also answers a hang
+ * before the host's timeout. It cannot answer for a process that never starts
+ * or that the host kills for another reason; only the host can, as Claude
+ * Code's `"onFailure": "block"` does.
+ * @param {string} agent
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {import("./control-plane.mjs").NativeResponse}
+ */
+export function failurePosture(agent, env = process.env) {
+  if (!Object.hasOwn(HOST_FAILURE, agent))
+    throw new Error(
+      `runtime: no HOST_FAILURE row for agent ${JSON.stringify(agent)}`,
+    );
+  const flag = env.ACP_FAIL_CLOSED;
+  if (flag === undefined || flag === "" || flag === "0")
+    return HOST_FAILURE[agent];
+  if (flag !== "1")
+    throw new Error(
+      `ACP_FAIL_CLOSED must be "1" or "0", got ${JSON.stringify(flag)}`,
+    );
+  return failClosedResponse(
+    agent,
+    "hook failed; ACP_FAIL_CLOSED blocks the call",
+  );
+}
+
+/**
+ * The whole hook entry for `adapter`'s host: read stdin, run
+ * {@link renderHookResponse} with that host's {@link failurePosture}, and
+ * {@link emit} the result. Every `bin/<host>-hook.mjs` is this one call. The
+ * failure response also answers a stdin read error and, when
+ * {@link hookDeadlineMs} is set, a hook still running at that deadline.
+ * @param {import("./control-plane.mjs").Adapter} adapter
+ * @param {(event: import("./control-plane.mjs").ToolCallEvent) => import("./control-plane.mjs").Verdict} [judge]
+ * @returns {Promise<never>}
+ */
+export async function runHookEntry(adapter, judge = demoJudge) {
+  const onFailure = failurePosture(adapter.AGENT);
+  const deadline = hookDeadlineMs();
+  /** @param {string} what @param {unknown} err @returns {never} */
+  const fail = (what, err) => {
+    report(what, err);
+    return emit(onFailure);
+  };
+  // A host that kills a hung hook runs the call, so the hook answers first with
+  // its own failure response. A judge that blocks the event loop outlasts this.
+  if (deadline !== undefined)
+    setTimeout(
+      () =>
+        fail(
+          "hook deadline",
+          new Error(`no response within ACP_HOOK_TIMEOUT_MS=${deadline}`),
+        ),
+      deadline,
+    );
+  /** @type {string} */
+  let raw;
+  try {
+    raw = await readStdin();
+  } catch (err) {
+    return fail("hook stdin error", err);
+  }
+  return emit(renderHookResponse(adapter, raw, onFailure, judge));
+}
+
+/**
+ * `ACP_HOOK_TIMEOUT_MS` as a positive integer, or `undefined` when unset. Set it
+ * below the host's own hook timeout, so the hook's failure response lands
+ * before the host kills it.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {number|undefined}
+ */
+export function hookDeadlineMs(env = process.env) {
+  const value = env.ACP_HOOK_TIMEOUT_MS;
+  if (value === undefined || value === "") return undefined;
+  if (!/^[1-9]\d*$/u.test(value))
+    throw new Error(
+      `ACP_HOOK_TIMEOUT_MS must be a positive integer of milliseconds, got ${JSON.stringify(value)}`,
+    );
+  return Number(value);
+}
+
 /**
  * A thrown value as readable text: an Error's stack (or message when it has no
  * stack), or the value itself for a bare throw.

package/types/runtime.d.mts

@@ -14,15 +14,17 @@ export function demoJudge(event: import("./control-plane.mjs").ToolCallEvent): i
 /**
  * Run one host's parse→judge→render pipe over a raw stdin payload. If the payload
  * can't be parsed or the render 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.
+ * fail-safe response from {@link failurePosture} — so a crashed hook degrades
+ * the way THAT host expects instead of a single shared default. This is the
+ * deliberate, necessary recovery the whole per-host split exists for, not a
+ * blanket swallow.
  *
  * A judge that THROWS is not a malformed payload: the call parsed, and the judge
  * failed to answer. That takes the same path as a judge that answers garbage —
  * the clamp's `ask` (see below) — so a crashing guardrail puts the call in front
- * of a human instead of taking an exit-0 fail-safe that runs it.
+ * of a human instead of taking an exit-0 fail-safe that runs it. The verdict
+ * renders through `renderEscalated`, so on a host with no ask tier that ask
+ * blocks a vetoable call rather than running it.
  *
  * Every error is written to STDERR (never stdout, which belongs to the host
  * transport) so a regression that silently disables enforcement leaves a
@@ -39,6 +41,48 @@ export function demoJudge(event: import("./control-plane.mjs").ToolCallEvent): i
  * @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;
+/**
+ * The response that BLOCKS the call on `agent`'s host: its
+ * {@link BLOCK_TRANSPORT} row's exit code, with `reason` on the row's reason
+ * stream. Every row blocks, so this is the one fail-closed response for all hosts.
+ * @param {string} agent
+ * @param {string} reason
+ * @returns {import("./control-plane.mjs").NativeResponse}
+ */
+export function failClosedResponse(agent: string, reason: string): import("./control-plane.mjs").NativeResponse;
+/**
+ * The failure response for `agent`: its {@link HOST_FAILURE} row, or
+ * {@link failClosedResponse} when `ACP_FAIL_CLOSED=1`. A blocking failure
+ * response also blocks a call whose judge threw or answered no decision.
+ * Register a fail-closed entry on tool-call events only: on a Stop event,
+ * exit 2 means "keep working". {@link runHookEntry} also answers a hang
+ * before the host's timeout. It cannot answer for a process that never starts
+ * or that the host kills for another reason; only the host can, as Claude
+ * Code's `"onFailure": "block"` does.
+ * @param {string} agent
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {import("./control-plane.mjs").NativeResponse}
+ */
+export function failurePosture(agent: string, env?: NodeJS.ProcessEnv): import("./control-plane.mjs").NativeResponse;
+/**
+ * The whole hook entry for `adapter`'s host: read stdin, run
+ * {@link renderHookResponse} with that host's {@link failurePosture}, and
+ * {@link emit} the result. Every `bin/<host>-hook.mjs` is this one call. The
+ * failure response also answers a stdin read error and, when
+ * {@link hookDeadlineMs} is set, a hook still running at that deadline.
+ * @param {import("./control-plane.mjs").Adapter} adapter
+ * @param {(event: import("./control-plane.mjs").ToolCallEvent) => import("./control-plane.mjs").Verdict} [judge]
+ * @returns {Promise<never>}
+ */
+export function runHookEntry(adapter: import("./control-plane.mjs").Adapter, judge?: (event: import("./control-plane.mjs").ToolCallEvent) => import("./control-plane.mjs").Verdict): Promise<never>;
+/**
+ * `ACP_HOOK_TIMEOUT_MS` as a positive integer, or `undefined` when unset. Set it
+ * below the host's own hook timeout, so the hook's failure response lands
+ * before the host kills it.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {number|undefined}
+ */
+export function hookDeadlineMs(env?: NodeJS.ProcessEnv): number | undefined;
 /**
  * Whether a failed `writeSync` is the one recoverable case: EAGAIN, meaning the
  * non-blocking pipe is momentarily full because the host has not drained it
@@ -80,3 +124,14 @@ export function writeAllSync(fd: number, text: string): void;
  * @returns {never}
  */
 export function emit(response: import("./control-plane.mjs").NativeResponse): never;
+/**
+ * Each host's DEFAULT response when its hook breaks, which is how that host
+ * degrades a hook it cannot read:
+ * - claude, codex, gemini: exit 0, so the call runs. Each host treats a crashed
+ *   or non-conforming hook as no objection, and a spurious block would wedge the
+ *   user. The sandbox is the backstop.
+ * - amp: exit 1, which Amp's delegate reads as "ask the human". That neither
+ *   runs nor rejects a call no judge saw.
+ * @type {Readonly<Record<string, import("./control-plane.mjs").NativeResponse>>}
+ */
+export const HOST_FAILURE: Readonly<Record<string, import("./control-plane.mjs").NativeResponse>>;