agent-control-plane-core 0.1.0

package/src/adapters/claude.mjs

@@ -0,0 +1,227 @@
+/**
+ * The Claude Code adapter — reference EXTERNAL_HOOK translator.
+ *
+ * The ONLY module that knows Claude Code's native hook field names
+ * (`hook_event_name`, `tool_name`, `tool_input`, `tool_response`, `prompt`,
+ * `permissionDecision`, `hookSpecificOutput`). Transport is external-hook: the
+ * agent shells out with stdin JSON and reads a deny body / exit code back.
+ *
+ * Deny signal (PreToolUse): `hookSpecificOutput.permissionDecision = "deny"`
+ * AND exit 2. this_call_vetoable is true, but per the doctrine that is a
+ * useful FIRST filter, never the boundary — the Verdict stays advisory to the
+ * sandbox.
+ */
+
+import {
+  EventKind,
+  Decision,
+  IntegrationMode,
+  makeEvent,
+  normalizeVerdict,
+  nativeResponse,
+  collectPassthrough,
+  asObject,
+  asString,
+  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 */
+
+/** Producing-agent id stamped onto every event this adapter parses. */
+export const AGENT = "claude";
+
+/** How this adapter attaches to the agent. */
+export const INTEGRATION_MODE = IntegrationMode.EXTERNAL_HOOK;
+
+/** Claude Code native hook event names (the `hook_event_name` field). */
+export const HookEvent = Object.freeze({
+  PRE_TOOL_USE: "PreToolUse",
+  POST_TOOL_USE: "PostToolUse",
+  USER_PROMPT_SUBMIT: "UserPromptSubmit",
+  SESSION_START: "SessionStart",
+});
+
+const NATIVE_TO_KIND = Object.freeze({
+  [HookEvent.PRE_TOOL_USE]: EventKind.PRE_TOOL,
+  [HookEvent.POST_TOOL_USE]: EventKind.POST_TOOL,
+  [HookEvent.USER_PROMPT_SUBMIT]: EventKind.PROMPT_SUBMIT,
+  [HookEvent.SESSION_START]: EventKind.SESSION_START,
+});
+
+const KIND_TO_NATIVE = Object.freeze({
+  [EventKind.PRE_TOOL]: HookEvent.PRE_TOOL_USE,
+  [EventKind.POST_TOOL]: HookEvent.POST_TOOL_USE,
+  [EventKind.PROMPT_SUBMIT]: HookEvent.USER_PROMPT_SUBMIT,
+  [EventKind.SESSION_START]: HookEvent.SESSION_START,
+});
+
+const CONSUMED = new Set([
+  "hook_event_name",
+  "session_id",
+  "cwd",
+  "permission_mode",
+  "transcript_path",
+  "tool_name",
+  "tool_input",
+  "tool_response",
+  "prompt",
+]);
+
+/**
+ * @param {string} kind
+ * @param {Record<string, unknown>} raw
+ * @returns {Record<string, unknown>}
+ */
+function claudeInput(kind, raw) {
+  if (kind === EventKind.PROMPT_SUBMIT)
+    return { prompt: asString(raw.prompt, "") };
+  if (kind === EventKind.SESSION_START) return {};
+  return asObject(raw.tool_input);
+}
+
+/**
+ * @param {string} kind
+ * @param {Record<string, unknown>} raw
+ * @returns {string|null}
+ */
+function claudeTool(kind, raw) {
+  if (kind === EventKind.PROMPT_SUBMIT || kind === EventKind.SESSION_START)
+    return null;
+  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.
+ * @param {any} native
+ * @returns {ToolCallEvent}
+ */
+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;
+  const response = kind === EventKind.POST_TOOL ? raw.tool_response : undefined;
+  return makeEvent({
+    event: kind,
+    tool: claudeTool(kind, raw),
+    input: claudeInput(kind, raw),
+    response,
+    this_call_vetoable: true,
+    meta: claudeMeta(nativeEvent, raw),
+  });
+}
+
+/**
+ * Render into Claude Code's native external-hook transport: a
+ * `hookSpecificOutput` JSON body on stdout plus the exit code that carries the
+ * decision (deny ⇒ exit 2). A deny only counts as `enforced` when the event's
+ * `this_call_vetoable` holds.
+ *
+ * `soleGate` (default `false`) is a dangerous, explicit opt-in: when `true` AND
+ * the verdict is `allow`, the render emits Claude Code's REAL
+ * `permissionDecision: "allow"`, which bypasses the native permission prompt.
+ * Default behavior always abstains on allow (see {@link gatingBody}) so the
+ * guardrail can never silently become the sole gate by accident.
+ * @param {Verdict} verdict
+ * @param {ToolCallEvent} event
+ * @param {{ soleGate?: boolean }} [options]
+ * @returns {NativeResponse}
+ */
+export function render(verdict, event, { soleGate = false } = {}) {
+  const vd = normalizeVerdict(verdict);
+  const kind = event.event;
+  const hookEventName =
+    /** @type {Record<string, string>} */ (KIND_TO_NATIVE)[kind] ??
+    event.meta.native_event;
+  const isDeny = vd.decision === Decision.DENY;
+  const enforced = isDeny && event.this_call_vetoable;
+
+  /** @type {Record<string, unknown>} */
+  const stdout =
+    kind === EventKind.PRE_TOOL
+      ? gatingBody(hookEventName, vd, soleGate)
+      : nonGatingBody(hookEventName, vd);
+
+  return nativeResponse({
+    transport: INTEGRATION_MODE,
+    exit_code: enforced ? 2 : 0,
+    enforced,
+    stdout,
+  });
+}
+
+/**
+ * Build a PreToolUse `hookSpecificOutput`. `allow` OMITS `permissionDecision`
+ * by default — in Claude Code that field auto-approves the call, bypassing the
+ * normal permission prompt, so a guardrail that merely has "no objection" must
+ * stay silent on it and let the default flow run. Only `deny`/`ask` emit an
+ * explicit `permissionDecision`, UNLESS `soleGate` is true, in which case an
+ * `allow` also emits the real `permissionDecision: "allow"` (the monitor-as-
+ * sole-gate opt-in). `updatedInput`/`additionalContext` ride along regardless.
+ * @param {string} hookEventName
+ * @param {Verdict} vd
+ * @param {boolean} soleGate
+ * @returns {Record<string, unknown>}
+ */
+function gatingBody(hookEventName, vd, soleGate) {
+  /** @type {Record<string, unknown>} */
+  const out = { hookEventName };
+  if (vd.decision !== Decision.ALLOW || soleGate) {
+    out.permissionDecision = vd.decision;
+    if (vd.reason !== undefined) out.permissionDecisionReason = vd.reason;
+  }
+  if (vd.mutated_input !== undefined) out.updatedInput = vd.mutated_input;
+  if (vd.additional_context !== undefined)
+    out.additionalContext = vd.additional_context;
+  return { hookSpecificOutput: out };
+}
+
+/**
+ * @param {string} hookEventName
+ * @param {Verdict} vd
+ * @returns {Record<string, unknown>}
+ */
+function nonGatingBody(hookEventName, vd) {
+  /** @type {Record<string, unknown>} */
+  const hookSpecificOutput = { hookEventName };
+  if (vd.additional_context !== undefined)
+    hookSpecificOutput.additionalContext = vd.additional_context;
+  /** @type {Record<string, unknown>} */
+  const out = { hookSpecificOutput };
+  if (vd.decision !== Decision.ALLOW) {
+    out.decision = "block";
+    if (vd.reason !== undefined) out.reason = vd.reason;
+  }
+  return out;
+}
+
+/** @type {import("../control-plane.mjs").Adapter} */
+export const claudeAdapter = { AGENT, INTEGRATION_MODE, parse, render };

package/src/adapters/codex.mjs

@@ -0,0 +1,149 @@
+/**
+ * The Codex CLI adapter — EXTERNAL_HOOK translator (≥ v0.135).
+ *
+ * Real Codex speaks nearly the same protocol as Claude Code: `PreToolUse` and
+ * `PermissionRequest` hook events with `tool_name`/`tool_input`, and a deny
+ * expressed as `hookSpecificOutput.permissionDecision = "deny"` plus exit 2.
+ * Managed pin: /etc/codex/requirements.toml + allow_managed_hooks_only.
+ *
+ * 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.
+ */
+
+import {
+  EventKind,
+  Decision,
+  IntegrationMode,
+  makeEvent,
+  normalizeVerdict,
+  nativeResponse,
+  collectPassthrough,
+  asObject,
+  asString,
+  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 */
+
+export const AGENT = "codex";
+export const INTEGRATION_MODE = IntegrationMode.EXTERNAL_HOOK;
+
+/** Minimum Codex version whose hook can actually veto a tool call. */
+export const MIN_ENFORCING_VERSION = Object.freeze([0, 135]);
+
+// Both native events gate a tool call; PermissionRequest is the ask-tier veto.
+const GATING_EVENTS = new Set(["PreToolUse", "PermissionRequest"]);
+
+const CONSUMED = new Set([
+  "hook_event_name",
+  "session_id",
+  "cwd",
+  "permission_mode",
+  "transcript_path",
+  "tool_name",
+  "tool_input",
+  "version",
+]);
+
+/**
+ * True when `version` ("0.135.0") is at or above {@link MIN_ENFORCING_VERSION}.
+ * A missing/garbage version is treated as too old (fail closed to advisory).
+ * @param {unknown} version
+ * @returns {boolean}
+ */
+export function canEnforce(version) {
+  const parts = asString(version, "").split(".");
+  const major = Number(parts[0]);
+  const minor = Number(parts[1]);
+  if (!Number.isInteger(major) || !Number.isInteger(minor)) return false;
+  if (major !== MIN_ENFORCING_VERSION[0])
+    return major > MIN_ENFORCING_VERSION[0];
+  return minor >= MIN_ENFORCING_VERSION[1];
+}
+
+/**
+ * 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.
+ * @param {any} native
+ * @returns {ToolCallEvent}
+ */
+export function parse(native) {
+  const raw = asObject(native);
+  const nativeEvent = asString(raw.hook_event_name, "");
+  const gating = GATING_EVENTS.has(nativeEvent);
+  const kind = gating ? EventKind.PRE_TOOL : EventKind.UNKNOWN;
+  const enforce = canEnforce(raw.version);
+
+  /** @type {EventMeta} */
+  const meta = {
+    agent: AGENT,
+    native_event: nativeEvent,
+    integration_mode: enforce
+      ? IntegrationMode.EXTERNAL_HOOK
+      : IntegrationMode.OBSERVE_ONLY,
+    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 makeEvent({
+    event: kind,
+    tool: asStringOrNull(raw.tool_name),
+    input: asObject(raw.tool_input),
+    response: undefined,
+    this_call_vetoable: enforce,
+    meta,
+  });
+}
+
+/**
+ * Render into Codex's native external-hook transport: a `hookSpecificOutput`
+ * body preserving the native event name (`PreToolUse`/`PermissionRequest`) plus
+ * exit 2 on an enforceable deny. On a pre-v0.135 Codex (`this_call_vetoable`
+ * false) the body still renders but exit stays 0 and `enforced` is false —
+ * advisory only.
+ *
+ * `soleGate` (default `false`) is the same dangerous, explicit opt-in as the
+ * Claude adapter: when `true` AND the verdict is `allow`, the render emits the
+ * real `permissionDecision: "allow"` instead of abstaining.
+ * @param {Verdict} verdict
+ * @param {ToolCallEvent} event
+ * @param {{ soleGate?: boolean }} [options]
+ * @returns {NativeResponse}
+ */
+export function render(verdict, event, { soleGate = false } = {}) {
+  const vd = normalizeVerdict(verdict);
+  const enforced = vd.decision === Decision.DENY && event.this_call_vetoable;
+  const hookEventName = event.meta.native_event || "PreToolUse";
+
+  // As in the Claude adapter, `allow` omits permissionDecision by default so the
+  // guardrail never auto-approves a call it merely had no objection to; only
+  // deny/ask emit an explicit decision, unless `soleGate` opts into it.
+  /** @type {Record<string, unknown>} */
+  const body = { hookEventName };
+  if (vd.decision !== Decision.ALLOW || soleGate) {
+    body.permissionDecision = vd.decision;
+    if (vd.reason !== undefined) body.permissionDecisionReason = vd.reason;
+  }
+  if (vd.mutated_input !== undefined) body.updatedInput = vd.mutated_input;
+
+  return nativeResponse({
+    transport: event.meta.integration_mode,
+    exit_code: enforced ? 2 : 0,
+    enforced,
+    stdout: { hookSpecificOutput: body },
+  });
+}
+
+/** @type {import("../control-plane.mjs").Adapter} */
+export const codexAdapter = { AGENT, INTEGRATION_MODE, parse, render };

package/src/adapters/gemini.mjs

@@ -0,0 +1,175 @@
+/**
+ * The Gemini CLI adapter — EXTERNAL_HOOK translator (hooks since v0.26.0).
+ *
+ * The only module that knows Gemini CLI's native hook field names. Transport is
+ * external-hook: the agent shells out with stdin JSON and reads a stdout body +
+ * exit code back, but the vocabulary differs from Claude/Codex — the pre-tool
+ * event is `BeforeTool` (not `PreToolUse`), tool names are snake_case
+ * (`run_shell_command`), and the decision body is `{ decision, reason,
+ * hookSpecificOutput: { tool_input } }` rather than `permissionDecision`.
+ *
+ * Decision channel (from geminicli.com/docs/hooks/reference): exit 0 → stdout is
+ * 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.
+ */
+
+import {
+  EventKind,
+  Decision,
+  IntegrationMode,
+  makeEvent,
+  normalizeVerdict,
+  nativeResponse,
+  collectPassthrough,
+  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 */
+
+export const AGENT = "gemini";
+export const INTEGRATION_MODE = IntegrationMode.EXTERNAL_HOOK;
+
+/** Gemini CLI native hook event names (the `hook_event_name` field). */
+export const HookEvent = Object.freeze({
+  BEFORE_TOOL: "BeforeTool",
+  AFTER_TOOL: "AfterTool",
+});
+
+const NATIVE_TO_KIND = Object.freeze({
+  [HookEvent.BEFORE_TOOL]: EventKind.PRE_TOOL,
+  [HookEvent.AFTER_TOOL]: EventKind.POST_TOOL,
+});
+
+// Only the fields the adapter maps are consumed; everything else (timestamp,
+// mcp_context, original_request_name, …) survives verbatim in meta.passthrough.
+const CONSUMED = new Set([
+  "hook_event_name",
+  "session_id",
+  "cwd",
+  "transcript_path",
+  "tool_name",
+  "tool_input",
+  "tool_response",
+]);
+
+/**
+ * @param {string} nativeEvent
+ * @param {Record<string, unknown>} raw
+ * @returns {EventMeta}
+ */
+function geminiMeta(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.transcript_path === "string")
+    meta.transcript_path = raw.transcript_path;
+  return meta;
+}
+
+/**
+ * Parse a raw Gemini CLI hook payload into a normalized {@link ToolCallEvent}.
+ * Never throws on an unmodelled event type or tool-input field. Any payload we
+ * receive comes from a hooks-capable Gemini (v0.26.0+) whose `BeforeTool` can
+ * pre-empt via exit 2, so `this_call_vetoable` is true.
+ * @param {any} native
+ * @returns {ToolCallEvent}
+ */
+export function parse(native) {
+  const raw = asObject(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;
+  const gating = kind === EventKind.PRE_TOOL || kind === EventKind.POST_TOOL;
+  const response = kind === EventKind.POST_TOOL ? raw.tool_response : undefined;
+  return makeEvent({
+    event: kind,
+    tool: gating ? asStringOrNull(raw.tool_name) : null,
+    input: gating ? asObject(raw.tool_input) : {},
+    response,
+    this_call_vetoable: true,
+    meta: geminiMeta(nativeEvent, raw),
+  });
+}
+
+/**
+ * Render into Gemini CLI's native external-hook transport. An enforceable deny
+ * renders as exit 2 (the System Block); everything else exits 0 with a JSON
+ * decision body (or none, when `allow` abstains). `soleGate` (default false) is
+ * the same dangerous opt-in as the other adapters: it makes an `allow` emit the
+ * real `decision: "allow"` instead of abstaining.
+ * @param {Verdict} verdict
+ * @param {ToolCallEvent} event
+ * @param {{ soleGate?: boolean }} [options]
+ * @returns {NativeResponse}
+ */
+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.
+  if (enforced)
+    return nativeResponse({
+      transport: INTEGRATION_MODE,
+      exit_code: 2,
+      enforced: true,
+    });
+
+  const body = decisionBody(vd, soleGate);
+  return nativeResponse({
+    transport: INTEGRATION_MODE,
+    exit_code: 0,
+    enforced: false,
+    ...(body === undefined ? {} : { stdout: body }),
+  });
+}
+
+/**
+ * Build the exit-0 stdout decision body. `allow` abstains — no `decision` key,
+ * so Gemini runs its normal flow — unless `soleGate` opts into the real
+ * `decision: "allow"`. `deny`/`ask` both surface an advisory `decision: "deny"`
+ * (Gemini has no native ask tier). `mutated_input` rides along as
+ * `hookSpecificOutput.tool_input` and `additional_context` as Gemini's native
+ * `systemMessage`. Returns undefined when there is nothing to emit (a pure
+ * abstaining allow).
+ * @param {Verdict} vd
+ * @param {boolean} soleGate
+ * @returns {Record<string, unknown>|undefined}
+ */
+function decisionBody(vd, soleGate) {
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  if (vd.decision === Decision.DENY || vd.decision === Decision.ASK) {
+    out.decision = "deny";
+    if (vd.reason !== undefined) out.reason = vd.reason;
+  } else if (soleGate) {
+    out.decision = "allow";
+  }
+  if (vd.mutated_input !== undefined)
+    out.hookSpecificOutput = { tool_input: vd.mutated_input };
+  if (vd.additional_context !== undefined)
+    out.systemMessage = vd.additional_context;
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/** @type {import("../control-plane.mjs").Adapter} */
+export const geminiAdapter = { AGENT, INTEGRATION_MODE, parse, render };

package/src/conformance.mjs

@@ -0,0 +1,121 @@
+/**
+ * The control-plane conformance harness.
+ *
+ * Any adapter — the reference claude one, codex, or a future
+ * cursor/cline/gemini-cli/aider translator — must pass this against its own
+ * golden fixtures. It pins the two directions of the contract:
+ *
+ *   1. parse is golden: adapter.parse(native) deep-equals the fixture's
+ *      normalized `event` (and never throws — an adapter that threw would fail
+ *      here rather than in production).
+ *   2. render is golden: for each verdict scenario, adapter.render(verdict,
+ *      parsedEvent) deep-equals the fixture's native response. An `allow` with
+ *      the unmutated input renders to the agent's native allow; deny/ask/mutation
+ *      each render to their native shape.
+ *   3. non-vacuity: the fixture set collectively renders an allow, a deny, an
+ *      ask, AND a mutated_input, so a suite can't pass while silently skipping a
+ *      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` or a `throw_` —
+ *      not just a JSON body the agent is free to ignore. At least one enforced
+ *      deny must appear, so the honesty check is never vacuous.
+ *   5. non-vetoable honesty: when the parsed event's `this_call_vetoable` is
+ *      false, EVERY render for that case must be `enforced === false` — a
+ *      guardrail that cannot veto this call must never render as if it did.
+ *   6. allow = abstain: by default (no `soleGate` opt-in) every `allow` render
+ *      is `enforced === false` AND `exit_code === 0` — an "I have no objection"
+ *      verdict never renders as a block, on any adapter. At least one `allow`
+ *      must be rendered, so this is never vacuous.
+ *
+ * `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 }}
+ */
+export function runAdapterConformance({ adapter, fixtures, assert }) {
+  assert.equal(
+    adapter.AGENT,
+    fixtures.agent,
+    `adapter AGENT '${adapter.AGENT}' does not match fixtures.agent '${fixtures.agent}'`,
+  );
+
+  /** @type {Set<string>} */
+  const decisionsSeen = new Set();
+  let mutationSeen = false;
+  let enforcedDenySeen = false;
+  let renders = 0;
+
+  for (const testCase of fixtures.cases) {
+    const parsed = adapter.parse(testCase.native);
+    assert.deepEqual(
+      parsed,
+      testCase.event,
+      `parse mismatch: ${testCase.name}`,
+    );
+
+    for (const [scenario, raw] of Object.entries(testCase.render)) {
+      const spec = /** @type {{ verdict: any, native: any }} */ (raw);
+      const rendered = adapter.render(spec.verdict, parsed);
+      assert.deepEqual(
+        rendered,
+        spec.native,
+        `render mismatch: ${testCase.name} / ${scenario}`,
+      );
+      if (rendered.enforced) {
+        assert.ok(
+          rendered.exit_code !== 0 || rendered.throw_ !== undefined,
+          `enforced deny carries no block signal: ${testCase.name} / ${scenario}`,
+        );
+        enforcedDenySeen = true;
+      }
+      if (parsed.this_call_vetoable === false) {
+        assert.equal(
+          rendered.enforced,
+          false,
+          `non-vetoable call rendered as enforced: ${testCase.name} / ${scenario}`,
+        );
+      }
+      if (spec.verdict.decision === "allow") {
+        assert.equal(
+          rendered.enforced,
+          false,
+          `allow rendered as enforced: ${testCase.name} / ${scenario}`,
+        );
+        assert.equal(
+          rendered.exit_code,
+          0,
+          `allow rendered a non-zero exit_code: ${testCase.name} / ${scenario}`,
+        );
+      }
+      decisionsSeen.add(spec.verdict.decision);
+      if (spec.verdict.mutated_input !== undefined) mutationSeen = true;
+      renders += 1;
+    }
+  }
+
+  for (const decision of ["allow", "deny", "ask"]) {
+    assert.ok(
+      decisionsSeen.has(decision),
+      `conformance fixtures never render a '${decision}' verdict — the suite is vacuous`,
+    );
+  }
+  assert.ok(
+    mutationSeen,
+    "conformance fixtures never render a mutated_input verdict — mutation is untested",
+  );
+  assert.ok(
+    enforcedDenySeen,
+    "no enforced deny rendered — enforcement honesty is untested",
+  );
+  assert.ok(renders > 0, "conformance fixtures render nothing");
+
+  return {
+    cases: fixtures.cases.length,
+    renders,
+    decisionsSeen,
+    mutationSeen,
+    enforcedDenySeen,
+  };
+}