agent-control-plane-core 0.5.3 → 0.6.0

package/README.md

@@ -28,10 +28,11 @@ removes.
   (a tool about to run, a tool that just ran, a prompt, a session start).
 - **`Verdict`** — one normalized way to say what your guardrail decided:
   `allow` / `deny` / `ask`, optionally with a rewritten input or extra context.
-- **Adapters** — a thin `{ parse, render }` translator per agent. `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).
+- **Adapters** — a thin `{ parse, render }` translator per agent, plus the
+  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).
 
 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.
@@ -90,13 +91,35 @@ pnpm add agent-control-plane-core
 }
 ```
 
-An **Adapter** is a pair `{ AGENT, parse, render }`:
+An **Adapter** is `{ AGENT, COVERAGE, UNRENDERED_FIELDS, parse, render }`:
 
 ```js
 parse(nativeEvent) -> ToolCallEvent      // never throws on unknown input
 render(verdict, event) -> nativeResponse // the agent's native shape
+
+// Which Verdict content fields this host has NO native channel for, per event
+// kind. Every EventKind needs a row: an omission would read as "every field
+// reaches a channel here", which is the reverse of the truth on a transport
+// that carries none.
+UNRENDERED_FIELDS = Object.freeze({
+  [EventKind.PRE_TOOL]: readonlySet(["mutated_output"]),
+  [EventKind.POST_TOOL]: readonlySet(["mutated_output"]),
+  [EventKind.PROMPT_SUBMIT]: UNRENDERED_ON_UNKNOWN,
+  [EventKind.SESSION_START]: UNRENDERED_ON_UNKNOWN,
+  [EventKind.UNKNOWN]: UNRENDERED_ON_UNKNOWN,
+})
 ```
 
