agent-control-plane-core 0.6.4 → 0.8.0

package/src/conformance.mjs

@@ -22,6 +22,22 @@ const UNENFORCEABLE_DENY_PROBE = Object.freeze({
 });
 const ABSTAINING_ALLOW_PROBE = Object.freeze({ decision: Decision.ALLOW });
 
+/**
+ * The two probe verdicts rule ⑪ renders against the same event, to read whether
+ * this host's transport carries an ask tier of its own. They share one `reason`
+ * on purpose: the rule compares the two RENDERS, and a reason that differed
+ * would make them differ for a reason that is not the decision.
+ */
+const ASK_TIER_REASON = "conformance probe: ask tier";
+const ASK_TIER_ASK_PROBE = Object.freeze({
+  decision: Decision.ASK,
+  reason: ASK_TIER_REASON,
+});
+const ASK_TIER_DENY_PROBE = Object.freeze({
+  decision: Decision.DENY,
+  reason: ASK_TIER_REASON,
+});
+
 /**
  * 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}.
@@ -202,17 +218,23 @@ const CONTENT_PROBE_VALUES = Object.freeze({
   ]),
 });
 
-// A field added to VERDICT_CONTENT_FIELDS with no probe value would be dropped
-// by normalizeVerdict and then reported as "reaches no native channel" against
-// every adapter, naming the adapter for the harness's own omission.
-if (
-  VERDICT_CONTENT_FIELDS.some(
-    (field) => (lookup(CONTENT_PROBE_VALUES, field) ?? []).length < 2,
-  )
-)
-  throw new Error(
-    `conformance: CONTENT_PROBE_VALUES needs two or more values for each of ${VERDICT_CONTENT_FIELDS.join(", ")}`,
-  );
+/**
+ * A field added to VERDICT_CONTENT_FIELDS with no probe value would be dropped
+ * by normalizeVerdict and then reported as "reaches no native channel" against
+ * every adapter, naming the adapter for the harness's own omission. Called at
+ * import against the live {@link CONTENT_PROBE_VALUES}; exported so a test can
+ * drive both branches.
+ * @param {readonly string[]} fields
+ * @param {Record<string, readonly unknown[]>} values
+ */
+export function assertContentProbeValuesComplete(fields, values) {
+  if (fields.some((field) => (lookup(values, field) ?? []).length < 2))
+    throw new Error(
+      `conformance: CONTENT_PROBE_VALUES needs two or more values for each of ${fields.join(", ")}`,
+    );
+}
+
+assertContentProbeValuesComplete(VERDICT_CONTENT_FIELDS, CONTENT_PROBE_VALUES);
 
 /**
  * Rule ⑩'s first half: the adapter declares a row for EVERY {@link EventKind}.
@@ -454,6 +476,78 @@ function coherentEvent(adapter, byKind, kind) {
   };
 }
 
+/**
+ * Rule ⑪, for one pre-tool event: the adapter's `NATIVE_ASK_TIER` declaration
+ * agrees with what `render` does with an `ask`.
+ *
+ * The declaration is what lets a consumer stop keeping a hand-typed list of
+ * which hosts honour an ask. A consumer that must not let an ask through
+ * escalates it to a deny on a host with no ask tier — and applying that
+ * uniformly turns every ask into a deny on the hosts that DO have one. So the
+ * declaration has to be checked against the render rather than believed.
+ *
+ * Probed on a NON-vetoable variant of the event, for rule ⑧'s reason and one
+ * more: it makes the deny comparison below an ADVISORY deny, which is the
+ * signal a host with no ask tier has left to spend on an ask.
+ *
+ * What a render can show, and what it cannot. Whether a host suspends the call
+ * for a human lives in the HOST, so no probe reads it off a render. What a probe
+ * does read is each direction's tell:
+ *
+ * - Declared `true`, rendered as the abstaining ALLOW: the consumer is told the
+ *   human will see this call, and the transport carries nothing that says so —
+ *   the tool just runs. That is the lie this rule exists to catch.
+ * - Declared `false`, rendered as something the adapter's own advisory deny is
+ *   not: the render invents a third signal on a transport the declaration says
+ *   has only two, so one of the two is wrong.
+ *
+ * An OBSERVE_ONLY render is exempt, as in rule ⑧: that transport has no
+ * pre-emption channel at all, so its ask, deny and allow coincide by
+ * construction and demanding a distinct ask would demand a fiction.
+ * @param {import("./control-plane.mjs").Adapter} adapter
+ * @param {import("./control-plane.mjs").ToolCallEvent} event a non-vetoable pre-tool event
+ * @param {import("./control-plane.mjs").ToolCallEvent} vetoable the fixture's own pre-tool event, whose veto the block half needs
+ * @param {string} caseName
+ * @param {any} assert
+ */
+function assertAskTier(adapter, event, vetoable, caseName, assert) {
+  const asked = adapter.render(ASK_TIER_ASK_PROBE, event);
+  assert.equal(
+    asked.enforced,
+    false,
+    `an ask rendered as an enforced block: ${caseName}`,
+  );
+  if (asked.transport === IntegrationMode.OBSERVE_ONLY) return;
+  if (adapter.NATIVE_ASK_TIER) {
+    assert.notDeepEqual(
+      asked,
+      adapter.render(ABSTAINING_ALLOW_PROBE, event),
+      `${adapter.AGENT}: NATIVE_ASK_TIER is true, but an ask renders exactly as this host's abstaining allow — nothing in the transport asks anyone: ${caseName}`,
+    );
+    // The other way to declare an ask tier this host has not got: render the ask
+    // as the host's BLOCK. It differs from the allow, so the half above passes,
+    // and the consumer it tells to stop escalating then hands a call to a host
+    // that denies it outright rather than suspending it for a human. Probed on
+    // the vetoable event, because a block is the one signal a non-vetoable
+    // render cannot carry.
+    if (vetoable.this_call_vetoable) {
+      const blocked = adapter.render(ASK_TIER_DENY_PROBE, vetoable);
+      if (blocked.enforced)
+        assert.notDeepEqual(
+          adapter.render(ASK_TIER_ASK_PROBE, vetoable),
+          blocked,
+          `${adapter.AGENT}: NATIVE_ASK_TIER is true, but an ask renders exactly as this host's enforced deny — the call is blocked, not suspended: ${caseName}`,
+        );
+    }
+    return;
+  }
+  assert.deepEqual(
+    asked,
+    adapter.render(ASK_TIER_DENY_PROBE, event),
+    `${adapter.AGENT}: NATIVE_ASK_TIER is false, but an ask renders differently from this host's advisory deny — the render carries an ask signal the declaration says the host has not got: ${caseName}`,
+  );
+}
+
 /**
  * Rule ⑩, for one parsed event: every {@link VERDICT_CONTENT_FIELDS} entry
  * either reaches this host's wire or is DECLARED unreachable in the adapter's
@@ -513,8 +607,13 @@ function assertContentChannels(adapter, event, caseName, assert, seen) {
   // nowhere to hide.
   /** @param {string} field @param {Record<string, unknown>} held @param {string} shape */
   const carries = (field, held, shape) => {
-    const values = lookup(CONTENT_PROBE_VALUES, field) ?? [];
-    if (values.length < 2) return;
+    // `field` is always a VERDICT_CONTENT_FIELDS member (the only caller below
+    // iterates it), and assertContentProbeValuesComplete guarantees at import
+    // that every such member has two or more entries here — so neither a
+    // missing row nor a short one can reach this point.
+    const values = /** @type {readonly unknown[]} */ (
+      lookup(CONTENT_PROBE_VALUES, field)
+    );
     const renders = values.map((value) =>
       adapter.render(
         { decision: Decision.ALLOW, ...held, [field]: value },
@@ -592,7 +691,11 @@ function assertContentChannels(adapter, event, caseName, assert, seen) {
     const held = others.reduce(
       (combinations, name) =>
         combinations.flatMap((carried) =>
-          (lookup(CONTENT_PROBE_VALUES, name) ?? []).map((value) => ({
+          // Same guarantee as `carries` above: `name` is a VERDICT_CONTENT_FIELDS
+          // member, so the row is always present.
+          /** @type {readonly unknown[]} */ (
+            lookup(CONTENT_PROBE_VALUES, name)
+          ).map((value) => ({
             ...carried,
             [name]: value,
           })),
@@ -820,13 +923,23 @@ function assertAliasedInput(agent, caseName, event, assert) {
  *      that DID reach a wire come back as `contentFieldsSeen`; a suite covering
  *      several adapters asserts their union to keep the positive half of the
  *      rule non-vacuous, since no single host has a channel for all three.
+ *  11. ask-tier honesty: the adapter declares whether this host carries a
+ *      distinct "ask the human" tier it honours (`NATIVE_ASK_TIER`), and the
+ *      render is held to that declaration on every pre-tool event. A declared
+ *      tier whose `ask` renders as the host's abstaining allow fails — the
+ *      consumer is told a human will see the call while the tool just runs —
+ *      and so does a declared-absent tier whose `ask` renders as anything but
+ *      the adapter's own advisory deny. A consumer reads the declaration to
+ *      decide where an `ask` must be escalated to a `deny`, so a wrong one
+ *      either lets a call through or denies every asked call on the hosts that
+ *      do ask. OBSERVE_ONLY renders are exempt, as in rule ⑧.
  *
  * `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, contentFieldsSeen: Set<string>, enforcedDenySeen: boolean, vetoableDenySeen: boolean, unknownKindSeen: boolean, coverageClassesChecked: Set<string>, unenforceableDenyChecks: number }}
+ * @returns {{ cases: number, renders: number, decisionsSeen: Set<string>, mutationSeen: boolean, contentFieldsSeen: Set<string>, enforcedDenySeen: boolean, vetoableDenySeen: boolean, unknownKindSeen: boolean, coverageClassesChecked: Set<string>, unenforceableDenyChecks: number, askTierChecks: number }}
  */
 export function runAdapterConformance({ adapter, fixtures, assert }) {
   assert.equal(
@@ -837,6 +950,14 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
 
   assertCoverageWellFormed(adapter, assert);
   assertEveryKindHasARow(adapter, assert);
+  // Named here rather than left to a `TypeError` inside rule ⑪: a third-party
+  // adapter written against the earlier contract has no such member, and its
+  // author is who reads this.
+  assert.equal(
+    typeof adapter.NATIVE_ASK_TIER,
+    "boolean",
+    `${adapter.AGENT}: adapter declares no NATIVE_ASK_TIER — every adapter needs a boolean saying whether this host honours a distinct "ask the human" tier (false when render collapses ask onto another signal)`,
+  );
 
   /** @type {Set<string>} */
   const decisionsSeen = new Set();
@@ -852,6 +973,7 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
   const parsedByKind = {};
   let preToolCases = 0;
   let unenforceableDenyChecks = 0;
+  let askTierChecks = 0;
   let renders = 0;
 
   for (const testCase of fixtures.cases) {
@@ -991,12 +1113,17 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
     // An OBSERVE_ONLY render is exempt from the ≠-allow half: that transport has
     // no pre-emption channel at all, so its deny and allow are identical by
     // construction. Demanding a distinct signal there would demand a fiction.
-    if (deniedRender.transport === IntegrationMode.OBSERVE_ONLY) continue;
-    assert.notDeepEqual(
-      deniedRender,
-      adapter.render(ABSTAINING_ALLOW_PROBE, unenforceable),
-      `unenforceable deny renders identically to an abstaining allow — the objection is lost: ${testCase.name}`,
-    );
+    if (deniedRender.transport !== IntegrationMode.OBSERVE_ONLY)
+      assert.notDeepEqual(
+        deniedRender,
+        adapter.render(ABSTAINING_ALLOW_PROBE, unenforceable),
+        `unenforceable deny renders identically to an abstaining allow — the objection is lost: ${testCase.name}`,
+      );
+    // Rule ⑪, on the same non-vetoable variant and AFTER rule ⑧: an adapter that
+    // collapses both its deny and its ask onto the host's allow is reported as
+    // the lost objection it is, not as a mis-declared ask tier.
+    assertAskTier(adapter, unenforceable, parsed, testCase.name, assert);
+    askTierChecks += 1;
   }
 
   for (const decision of ["allow", "deny", "ask"]) {
@@ -1055,6 +1182,13 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
     preToolCases,
     `rule ⑧ (unenforceable deny ≠ allow) ran on ${unenforceableDenyChecks} of ${preToolCases} pre-tool cases`,
   );
+  // Same reason as the count above: the rule is in the same loop, so a stray
+  // `continue` would skip it silently on the later cases.
+  assert.equal(
+    askTierChecks,
+    preToolCases,
+    `rule ⑪ (ask-tier declaration) ran on ${askTierChecks} of ${preToolCases} pre-tool cases`,
+  );
 
   return {
     cases: fixtures.cases.length,
@@ -1067,5 +1201,6 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
     unknownKindSeen,
     coverageClassesChecked,
     unenforceableDenyChecks,
+    askTierChecks,
   };
 }

package/src/control-plane.mjs

@@ -23,9 +23,11 @@
  * Dependency-free on purpose, so a fail-closed hook can import it without
  * dragging in eager config-file reads.
  *
- * VERSIONING — this module IS the frozen contract (its own SSOT, no parallel
- * schema file to drift). Adapters and guardrail consumers are built against it
- * in parallel, so its shapes are stable: {@link EventKind}, {@link Decision},
+ * VERSIONING — this module IS the frozen contract and its own SSOT. The JSON
+ * Schema documents under `schema/` are GENERATED from it by `pnpm gen:schema`
+ * and byte-compared in `json-schema.test.mjs`, so they are output rather than a
+ * second contract; never hand-edit one. Adapters and guardrail consumers are
+ * built against this module in parallel, so its shapes are stable: {@link EventKind}, {@link Decision},
  * {@link MODELED_TOOLS}, and {@link TOOL_ALIASES} are frozen, and
  * {@link SCHEMA_VERSION} / {@link CONTROL_PLANE_SCHEMA} are pinned
  * (control-plane.test.mjs asserts the exact values, so any shape change is a
@@ -38,9 +40,10 @@
  * {@link Adapter} interface an integrator implements. A new REQUIRED adapter
  * member breaks every third-party adapter while every event on the wire stays
  * byte-identical, so it is a package-semver break and leaves
- * {@link CONTROL_PLANE_SCHEMA} alone. `UNRENDERED_FIELDS` is one: adding it is
- * a one-line change per adapter, and the conformance harness names the member
- * and the migration rather than throwing from inside itself.
+ * {@link CONTROL_PLANE_SCHEMA} alone. `UNRENDERED_FIELDS` is one and
+ * `NATIVE_ASK_TIER` is the second: adding either is a one-line change per
+ * adapter, and the conformance harness names the member and the migration
+ * rather than throwing from inside itself.
  */
 
 /** Wire identifier for this schema version; bump on a breaking shape change. */
@@ -501,6 +504,7 @@ export const UNRENDERED_ON_UNKNOWN = readonlySet(VERDICT_CONTENT_FIELDS);
  * @property {(native: any) => ToolCallEvent} parse
  * @property {(verdict: Verdict, event: ToolCallEvent, options?: { soleGate?: boolean }) => NativeResponse} render
  * @property {Record<string, string|undefined>} [NATIVE_EVENT_FOR] the native event name this host uses for each {@link EventKind}, for a conformance probe of a kind no fixture produced. Optional: a kind absent here (`unknown` always, plus any kind this transport does not carry) is probed with a marker name, which takes the adapter's unrecognized-event branch. Never read at runtime — `parse` stamps the real name on `meta.native_event`.
+ * @property {boolean} NATIVE_ASK_TIER whether this host's transport carries a DISTINCT "ask the human" tier that the host honours. `true` ⇒ a rendered `ask` suspends the call in front of a person (Claude Code's `permissionDecision: "ask"`, Amp's exit 1). `false` ⇒ the host has no such tier, so `render` collapses `ask` onto another signal (Gemini CLI writes its advisory `decision: "deny"`) and an un-escalated ask lets the tool run. A consumer that must not let an ask through reads this to decide where to escalate `ask` to `deny`, instead of keeping its own hand-typed list of agent ids. It is about the HOST, not the verdict: `ask` never renders as `enforced` on any adapter, and the tier it names is the PRE-TOOL gate — once a tool has run there is nothing left to suspend, so every host renders a post-tool `ask` as its block. The conformance harness probes the real `render` against it — a `true` whose ask renders as the host's abstaining allow fails, and so does a `false` whose ask differs from its own advisory deny.
  * @property {Record<string, ReadonlySet<string>|undefined>} UNRENDERED_FIELDS per-event-kind set of {@link VERDICT_CONTENT_FIELDS} this host has no native channel for, so `render` drops them. EVERY {@link EventKind} carries a row, including one this adapter's `parse` cannot emit — an omission would otherwise read as "every content field reaches a channel here", the reverse of the truth on a transport that carries none. The value type still admits `undefined` so a consumer handles a lookup miss rather than indexing straight into `.has(...)`; the conformance harness refuses a missing row. SCOPE — a row describes the ALLOW path only. An enforceable deny may drop more: Gemini's exit-2 System Block returns no stdout at all, so a deny there carries no `additional_context` whatever the row says. Do not read this map to infer what a deny delivers. The conformance harness fails an adapter whose renders disagree with its declaration either way, so a stale entry cannot survive.
  */
 

package/src/fixtures/claude.json

@@ -67,7 +67,8 @@
                 "permissionDecision": "deny",
                 "permissionDecisionReason": "blocked rm"
               }
-            }
+            },
+            "stderr": "blocked rm"
           }
         },
         "ask": {
@@ -244,7 +245,8 @@
               },
               "decision": "block",
               "reason": "leak"
-            }
+            },
+            "stderr": "leak"
           }
         },
         "ask": {

package/src/fixtures/codex.json

@@ -109,12 +109,13 @@
           },
           "native": {
             "transport": "external_hook",
-            "exit_code": 0,
-            "enforced": false,
+            "exit_code": 2,
+            "enforced": true,
             "stdout": {
               "hookSpecificOutput": {
                 "hookEventName": "PreToolUse",
-                "permissionDecision": "ask"
+                "permissionDecision": "deny",
+                "permissionDecisionReason": "blocked by monitor"
               }
             }
           }
@@ -315,12 +316,13 @@
           },
           "native": {
             "transport": "external_hook",
-            "exit_code": 0,
-            "enforced": false,
+            "exit_code": 2,
+            "enforced": true,
             "stdout": {
               "hookSpecificOutput": {
                 "hookEventName": "PreToolUse",
-                "permissionDecision": "ask"
+                "permissionDecision": "deny",
+                "permissionDecisionReason": "blocked by monitor"
               }
             }
           }