agent-control-plane-core 0.4.3 → 0.5.0

package/package.json

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

@@ -18,7 +18,8 @@ import {
   CallClass,
   CoverageStatus,
   classifyCallClass,
-  coverageAllowsVeto,
+  vetoableFor,
+  assertGatedKinds,
   canonicalTool,
   lookup,
   makeEvent,
@@ -53,6 +54,14 @@ 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.
+ */
+export 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 +90,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,18 @@ 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.
+ */
+export 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 +175,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,15 @@ 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.
+ */
+export 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 +150,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,16 @@ 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.
+ */
+export 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 +247,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,12 @@ const UNENFORCEABLE_DENY_PROBE = Object.freeze({
 });
 const ABSTAINING_ALLOW_PROBE = Object.freeze({ decision: Decision.ALLOW });
 
+/**
+ * The native event name rule ⑨ drifts an adapter with. No host emits it, so an
+ * adapter that maps event names must answer {@link EventKind.UNKNOWN} for it.
+ */
+const UNMODELLED_EVENT_NAME = "ConformanceProbeUnmodelledEvent";
+
 /**
  * Assert an adapter's {@link import("./control-plane.mjs").Adapter.COVERAGE}
  * hook-coverage matrix is well-formed: it classifies EXACTLY the canonical
@@ -225,7 +231,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 +249,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 +267,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 +404,24 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
     enforcedDenySeen,
     "no enforced deny rendered — enforcement honesty is untested",
   );
+  // Rule ⑨, probed on a synthesized payload rather than a fixture flag: an
+  // adapter whose parse can never emit UNKNOWN — amp routes every payload to
+  // pre_tool — has no such fixture to write, so a fixture-driven check would sit
+  // vacuous on exactly the adapters this rule covers.
+  const drifted = adapter.parse({ hook_event_name: UNMODELLED_EVENT_NAME });
+  if (drifted.event === EventKind.UNKNOWN) {
+    assert.equal(
+      drifted.this_call_vetoable,
+      false,
+      "an unmodelled event parsed as vetoable",
+    );
+    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 +440,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

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/adapters/amp.d.mts

@@ -30,6 +30,12 @@ export const INTEGRATION_MODE: "external_hook";
  */
 /** @type {import("../control-plane.mjs").CoverageMap} */
 export const COVERAGE: import("../control-plane.mjs").CoverageMap;
+/**
+ * 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.
+ */
+export const GATED_EVENTS: Readonly<Set<"pre_tool">>;
 /** @type {import("../control-plane.mjs").Adapter} */
 export const ampAdapter: import("../control-plane.mjs").Adapter;
 export type ToolCallEvent = import("../control-plane.mjs").ToolCallEvent;

package/types/adapters/claude.d.mts

@@ -41,6 +41,14 @@ export const INTEGRATION_MODE: "external_hook";
  */
 /** @type {import("../control-plane.mjs").CoverageMap} */
 export const COVERAGE: import("../control-plane.mjs").CoverageMap;
+/**
+ * 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.
+ */
+export const GATED_EVENTS: Readonly<Set<"pre_tool" | "post_tool" | "prompt_submit">>;
 /** Claude Code native hook event names (the `hook_event_name` field). */
 export const HookEvent: Readonly<{
     PRE_TOOL_USE: "PreToolUse";

package/types/adapters/codex.d.mts

@@ -59,6 +59,13 @@ export const INTEGRATION_MODE: "external_hook";
  */
 /** @type {import("../control-plane.mjs").CoverageMap} */
 export const COVERAGE: import("../control-plane.mjs").CoverageMap;
+/**
+ * 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.
+ */
+export const GATED_EVENTS: Readonly<Set<"pre_tool">>;
 /** Minimum Codex version whose hook can actually veto a tool call. */
 export const MIN_ENFORCING_VERSION: readonly number[];
 export const DEFAULT_DENY_REASON: "blocked by monitor";

package/types/adapters/gemini.d.mts

@@ -43,6 +43,12 @@ export const INTEGRATION_MODE: "external_hook";
  */
 /** @type {import("../control-plane.mjs").CoverageMap} */
 export const COVERAGE: import("../control-plane.mjs").CoverageMap;
+/**
+ * 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.
+ */
+export const GATED_EVENTS: Readonly<Set<"pre_tool" | "post_tool" | "prompt_submit">>;
 /** Gemini CLI native hook event names (the `hook_event_name` field). */
 export const HookEvent: Readonly<{
     BEFORE_TOOL: "BeforeTool";

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