agent-control-plane-core 0.2.11 → 0.2.12

package/bin/hook-runtime.mjs

@@ -8,6 +8,7 @@
  * binary impersonate every host and so had to pick a single shared failure
  * behavior; sharing pure plumbing across distinct entries is not that.
  */
+import { writeSync } from "node:fs";
 import { Decision } from "../src/control-plane.mjs";
 
 /** Read all of stdin to a string. */
@@ -57,7 +58,17 @@ export function demoJudge(event) {
  */
 export function renderHookResponse(adapter, rawInput, onFailure) {
   try {
-    const event = adapter.parse(JSON.parse(rawInput));
+    const native = JSON.parse(rawInput);
+    // A non-object top-level payload (null, array, number, string) is malformed:
+    // the adapters' `asObject` would silently coerce it to `{}` and judge it as a
+    // benign no-op tool call — a rubber-stamp with no trace. Throw so it takes the
+    // host's declared failure posture AND leaves a greppable stderr diagnostic,
+    // instead of a silent coerce-to-empty.
+    if (native === null || typeof native !== "object" || Array.isArray(native))
+      throw new TypeError(
+        `hook payload must be a JSON object, got ${native === null ? "null" : Array.isArray(native) ? "array" : typeof native}`,
+      );
+    const event = adapter.parse(native);
     return adapter.render(demoJudge(event), event);
   } catch (err) {
     const detail = err instanceof Error ? (err.stack ?? err.message) : `${err}`;
@@ -73,7 +84,18 @@ export function renderHookResponse(adapter, rawInput, onFailure) {
  * @returns {never}
  */
 export function emit(response) {
+  // `writeSync` (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.
   if (response.stdout !== undefined)
-    process.stdout.write(JSON.stringify(response.stdout));
+    writeSync(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);
   process.exit(response.exit_code);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-control-plane-core",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "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/claude.mjs

@@ -21,6 +21,7 @@ import {
   classifyCallClass,
   coverageAllowsVeto,
   canonicalTool,
+  lookup,
   makeEvent,
   normalizeVerdict,
   nativeResponse,
@@ -146,8 +147,10 @@ export function parse(native) {
   const raw = asObject(native);
   const nativeEvent = asString(raw.hook_event_name, "");
   const kind =
-    /** @type {Record<string, string>} */ (NATIVE_TO_KIND)[nativeEvent] ??
-    EventKind.UNKNOWN;
+    lookup(
+      /** @type {Record<string, string>} */ (NATIVE_TO_KIND),
+      nativeEvent,
+    ) ?? EventKind.UNKNOWN;
   const response = kind === EventKind.POST_TOOL ? raw.tool_response : undefined;
   const nativeTool = claudeTool(kind, raw);
   const meta = claudeMeta(nativeEvent, raw);

package/src/adapters/codex.mjs

@@ -83,6 +83,17 @@ const CONSUMED = new Set([
  * `semver.coerce` normalizes a patch/prerelease/build-tagged version to its
  * 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.
  * @param {unknown} version
  * @returns {boolean}
  */

package/src/adapters/gemini.mjs

@@ -12,11 +12,20 @@
  * parsed as JSON (the path for allow / advisory / mutation); exit 2 → a "System
  * Block" that pre-empts the call, with the reason taken from STDERR (stdout is
  * ignored). So an ENFORCED deny renders as exit 2 (the only real block signal),
- * and its `reason` has no home in this stdout-only NativeResponse — it is
- * dropped here (a real hook wrapper also writes it to stderr), the same fidelity
- * gap Amp's exit-code transport has. Gemini has no native "ask" tier, so `ask`
- * maps to an exit-0 advisory `decision: "deny"` the model sees but that does not
- * hard-block.
+ * with its `reason` carried on `NativeResponse.stderr` (which `emit` writes to fd
+ * 2) so the System Block is never shown with no rationale. Gemini has no native
+ * "ask" tier, so `ask` maps to an exit-0 advisory `decision: "deny"` the model
+ * sees but that does not hard-block.
+ *
+ * PIN GAP (sandbox, not adapter — carried here because this is the module that
+ * knows the host is pin-dependent): Gemini CLI's system settings file wins over
+ * other settings FILES, but environment variables and CLI argv still override it,
+ * and `GEMINI_CLI_SYSTEM_SETTINGS_PATH` redirects WHERE the system file is read
+ * from (geminicli.com/docs/reference/configuration). So mounting the pinned
+ * system settings file read-only is NOT sufficient on Gemini CLI: an agent that
+ * controls its own env or launch argv routes around it. The launcher must ALSO
+ * fix `GEMINI_CLI_SYSTEM_SETTINGS_PATH` and the per-invocation env/argv the agent
+ * can't rewrite. See docs/monitor-invariants.md §Invariant 1.
  */
 
 import {
@@ -28,6 +37,7 @@ import {
   classifyCallClass,
   coverageAllowsVeto,
   canonicalTool,
+  lookup,
   assertAliasTargetsModeled,
   makeEvent,
   normalizeVerdict,
@@ -142,7 +152,7 @@ assertAliasTargetsModeled(GEMINI_TOOL_ALIASES);
  */
 function geminiCanonicalTool(nativeTool, callClass) {
   if (nativeTool !== null && callClass === CallClass.BUILTIN) {
-    const scoped = GEMINI_TOOL_ALIASES[nativeTool];
+    const scoped = lookup(GEMINI_TOOL_ALIASES, nativeTool);
     if (scoped !== undefined) return scoped;
   }
   return canonicalTool(nativeTool);
@@ -178,8 +188,10 @@ export function parse(native) {
   const nativeEvent =
     typeof raw.hook_event_name === "string" ? raw.hook_event_name : "";
   const kind =
-    /** @type {Record<string, string>} */ (NATIVE_TO_KIND)[nativeEvent] ??
-    EventKind.UNKNOWN;
+    lookup(
+      /** @type {Record<string, string>} */ (NATIVE_TO_KIND),
+      nativeEvent,
+    ) ?? EventKind.UNKNOWN;
   const gating = kind === EventKind.PRE_TOOL || kind === EventKind.POST_TOOL;
   const response = kind === EventKind.POST_TOOL ? raw.tool_response : undefined;
   const nativeTool = gating ? asStringOrNull(raw.tool_name) : null;
@@ -216,13 +228,16 @@ 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 (no home
-  // in this stdout-only response), so no stdout body.
+  // 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.
   if (enforced)
     return nativeResponse({
       transport: INTEGRATION_MODE,
       exit_code: 2,
       enforced: true,
+      ...(vd.reason !== undefined ? { stderr: vd.reason } : {}),
     });
 
   const body =

package/src/control-plane.mjs

@@ -54,6 +54,9 @@ export const EventKind = Object.freeze({
   UNKNOWN: "unknown",
 });
 
+/** @type {Set<string>} the valid {@link EventKind} values, for membership checks. */
+const EVENT_KIND_VALUES = new Set(Object.values(EventKind));
+
 /** The normalized verdict decisions a guardrail can return. */
 export const Decision = Object.freeze({
   ALLOW: "allow",
@@ -127,7 +130,27 @@ assertAliasTargetsModeled(TOOL_ALIASES);
  */
 export function canonicalTool(tool) {
   if (typeof tool !== "string") return tool;
-  return /** @type {Record<string, string>} */ (TOOL_ALIASES)[tool] ?? tool;
+  return (
+    lookup(/** @type {Record<string, string>} */ (TOOL_ALIASES), tool) ?? tool
+  );
+}
+
+/**
+ * Own-property lookup on an object used as a string-keyed map. Returns the value
+ * ONLY when `key` is an OWN property; an inherited `Object.prototype` member
+ * (`constructor`, `toString`, `valueOf`, `__proto__`, `hasOwnProperty`, …) that
+ * an untrusted key could name resolves to `undefined`, never the prototype
+ * function. EVERY map keyed by an untrusted native string — a tool name, an
+ * agent id, a native event name — MUST resolve through this: a bare `map[key]`
+ * index lets a payload named after a prototype member resolve a JS function
+ * instead of falling through to the default, silently reclassifying the call.
+ * @template T
+ * @param {Record<string, T>} map
+ * @param {string} key
+ * @returns {T|undefined}
+ */
+export function lookup(map, key) {
+  return Object.hasOwn(map, key) ? map[key] : undefined;
 }
 
 /**
@@ -235,7 +258,11 @@ export function classifyCallClass(tool, native) {
   if (typeof tool === "string" && /^mcp__?[^_]/.test(tool))
     return CallClass.MCP;
   const ctx = native ? native.mcp_context : undefined;
-  if (ctx !== null && typeof ctx === "object") return CallClass.MCP;
+  // A plain object mcp_context is the MCP marker; an array is NOT (typeof [] is
+  // "object", so a bare typeof test over-classifies an array-valued field as MCP
+  // and silently downgrades a legitimate veto).
+  if (ctx !== null && typeof ctx === "object" && !Array.isArray(ctx))
+    return CallClass.MCP;
   return CallClass.BUILTIN;
 }
 
@@ -262,6 +289,7 @@ export function classifyCallClass(tool, native) {
  * @property {number} exit_code process exit code carrying the decision (0 = proceed)
  * @property {boolean} enforced whether THIS render actually blocks (false ⇒ advisory only)
  * @property {unknown} [stdout] native JSON body to write to stdout, when the transport uses one
+ * @property {string} [stderr] text the host reads from STDERR — the block reason on a transport (e.g. Gemini CLI's exit-2 System Block) that takes its rationale from stderr rather than the stdout body. The caller writes it to fd 2 before exiting.
  */
 
 /**
@@ -314,6 +342,20 @@ export function makeEvent({
   this_call_vetoable,
   meta,
 }) {
+  // Fail loud on an internally-malformed event: an adapter that hands makeEvent a
+  // typo'd event kind ("pre-tool") or a non-boolean vetoable flag would otherwise
+  // ship an event that downstream `switch(event)` and the `=== false` veto-honesty
+  // guard silently mis-handle (a non-boolean `this_call_vetoable` reads as
+  // vetoable — a fail-open seam). These are produced in-process, so a bad value is
+  // a bug, not untrusted input to tolerate.
+  if (!EVENT_KIND_VALUES.has(event))
+    throw new Error(
+      `control-plane: makeEvent got an unmodeled event kind ${JSON.stringify(event)} (use EventKind.UNKNOWN for an unmapped native event)`,
+    );
+  if (typeof this_call_vetoable !== "boolean")
+    throw new TypeError(
+      `control-plane: makeEvent this_call_vetoable must be a boolean, got ${typeof this_call_vetoable}`,
+    );
   /** @type {ToolCallEvent} */
   const evt = {
     schema_version: SCHEMA_VERSION,
@@ -359,6 +401,23 @@ export function normalizeVerdict(verdict) {
   return out;
 }
 
+/**
+ * Render an untrusted, rejected `decision` value for the clamp note. Prefers the
+ * JSON form (so a string reads back quoted, matching the note's contract) but
+ * falls back to `String(...)` for a value JSON cannot serialize — a BigInt would
+ * otherwise make `JSON.stringify` THROW, defeating the whole fail-to-ask purpose
+ * of the clamp on exactly the malformed input it exists to neutralize.
+ * @param {unknown} decision
+ * @returns {string}
+ */
+function stringifyRejected(decision) {
+  try {
+    return JSON.stringify(decision) ?? String(decision);
+  } catch {
+    return String(decision);
+  }
+}
+
 /**
  * Harden an UNTRUSTED {@link Verdict} — one authored by a separate
  * monitor/judge process (e.g. claude-guard's scrub-monitor-response) — before
@@ -437,7 +496,7 @@ export function sanitizeVerdict(verdict, sanitizeText) {
   if (!valid) {
     // The rejected value is itself untrusted text, so it is scrubbed before
     // being embedded in the clamp note.
-    const rejected = scrub("decision", JSON.stringify(decision) ?? "undefined");
+    const rejected = scrub("decision", stringifyRejected(decision));
     const note = `[control-plane: invalid verdict decision ${rejected} clamped to "ask"]`;
     out.reason = out.reason === undefined ? note : `${out.reason} ${note}`;
   }
@@ -499,10 +558,16 @@ export function asString(value, fallback) {
 /**
  * Assemble a {@link NativeResponse}, omitting an absent `stdout` so a pure
  * exit-code transport carries no `stdout` key.
- * @param {{ transport: string, exit_code: number, enforced: boolean, stdout?: unknown }} parts
+ * @param {{ transport: string, exit_code: number, enforced: boolean, stdout?: unknown, stderr?: string }} parts
  * @returns {NativeResponse}
  */
-export function nativeResponse({ transport, exit_code, enforced, stdout }) {
+export function nativeResponse({
+  transport,
+  exit_code,
+  enforced,
+  stdout,
+  stderr,
+}) {
   /** @type {NativeResponse} */
   const out = {
     transport: /** @type {NativeResponse["transport"]} */ (transport),
@@ -510,5 +575,6 @@ export function nativeResponse({ transport, exit_code, enforced, stdout }) {
     enforced,
   };
   if (stdout !== undefined) out.stdout = stdout;
+  if (stderr !== undefined) out.stderr = stderr;
   return out;
 }

package/src/fixtures/gemini.json

@@ -56,7 +56,8 @@
           "native": {
             "transport": "external_hook",
             "exit_code": 2,
-            "enforced": true
+            "enforced": true,
+            "stderr": "blocked destructive command"
           }
         },
         "ask": {
@@ -238,7 +239,8 @@
           "native": {
             "transport": "external_hook",
             "exit_code": 2,
-            "enforced": true
+            "enforced": true,
+            "stderr": "prompt requests credential exfiltration"
           }
         },
         "ask": {

package/src/registry.mjs

@@ -14,6 +14,7 @@
  * is no second spelling to reconcile.
  */
 
+import { lookup } from "./control-plane.mjs";
 import { claudeAdapter } from "./adapters/claude.mjs";
 import { codexAdapter } from "./adapters/codex.mjs";
 import { ampAdapter } from "./adapters/amp.mjs";
@@ -71,7 +72,7 @@ assertRegistryConsistent(ADAPTERS);
  * @returns {Adapter}
  */
 export function adapterFor(id) {
-  const adapter = ADAPTERS[id];
+  const adapter = lookup(ADAPTERS, id);
   if (adapter === undefined)
     throw new Error(
       `registry: no adapter for agent id ${JSON.stringify(id)} (known: ${AGENT_IDS.join(", ")})`,

package/types/adapters/codex.d.mts

@@ -3,6 +3,17 @@
  * `semver.coerce` normalizes a patch/prerelease/build-tagged version to its
  * 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.
  * @param {unknown} version
  * @returns {boolean}
  */

package/types/control-plane.d.mts

@@ -16,6 +16,21 @@ export function assertAliasTargetsModeled(aliases: Record<string, string>): void
  * @returns {string|null} the canonical name, or the native name verbatim
  */
 export function canonicalTool(tool: string | null): string | null;
+/**
+ * Own-property lookup on an object used as a string-keyed map. Returns the value
+ * ONLY when `key` is an OWN property; an inherited `Object.prototype` member
+ * (`constructor`, `toString`, `valueOf`, `__proto__`, `hasOwnProperty`, …) that
+ * an untrusted key could name resolves to `undefined`, never the prototype
+ * function. EVERY map keyed by an untrusted native string — a tool name, an
+ * agent id, a native event name — MUST resolve through this: a bare `map[key]`
+ * index lets a payload named after a prototype member resolve a JS function
+ * instead of falling through to the default, silently reclassifying the call.
+ * @template T
+ * @param {Record<string, T>} map
+ * @param {string} key
+ * @returns {T|undefined}
+ */
+export function lookup<T>(map: Record<string, T>, key: string): T | undefined;
 /**
  * Whether a coverage status PERMITS an adapter to mark a call in that class
  * `this_call_vetoable: true`. Only a hook confirmed to fire does: COVERED, or
@@ -70,6 +85,7 @@ export function classifyCallClass(tool: string | null, native?: Record<string, u
  * @property {number} exit_code process exit code carrying the decision (0 = proceed)
  * @property {boolean} enforced whether THIS render actually blocks (false ⇒ advisory only)
  * @property {unknown} [stdout] native JSON body to write to stdout, when the transport uses one
+ * @property {string} [stderr] text the host reads from STDERR — the block reason on a transport (e.g. Gemini CLI's exit-2 System Block) that takes its rationale from stderr rather than the stdout body. The caller writes it to fd 2 before exiting.
  */
 /**
  * A normalized, agent-agnostic view of one agent event.
@@ -188,14 +204,15 @@ export function asString(value: unknown, fallback: string): string;
 /**
  * Assemble a {@link NativeResponse}, omitting an absent `stdout` so a pure
  * exit-code transport carries no `stdout` key.
- * @param {{ transport: string, exit_code: number, enforced: boolean, stdout?: unknown }} parts
+ * @param {{ transport: string, exit_code: number, enforced: boolean, stdout?: unknown, stderr?: string }} parts
  * @returns {NativeResponse}
  */
-export function nativeResponse({ transport, exit_code, enforced, stdout }: {
+export function nativeResponse({ transport, exit_code, enforced, stdout, stderr, }: {
     transport: string;
     exit_code: number;
     enforced: boolean;
     stdout?: unknown;
+    stderr?: string;
 }): NativeResponse;
 /**
  * The vendor-neutral control-plane contract.
@@ -379,6 +396,10 @@ export type NativeResponse = {
      * native JSON body to write to stdout, when the transport uses one
      */
     stdout?: unknown;
+    /**
+     * text the host reads from STDERR — the block reason on a transport (e.g. Gemini CLI's exit-2 System Block) that takes its rationale from stderr rather than the stdout body. The caller writes it to fd 2 before exiting.
+     */
+    stderr?: string | undefined;
 };
 /**
  * A normalized, agent-agnostic view of one agent event.