agent-control-plane-core 0.4.3 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-control-plane-core",
-  "version": "0.4.3",
+  "version": "0.5.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/adapters/amp.mjs

@@ -18,7 +18,8 @@ import {
   CallClass,
   CoverageStatus,
   classifyCallClass,
-  coverageAllowsVeto,
+  vetoableFor,
+  assertGatedKinds,
   canonicalTool,
   lookup,
   makeEvent,
@@ -53,6 +54,16 @@ export const COVERAGE = Object.freeze({
   [CallClass.RESUMED]: CoverageStatus.UNKNOWN,
 });
 
+/**
+ * The event kinds this host can actually gate. Amp invokes the delegate for a tool call and nothing else, so parse only ever emits PRE_TOOL.
+ * A kind absent here parses non-vetoable, so an unmodelled event never renders as
+ * an enforced block the host will not perform. Module-private: `Object.freeze` does
+ * not stop `Set.add`, so an exported set would let a consumer add UNKNOWN back
+ * after `assertGatedKinds` has already run.
+ */
+const GATED_EVENTS = Object.freeze(new Set([EventKind.PRE_TOOL]));
+assertGatedKinds(GATED_EVENTS, AGENT);
+
 // 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"]);
@@ -81,7 +92,9 @@ export function parse(native) {
     input: asObject(raw.input),
     response: undefined,
     // Classify on the NATIVE name (MCP detection keys on `mcp__…`).
-    this_call_vetoable: coverageAllowsVeto(
+    this_call_vetoable: vetoableFor(
+      EventKind.PRE_TOOL,
+      GATED_EVENTS,
       COVERAGE[classifyCallClass(nativeTool, raw)],
     ),
     meta,

package/src/adapters/claude.mjs

@@ -19,7 +19,8 @@ import {
   CallClass,
   CoverageStatus,
   classifyCallClass,
-  coverageAllowsVeto,
+  vetoableFor,
+  assertGatedKinds,
   canonicalTool,
   lookup,
   makeEvent,
@@ -57,6 +58,20 @@ export const COVERAGE = Object.freeze({
   [CallClass.RESUMED]: CoverageStatus.COVERED,
 });
 
+/**
+ * The event kinds this host can actually gate. Claude Code honours a deny on these three. SESSION_START is left out: exit 2 does
+ * not abort a session start, and the matrix documents no host response for it — an
+ * undocumented kind is fail-closed to non-vetoable, the same rule coverage uses.
+ * A kind absent here parses non-vetoable, so an unmodelled event never renders as
+ * an enforced block the host will not perform. Module-private: `Object.freeze` does
+ * not stop `Set.add`, so an exported set would let a consumer add UNKNOWN back after
+ * `assertGatedKinds` has already run.
+ */
+const GATED_EVENTS = Object.freeze(
+  new Set([EventKind.PRE_TOOL, EventKind.POST_TOOL, EventKind.PROMPT_SUBMIT]),
+);
+assertGatedKinds(GATED_EVENTS, AGENT);
+
 /** Claude Code native hook event names (the `hook_event_name` field). */
 export const HookEvent = Object.freeze({
   PRE_TOOL_USE: "PreToolUse",
@@ -162,7 +177,9 @@ export function parse(native) {
     response,
     // Classify on the NATIVE name — MCP detection keys on `mcp__…`, which a
     // canonical builtin name would never carry.
-    this_call_vetoable: coverageAllowsVeto(
+    this_call_vetoable: vetoableFor(
+      kind,
+      GATED_EVENTS,
       COVERAGE[classifyCallClass(nativeTool, raw)],
     ),
     meta,

package/src/adapters/codex.mjs

@@ -20,7 +20,8 @@ import {
   CallClass,
   CoverageStatus,
   classifyCallClass,
-  coverageAllowsVeto,
+  vetoableFor,
+  assertGatedKinds,
   canonicalTool,
   makeEvent,
   normalizeVerdict,
@@ -54,6 +55,17 @@ export const COVERAGE = Object.freeze({
   [CallClass.RESUMED]: CoverageStatus.UNKNOWN,
 });
 
+/**
+ * The event kinds this host can actually gate. `PreToolUse` is the one event Codex can veto. Every other native event parses as
+ * UNKNOWN today, so without this set each of them reported an enforced block.
+ * A kind absent here parses non-vetoable, so an unmodelled event never renders as
+ * an enforced block the host will not perform. Module-private: `Object.freeze` does
+ * not stop `Set.add`, so an exported set would let a consumer add UNKNOWN back
+ * after `assertGatedKinds` has already run.
+ */
+const GATED_EVENTS = Object.freeze(new Set([EventKind.PRE_TOOL]));
+assertGatedKinds(GATED_EVENTS, AGENT);
+
 /** Minimum Codex version whose hook can actually veto a tool call. */
 export const MIN_ENFORCING_VERSION = Object.freeze([0, 135]);
 
@@ -140,7 +152,12 @@ export function parse(native) {
   const nativeTool = asStringOrNull(raw.tool_name);
   if (nativeTool !== null) meta.native_tool = nativeTool;
   const vetoable =
-    enforce && coverageAllowsVeto(COVERAGE[classifyCallClass(nativeTool, raw)]);
+    enforce &&
+    vetoableFor(
+      kind,
+      GATED_EVENTS,
+      COVERAGE[classifyCallClass(nativeTool, raw)],
+    );
 
   return makeEvent({
     event: kind,

package/src/adapters/gemini.mjs

@@ -35,7 +35,8 @@ import {
   CallClass,
   CoverageStatus,
   classifyCallClass,
-  coverageAllowsVeto,
+  vetoableFor,
+  assertGatedKinds,
   canonicalTool,
   lookup,
   assertAliasTargetsModeled,
@@ -72,6 +73,18 @@ export const COVERAGE = Object.freeze({
   [CallClass.RESUMED]: CoverageStatus.UNKNOWN,
 });
 
+/**
+ * The event kinds this host can actually gate. Gemini CLI honours a deny on each of the three events NATIVE_TO_KIND maps.
+ * A kind absent here parses non-vetoable, so an unmodelled event never renders as
+ * an enforced block the host will not perform. Module-private: `Object.freeze` does
+ * not stop `Set.add`, so an exported set would let a consumer add UNKNOWN back
+ * after `assertGatedKinds` has already run.
+ */
+const GATED_EVENTS = Object.freeze(
+  new Set([EventKind.PRE_TOOL, EventKind.POST_TOOL, EventKind.PROMPT_SUBMIT]),
+);
+assertGatedKinds(GATED_EVENTS, AGENT);
+
 /** Gemini CLI native hook event names (the `hook_event_name` field). */
 export const HookEvent = Object.freeze({
   BEFORE_TOOL: "BeforeTool",
@@ -236,7 +249,7 @@ export function parse(native) {
     tool: geminiCanonicalTool(nativeTool, callClass),
     input: geminiInput(kind, raw, nativeTool, callClass),
     response,
-    this_call_vetoable: coverageAllowsVeto(COVERAGE[callClass]),
+    this_call_vetoable: vetoableFor(kind, GATED_EVENTS, COVERAGE[callClass]),
     meta,
   });
 }

package/src/conformance.mjs

@@ -21,6 +21,21 @@ const UNENFORCEABLE_DENY_PROBE = Object.freeze({
 });
 const ABSTAINING_ALLOW_PROBE = Object.freeze({ decision: Decision.ALLOW });
 
+/**
+ * The payload rule ⑨ drifts an adapter with. No host emits that event name, so
+ * an adapter that maps event names must answer {@link EventKind.UNKNOWN}.
+ *
+ * `version` carries a release far past any adapter's enforcement floor. Without
+ * it Codex's own version gate answers non-vetoable for an unrelated reason, and
+ * the rule then passes on the adapter that needs it most — Codex routes EVERY
+ * non-PreToolUse event into UNKNOWN, so a probe it cannot bite on certifies
+ * nothing.
+ */
+const DRIFT_PROBE_NATIVE = Object.freeze({
+  hook_event_name: "ConformanceProbeUnmodelledEvent",
+  version: "9999.0.0",
+});
+
 /**
  * Assert an adapter's {@link import("./control-plane.mjs").Adapter.COVERAGE}
  * hook-coverage matrix is well-formed: it classifies EXACTLY the canonical
@@ -225,7 +240,7 @@ function assertAliasedInput(agent, caseName, event, assert) {
  * 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, vetoableDenySeen: boolean, coverageClassesChecked: Set<string>, unenforceableDenyChecks: number }}
+ * @returns {{ cases: number, renders: number, decisionsSeen: Set<string>, mutationSeen: boolean, enforcedDenySeen: boolean, vetoableDenySeen: boolean, unknownKindSeen: boolean, coverageClassesChecked: Set<string>, unenforceableDenyChecks: number }}
  */
 export function runAdapterConformance({ adapter, fixtures, assert }) {
   assert.equal(
@@ -243,6 +258,7 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
   let mutationSeen = false;
   let enforcedDenySeen = false;
   let vetoableDenySeen = false;
+  let unknownKindSeen = false;
   let preToolCases = 0;
   let unenforceableDenyChecks = 0;
   let renders = 0;
@@ -260,6 +276,18 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
     // a rename-without-its-input land by editing the expectation.
     assertAliasedInput(adapter.AGENT, testCase.name, parsed, assert);
 
+    // An event the adapter could not name is one whose host response nobody has
+    // established, so claiming a veto for it is the one error that lies to a
+    // guardrail: the transcript shows a block and the host runs the tool anyway.
+    if (parsed.event === EventKind.UNKNOWN) {
+      assert.equal(
+        parsed.this_call_vetoable,
+        false,
+        `unmodelled event parsed as vetoable: ${testCase.name}`,
+      );
+      unknownKindSeen = true;
+    }
+
     if (testCase.call_class !== undefined) {
       assert.ok(
         CALL_CLASSES.includes(testCase.call_class),
@@ -385,6 +413,26 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
     enforcedDenySeen,
     "no enforced deny rendered — enforcement honesty is untested",
   );
+  // Rule ⑨: parse must ANSWER for an event it cannot name rather than throw, and
+  // the render of a deny on that answer must not claim a block. Probed on a
+  // synthesized payload rather than a fixture flag, because an adapter whose
+  // parse can never emit UNKNOWN — amp routes every payload to pre_tool — has no
+  // such fixture to write, and a fixture-driven check would then sit vacuous on
+  // exactly the adapters this rule covers.
+  const drifted = adapter.parse({ ...DRIFT_PROBE_NATIVE });
+  if (drifted.event === EventKind.UNKNOWN) {
+    // Not that the event is non-vetoable — `makeEvent` refuses to construct a
+    // vetoable UNKNOWN at all, so asserting it here would police a state the
+    // constructor already makes unreachable. What only a probe can reach is the
+    // RENDER: an adapter is free to derive `enforced` from something other than
+    // the flag, and then the false block returns by another door.
+    assert.equal(
+      adapter.render(UNENFORCEABLE_DENY_PROBE, drifted).enforced,
+      false,
+      "a deny on an unmodelled event rendered as an enforced block",
+    );
+    unknownKindSeen = true;
+  }
   assert.ok(renders > 0, "conformance fixtures render nothing");
   // EVERY pre-tool case, not merely one: the count is what catches rule ⑧ being
   // skipped by a stray `continue` rather than merely present somewhere. A suite
@@ -403,6 +451,7 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
     mutationSeen,
     enforcedDenySeen,
     vetoableDenySeen,
+    unknownKindSeen,
     coverageClassesChecked,
     unenforceableDenyChecks,
   };

package/src/control-plane.mjs

@@ -258,6 +258,52 @@ export function coverageAllowsVeto(status) {
   return status === CoverageStatus.COVERED || status === CoverageStatus.PARTIAL;
 }
 
+/**
+ * The event kinds a host can gate at all. {@link EventKind.UNKNOWN} is absent by
+ * construction, and that absence is the point: an event this package could not
+ * name is one whose host response nobody has established.
+ */
+/** @type {Set<string>} */
+const GATEABLE_KINDS = new Set([
+  EventKind.PRE_TOOL,
+  EventKind.POST_TOOL,
+  EventKind.PROMPT_SUBMIT,
+  EventKind.SESSION_START,
+]);
+
+/**
+ * Whether an event may be marked `this_call_vetoable`.
+ *
+ * INVARIANT: an event whose kind the adapter's `GATED_EVENTS` does not name is
+ * never vetoable, whatever its coverage says. Coverage answers whether the
+ * host's hook fires for a CLASS of call and says nothing about a kind the
+ * adapter could not model — so keying on coverage alone reported an enforced
+ * block for every unmodelled event, which is the one direction that lies to a
+ * guardrail: the transcript shows a block and the host runs the tool.
+ * @param {string} kind an {@link EventKind} value
+ * @param {Set<string>} gatedKinds the adapter's own gated set
+ * @param {string|undefined} coverage a {@link CoverageStatus} value
+ * @returns {boolean}
+ */
+export function vetoableFor(kind, gatedKinds, coverage) {
+  if (!gatedKinds.has(kind)) return false;
+  return coverageAllowsVeto(coverage);
+}
+
+/**
+ * Refuse a gated-kind set naming a kind no host can gate. Called at module load
+ * by each adapter, so `EventKind.UNKNOWN` cannot be added to one by hand.
+ * @param {Set<string>} kinds an adapter's `GATED_EVENTS`
+ * @param {string} agent the adapter's agent id, for the message
+ */
+export function assertGatedKinds(kinds, agent) {
+  for (const kind of kinds)
+    if (!GATEABLE_KINDS.has(kind))
+      throw new Error(
+        `${agent} adapter: ${JSON.stringify(kind)} is not a gateable event kind`,
+      );
+}
+
 /**
  * True when `status` is a recognized {@link CoverageStatus} value.
  * @param {unknown} status
@@ -383,6 +429,16 @@ export function makeEvent({
     throw new TypeError(
       `control-plane: makeEvent this_call_vetoable must be a boolean, got ${typeof this_call_vetoable}`,
     );
+  // The same fail-open seam, one step further: an event the adapter could not
+  // name is one whose host response nobody established, so a veto reported for
+  // it is a block the render claims and the host never performs. Refused HERE
+  // because every adapter builds its event through this call, so an adapter that
+  // computes the flag without `vetoableFor` cannot reach the wire either.
+  if (event === EventKind.UNKNOWN && this_call_vetoable)
+    throw new Error(
+      "control-plane: makeEvent got a vetoable UNKNOWN event — an unmodelled " +
+        "event has no host response to veto, so reporting one is a false block",
+    );
   /** @type {ToolCallEvent} */
   const evt = {
     schema_version: SCHEMA_VERSION,

package/src/fixtures/claude.json

@@ -318,7 +318,7 @@
         "event": "session_start",
         "tool": null,
         "input": {},
-        "this_call_vetoable": true,
+        "this_call_vetoable": false,
         "meta": {
           "agent": "claude",
           "native_event": "SessionStart",
@@ -344,6 +344,24 @@
               }
             }
           }
+        },
+        "deny": {
+          "verdict": {
+            "decision": "deny",
+            "reason": "not a gateable event"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false,
+            "stdout": {
+              "hookSpecificOutput": {
+                "hookEventName": "SessionStart"
+              },
+              "decision": "block",
+              "reason": "not a gateable event"
+            }
+          }
         }
       }
     }

package/types/conformance.d.mts

@@ -103,7 +103,7 @@ export function assertAliasedInputsCanonical(fixturesList: any[], assert: any):
  * 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, vetoableDenySeen: boolean, coverageClassesChecked: Set<string>, unenforceableDenyChecks: number }}
+ * @returns {{ cases: number, renders: number, decisionsSeen: Set<string>, mutationSeen: boolean, enforcedDenySeen: boolean, vetoableDenySeen: boolean, unknownKindSeen: boolean, coverageClassesChecked: Set<string>, unenforceableDenyChecks: number }}
  */
 export function runAdapterConformance({ adapter, fixtures, assert }: {
     adapter: import("./control-plane.mjs").Adapter;
@@ -116,6 +116,7 @@ export function runAdapterConformance({ adapter, fixtures, assert }: {
     mutationSeen: boolean;
     enforcedDenySeen: boolean;
     vetoableDenySeen: boolean;
+    unknownKindSeen: boolean;
     coverageClassesChecked: Set<string>;
     unenforceableDenyChecks: number;
 };

package/types/control-plane.d.mts

@@ -46,6 +46,28 @@ export function lookup<T>(map: Record<string, T>, key: string): T | undefined;
  * @returns {boolean}
  */
 export function coverageAllowsVeto(status: string | undefined): boolean;
+/**
+ * Whether an event may be marked `this_call_vetoable`.
+ *
+ * INVARIANT: an event whose kind the adapter's `GATED_EVENTS` does not name is
+ * never vetoable, whatever its coverage says. Coverage answers whether the
+ * host's hook fires for a CLASS of call and says nothing about a kind the
+ * adapter could not model — so keying on coverage alone reported an enforced
+ * block for every unmodelled event, which is the one direction that lies to a
+ * guardrail: the transcript shows a block and the host runs the tool.
+ * @param {string} kind an {@link EventKind} value
+ * @param {Set<string>} gatedKinds the adapter's own gated set
+ * @param {string|undefined} coverage a {@link CoverageStatus} value
+ * @returns {boolean}
+ */
+export function vetoableFor(kind: string, gatedKinds: Set<string>, coverage: string | undefined): boolean;
+/**
+ * Refuse a gated-kind set naming a kind no host can gate. Called at module load
+ * by each adapter, so `EventKind.UNKNOWN` cannot be added to one by hand.
+ * @param {Set<string>} kinds an adapter's `GATED_EVENTS`
+ * @param {string} agent the adapter's agent id, for the message
+ */
+export function assertGatedKinds(kinds: Set<string>, agent: string): void;
 /**
  * True when `status` is a recognized {@link CoverageStatus} value.
  * @param {unknown} status