+`readonlySet([])` is the row for a kind that carries all three;
+`UNRENDERED_ON_UNKNOWN` is the row for one that carries none. Both come from
+`agent-control-plane-core/contract`. Build every row with `readonlySet` — a
+plain `Set` exposes `clear()`, so a consumer could empty a declaration after
+conformance certified it, and `Object.freeze` does not stop that. Freeze the map
+itself too: an immutable row still leaves a consumer free to swap a whole row
+for one claiming another channel. A render that ships a field the row
+declares dropped fails conformance, and so does a row that declares a channel
+the render does not carry.
+
 ## Usage
 
 ```js
@@ -167,7 +190,13 @@ 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
+4. Every `Verdict` content field either reaches this host's wire or is declared
+   in `UNRENDERED_FIELDS` for that event kind, checked both ways on a
+   synthesized verdict — so an adapter with no channel for a field must say so,
+   and a declared drop that still ships the value fails. Set the optional
+   `NATIVE_EVENT_FOR` to have a kind your fixtures skip probed on its real
+   native event rather than on your unrecognized-event branch.
+5. 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

package/bin/codex-hook.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 /**
- * Codex CLI EXTERNAL_HOOK entry. Reads a native PreToolUse/PermissionRequest
- * payload on stdin, applies the demo judge, and emits Codex's native response.
+ * Codex CLI EXTERNAL_HOOK entry. Reads a native
+ * PreToolUse/PermissionRequest/PostToolUse payload on stdin, applies the demo
+ * judge, and emits Codex's native response.
  *
  * 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

package/package.json

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

@@ -8,7 +8,8 @@
  *
  * This adapter is what proves the transport split earns its keep: the normalized
  * ToolCallEvent/Verdict are identical to Claude's, but `render` carries the
- * decision in `exit_code` with no `stdout` at all.
+ * decision in `exit_code` with no `stdout` at all. An enforced deny's `reason`
+ * goes to the helper's STDERR, which Amp surfaces.
  */
 
 import {
@@ -25,15 +26,21 @@ import {
   makeEvent,
   normalizeVerdict,
   nativeResponse,
-  collectPassthrough,
+  readonlySet,
+  VERDICT_CONTENT_FIELDS,
+  baseMeta,
   asObject,
   asStringOrNull,
 } from "../control-plane.mjs";
 
 /** @typedef {import("../control-plane.mjs").ToolCallEvent} ToolCallEvent */
 /** @typedef {import("../control-plane.mjs").Verdict} Verdict */
-/** @typedef {import("../control-plane.mjs").EventMeta} EventMeta */
 /** @typedef {import("../control-plane.mjs").NativeResponse} NativeResponse */
+// Re-exported on this subpath even though no signature below names it:
+// tsc turns each @typedef into an `export type` in the generated .d.mts,
+// so dropping this line breaks `import type { EventMeta } from "…/<agent>"`
+// for every TypeScript consumer.
+/** @typedef {import("../control-plane.mjs").EventMeta} EventMeta */
 
 export const AGENT = "amp";
 export const INTEGRATION_MODE = IntegrationMode.EXTERNAL_HOOK;
@@ -45,6 +52,23 @@ export const INTEGRATION_MODE = IntegrationMode.EXTERNAL_HOOK;
  * gates calls inside subagents — so builtin, MCP, and subagent are all COVERED.
  * Resumed-thread firing is a strong-but-uncited structural argument, so it is
  * held at UNKNOWN until an item-⑤ probe confirms it.
+ *
+ * That UNKNOWN is this adapter's own fail-closed reading, NOT a transcription of
+ * the matrix cell, which reads `✅ struct. [A4]` — COVERED, on evidence the
+ * `struct.` suffix marks as uncited. A cell is a CEILING: an adapter may never
+ * claim more than it, but declaring LESS is always safe, since every step down
+ * degrades a deny toward notify. This row takes that conservative option until a
+ * probe cites it; Claude's takes the cell at face value on the same class of
+ * argument. The difference is free today, for the reason below.
+ *
+ * The row is DECLARATIVE ONLY either way: no host marks a lone tool event as
+ * belonging to a resumed session, so {@link classifyCallClass} never returns
+ * RESUMED and `parse` never reads the entry — a call in a resumed thread is
+ * classified by its TOOL, BUILTIN or MCP, and both are COVERED, so it parses
+ * vetoable. (The SUBAGENT row is reachable — the classifier answers it for a
+ * payload carrying `agent_type` — but Amp's subagent coverage is COVERED too,
+ * so it changes nothing here either.) The entry is there for a consumer reading
+ * COVERAGE directly, and becomes load-bearing only once a signal exists.
  */
 /** @type {import("../control-plane.mjs").CoverageMap} */
 export const COVERAGE = Object.freeze({
@@ -62,11 +86,44 @@ export const COVERAGE = Object.freeze({
  * after `assertGatedKinds` has already run.
  */
 const GATED_EVENTS = Object.freeze(new Set([EventKind.PRE_TOOL]));
+
+/**
+ * The native event a conformance probe should carry for each kind — this
+ * adapter's own answer, so an every-kind probe exercises the branch that kind
+ * really takes. Amp's observer names every event `delegate` and reaches no
+ * other kind.
+ * @type {Record<string, string|undefined>}
+ */
+export const NATIVE_EVENT_FOR = Object.freeze({
+  [EventKind.PRE_TOOL]: "delegate",
+});
 assertGatedKinds(GATED_EVENTS, AGENT);
 
+/**
+ * Which {@link VERDICT_CONTENT_FIELDS} have no native channel, so `render`
+ * drops them. Amp's transport is the exit code and nothing else — there is no
+ * stdout body to carry a replacement input, a replacement output or extra
+ * context, so ALL THREE are dropped on every kind. A guardrail that needs any of
+ * them cannot use Amp as its only integration. `reason` is not one of them and
+ * is NOT dropped: an enforced deny writes it to the helper's stderr, which Amp
+ * surfaces (see {@link render}). Built over every
+ * {@link EventKind} rather than the one `parse` emits: a row this adapter cannot
+ * reach is still the honest answer for a caller that asks.
+ * @type {Record<string, ReadonlySet<string>|undefined>}
+ */
+export const UNRENDERED_FIELDS = Object.freeze(
+  Object.fromEntries(
+    Object.values(EventKind).map((kind) => [
+      kind,
+      readonlySet(VERDICT_CONTENT_FIELDS),
+    ]),
+  ),
+);
+
 // 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"]);
+// input. The session context is the STANDARD_META_FIELDS set `baseMeta`
+// consumes, so it is not listed here. Pinned by fixtures/amp.json.
+const CONSUMED = new Set(["tool", "input"]);
 
 /**
  * @param {any} native
@@ -74,16 +131,14 @@ const CONSUMED = new Set(["tool", "input", "session_id", "cwd"]);
  */
 export function parse(native) {
   const raw = asObject(native);
-  /** @type {EventMeta} */
-  const meta = {
+  const meta = baseMeta({
     agent: AGENT,
     native_event: "delegate",
     integration_mode: INTEGRATION_MODE,
     primary_gate_present: true,
-    passthrough: collectPassthrough(raw, CONSUMED),
-  };
-  if (typeof raw.session_id === "string") meta.session_id = raw.session_id;
-  if (typeof raw.cwd === "string") meta.cwd = raw.cwd;
+    native: raw,
+    consumed: CONSUMED,
+  });
   const nativeTool = asStringOrNull(raw.tool);
   if (nativeTool !== null) meta.native_tool = nativeTool;
   return makeEvent({
@@ -146,10 +201,14 @@ for (const decision of Object.values(Decision)) {
 
 /**
  * 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
- * (Amp surfaces the helper's own stderr). No `soleGate` option — an allow
- * already renders as exit 0 either way, so there's no distinct "real approve"
- * signal for this transport to opt into.
+ * with no stdout body. An ENFORCED deny also carries its `reason` on
+ * `NativeResponse.stderr`, which `emit` writes to fd 2: the delegate is a PATH
+ * helper whose stderr Amp surfaces, and this render is what that helper writes,
+ * so a block that reached the user with no rationale was the adapter throwing
+ * the reason away. Only the enforced path — a deny this call cannot veto and an
+ * ask have blocked nothing, and `stderr` is the contract's block-reason channel.
+ * No `soleGate` option — an allow already renders as exit 0 either way, so
+ * there's no distinct "real approve" signal for this transport to opt into.
  * @param {Verdict} verdict
  * @param {ToolCallEvent} event
  * @returns {NativeResponse}
@@ -178,8 +237,21 @@ export function render(verdict, event) {
     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 });
+  return nativeResponse({
+    transport: INTEGRATION_MODE,
+    exit_code,
+    enforced,
+    ...(enforced && vd.reason !== undefined ? { stderr: vd.reason } : {}),
+  });
 }
 
 /** @type {import("../control-plane.mjs").Adapter} */
-export const ampAdapter = { AGENT, INTEGRATION_MODE, COVERAGE, parse, render };
+export const ampAdapter = {
+  AGENT,
+  INTEGRATION_MODE,
+  COVERAGE,
+  UNRENDERED_FIELDS,
+  NATIVE_EVENT_FOR,
+  parse,
+  render,
+};

package/src/adapters/claude.mjs

@@ -26,7 +26,9 @@ import {
   makeEvent,
   normalizeVerdict,
   nativeResponse,
-  collectPassthrough,
+  UNRENDERED_ON_UNKNOWN,
+  readonlySet,
+  baseMeta,
   asObject,
   asString,
   asStringOrNull,
@@ -34,8 +36,12 @@ import {
 
 /** @typedef {import("../control-plane.mjs").ToolCallEvent} ToolCallEvent */
 /** @typedef {import("../control-plane.mjs").Verdict} Verdict */
-/** @typedef {import("../control-plane.mjs").EventMeta} EventMeta */
 /** @typedef {import("../control-plane.mjs").NativeResponse} NativeResponse */
+// Re-exported on this subpath even though no signature below names it:
+// tsc turns each @typedef into an `export type` in the generated .d.mts,
+// so dropping this line breaks `import type { EventMeta } from "…/<agent>"`
+// for every TypeScript consumer.
+/** @typedef {import("../control-plane.mjs").EventMeta} EventMeta */
 
 /** Producing-agent id stamped onto every event this adapter parses. */
 export const AGENT = "claude";
@@ -48,7 +54,13 @@ export const INTEGRATION_MODE = IntegrationMode.EXTERNAL_HOOK;
  * for builtins, for MCP tools (surfaced as `mcp__<server>__<tool>` through the
  * same hook), and for every tool a subagent uses (subagents do not inherit the
  * parent's permissions, so the hook is often their only gate). Resumed sessions
- * re-read hooks from settings and fire per new call — structural, uncontested.
+ * re-read hooks from settings and fire per new call — `✅ struct. [C4]`, where
+ * the `struct.` suffix marks the status as uncited: no source addresses resumed
+ * sessions directly, and COVERED is an inference from the reload mechanism. This
+ * row takes the cell at face value. Amp holds the equivalent row at UNKNOWN,
+ * which the matrix permits — a cell is a ceiling, and declaring less coverage
+ * than it is always the safe direction. Both are free today, since
+ * `classifyCallClass` never returns RESUMED and no call is judged by this entry.
  */
 /** @type {import("../control-plane.mjs").CoverageMap} */
 export const COVERAGE = Object.freeze({
@@ -72,6 +84,36 @@ const GATED_EVENTS = Object.freeze(
 );
 assertGatedKinds(GATED_EVENTS, AGENT);
 
+// The kinds whose only content channel is context: the tool has already run
+// (or there is no tool), so neither an input nor an output replacement has
+// anywhere to go.
+const CONTEXT_ONLY = readonlySet(["mutated_input", "mutated_output"]);
+
+/**
+ * Which {@link VERDICT_CONTENT_FIELDS} have no native channel on each event
+ * kind, so `render` drops them. Claude Code splits its content channels by
+ * event: `updatedInput` exists only on PreToolUse (the call has not run yet),
+ * and `updatedToolOutput` only on PostToolUse (there is no tool output to
+ * replace anywhere else). `additionalContext` is the one channel every kind
+ * carries. The conformance harness holds this to what `render` actually emits,
+ * in both directions.
+ *
+ * `additionalContext` on PreToolUse is inherited behaviour, not a checked claim:
+ * Claude Code documents the field for UserPromptSubmit, SessionStart and
+ * PostToolUse, and this adapter has emitted it on PreToolUse since before the
+ * declaration existed. Rule ⑩ can see that the value reaches the wire, never
+ * that the host reads the key — confirm it against the hook reference before
+ * relying on it.
+ * @type {Record<string, ReadonlySet<string>|undefined>}
+ */
+export const UNRENDERED_FIELDS = Object.freeze({
+  [EventKind.PRE_TOOL]: readonlySet(["mutated_output"]),
+  [EventKind.POST_TOOL]: readonlySet(["mutated_input"]),
+  [EventKind.PROMPT_SUBMIT]: CONTEXT_ONLY,
+  [EventKind.SESSION_START]: CONTEXT_ONLY,
+  [EventKind.UNKNOWN]: UNRENDERED_ON_UNKNOWN,
+});
+
 /** Claude Code native hook event names (the `hook_event_name` field). */
 export const HookEvent = Object.freeze({
   PRE_TOOL_USE: "PreToolUse",
@@ -94,12 +136,17 @@ const KIND_TO_NATIVE = Object.freeze({
   [EventKind.SESSION_START]: HookEvent.SESSION_START,
 });
 
+/**
+ * The native event a conformance probe should carry for each kind — this
+ * adapter's own answer, so an every-kind probe exercises the branch that kind
+ * really takes. `unknown` has no native name by definition and is absent.
+ * @type {Record<string, string|undefined>}
+ */
+export const NATIVE_EVENT_FOR = KIND_TO_NATIVE;
+
+// The STANDARD_META_FIELDS are consumed by `baseMeta`, not listed here.
 const CONSUMED = new Set([
   "hook_event_name",
-  "session_id",
-  "cwd",
-  "permission_mode",
-  "transcript_path",
   "tool_name",
   "tool_input",
   "tool_response",
@@ -129,29 +176,6 @@ function claudeTool(kind, raw) {
   return asStringOrNull(raw.tool_name);
 }
 
-/**
- * @param {string} nativeEvent
- * @param {Record<string, unknown>} raw
- * @returns {EventMeta}
- */
-function claudeMeta(nativeEvent, raw) {
-  /** @type {EventMeta} */
-  const meta = {
-    agent: AGENT,
-    native_event: nativeEvent,
-    integration_mode: INTEGRATION_MODE,
-    primary_gate_present: true,
-    passthrough: collectPassthrough(raw, CONSUMED),
-  };
-  if (typeof raw.session_id === "string") meta.session_id = raw.session_id;
-  if (typeof raw.cwd === "string") meta.cwd = raw.cwd;
-  if (typeof raw.permission_mode === "string")
-    meta.permission_mode = raw.permission_mode;
-  if (typeof raw.transcript_path === "string")
-    meta.transcript_path = raw.transcript_path;
-  return meta;
-}
-
 /**
  * Parse a raw Claude Code hook payload into a normalized {@link ToolCallEvent}.
  * Never throws on an unmodelled event type or tool-input field.
@@ -168,7 +192,14 @@ export function parse(native) {
     ) ?? EventKind.UNKNOWN;
   const response = kind === EventKind.POST_TOOL ? raw.tool_response : undefined;
   const nativeTool = claudeTool(kind, raw);
-  const meta = claudeMeta(nativeEvent, raw);
+  const meta = baseMeta({
+    agent: AGENT,
+    native_event: nativeEvent,
+    integration_mode: INTEGRATION_MODE,
+    primary_gate_present: true,
+    native: raw,
+    consumed: CONSUMED,
+  });
   if (nativeTool !== null) meta.native_tool = nativeTool;
   return makeEvent({
     event: kind,
@@ -215,7 +246,7 @@ export function render(verdict, event, { soleGate = false } = {}) {
   const stdout =
     kind === EventKind.PRE_TOOL
       ? gatingBody(hookEventName, vd, soleGate)
-      : nonGatingBody(hookEventName, vd);
+      : nonGatingBody(hookEventName, kind, vd);
 
   return nativeResponse({
     transport: INTEGRATION_MODE,
@@ -253,18 +284,24 @@ function gatingBody(hookEventName, vd, soleGate) {
 
 /**
  * @param {string} hookEventName
+ * @param {string} kind the normalized {@link EventKind} being rendered
  * @param {Verdict} vd
  * @returns {Record<string, unknown>}
  */
-function nonGatingBody(hookEventName, vd) {
+function nonGatingBody(hookEventName, kind, vd) {
   /** @type {Record<string, unknown>} */
   const hookSpecificOutput = { hookEventName };
   // A PostToolUse content transform: `updatedToolOutput` replaces what the model
   // sees (the tool already ran, so this governs only the model's view). The
-  // native channel for the whole redaction/sanitize pipeline.
-  if (vd.mutated_output !== undefined)
+  // native channel for the whole redaction/sanitize pipeline. PostToolUse ONLY:
+  // a UserPromptSubmit or SessionStart carries no tool output, so the field is
+  // dropped there (declared in {@link UNRENDERED_FIELDS}) rather than emitted
+  // into a key the host ignores, which reads to a caller as a redaction applied.
+  if (kind === EventKind.POST_TOOL && vd.mutated_output !== undefined)
     hookSpecificOutput.updatedToolOutput = vd.mutated_output;
-  if (vd.additional_context !== undefined)
+  // Not on an UNKNOWN kind: `hookEventName` there is the unrecognized native
+  // event name, so the adapter has established no channel to write into.
+  if (kind !== EventKind.UNKNOWN && vd.additional_context !== undefined)
     hookSpecificOutput.additionalContext = vd.additional_context;
   /** @type {Record<string, unknown>} */
   const out = { hookSpecificOutput };
@@ -280,6 +317,8 @@ export const claudeAdapter = {
   AGENT,
   INTEGRATION_MODE,
   COVERAGE,
+  UNRENDERED_FIELDS,
+  NATIVE_EVENT_FOR,
   parse,
   render,
 };