agent-control-plane-core 0.5.0 → 0.5.2

package/package.json

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

@@ -57,9 +57,11 @@ export const COVERAGE = Object.freeze({
 /**
  * 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.
+ * 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.
  */
-export const GATED_EVENTS = Object.freeze(new Set([EventKind.PRE_TOOL]));
+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 +

package/src/adapters/claude.mjs

@@ -63,9 +63,11 @@ export const COVERAGE = Object.freeze({
  * 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.
+ * 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.
  */
-export const GATED_EVENTS = Object.freeze(
+const GATED_EVENTS = Object.freeze(
   new Set([EventKind.PRE_TOOL, EventKind.POST_TOOL, EventKind.PROMPT_SUBMIT]),
 );
 assertGatedKinds(GATED_EVENTS, AGENT);

package/src/adapters/codex.mjs

@@ -59,9 +59,11 @@ export const COVERAGE = Object.freeze({
  * 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.
+ * 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.
  */
-export const GATED_EVENTS = Object.freeze(new Set([EventKind.PRE_TOOL]));
+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. */

package/src/adapters/gemini.mjs

@@ -76,9 +76,11 @@ export const COVERAGE = Object.freeze({
 /**
  * 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.
+ * 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.
  */
-export const GATED_EVENTS = Object.freeze(
+const GATED_EVENTS = Object.freeze(
   new Set([EventKind.PRE_TOOL, EventKind.POST_TOOL, EventKind.PROMPT_SUBMIT]),
 );
 assertGatedKinds(GATED_EVENTS, AGENT);

package/src/conformance.mjs

@@ -22,10 +22,19 @@ 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.
+ * 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 UNMODELLED_EVENT_NAME = "ConformanceProbeUnmodelledEvent";
+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}
@@ -404,17 +413,19 @@ 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 });
+  // 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) {
-    assert.equal(
-      drifted.this_call_vetoable,
-      false,
-      "an unmodelled event parsed as vetoable",
-    );
+    // 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,

package/src/control-plane.mjs

@@ -429,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/types/adapters/amp.d.mts

@@ -30,12 +30,6 @@ 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,14 +41,6 @@ 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,13 +59,6 @@ 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,12 +43,6 @@ 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";