agent-control-plane-core 0.9.1 → 0.10.0

package/README.md

@@ -125,6 +125,9 @@ NATIVE_ASK_TIER = false;
 Read `NATIVE_ASK_TIER` instead of keeping a list of which agents to escalate an
 `ask` to a `deny` on: a guardrail that must not let an ask through escalates it
 where the flag is `false`, and leaves it alone where the host does the asking.
+`renderEscalated(adapter, verdict, event, { soleGate })` applies that rule: it
+re-renders as a `deny` any non-allow verdict that would render unenforced on a
+vetoable call, except an `ask` on a host whose flag is `true`.
 It describes the HOST, not the verdict — `ask` renders as `enforced: false`
 everywhere — and it names the pre-tool gate, since a tool that already ran has
 nothing left to suspend. Conformance probes your real `render` against it, so a

package/package.json

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

@@ -159,7 +159,10 @@ export function parse(native) {
 
 /**
  * Amp honours a distinct ask tier: exit 1 is its "ask the user", a code Amp
- * treats as neither the allow (0) nor the reject (2). {@link render} emits it
+ * treats as neither the allow (0) nor the reject (2). Source: Amp's own notes,
+ * "`0` allows the tool call, `1` makes Amp ask, and `2` rejects the tool call"
+ * (https://ampcode.com/notes/permissions). No live probe has measured it, and
+ * no source says what exit 1 does in a headless run. {@link render} emits it
  * for every `ask`, so a consumer must NOT escalate an `ask` to a `deny` here.
  * The table below leans on the same tier for the non-vetoable deny, which is
  * only honest because the tier is real.

package/src/adapters/codex.mjs

@@ -54,25 +54,25 @@ export const AGENT = "codex";
 export const INTEGRATION_MODE = IntegrationMode.EXTERNAL_HOOK;
 
 /**
- * Hook-coverage matrix row (`docs/hook-coverage-matrix.md`). `PreToolUse`
- * intercepts the shell (Bash) tool ONLY — other builtins and MCP tools never
- * reach it — so builtin is PARTIAL and MCP is UNCOVERED. A live probe
- * ([X3]/[X4]) fired `PreToolUse` for a SUBAGENT's call and for a call in a
- * RESUMED session, so both are PARTIAL too: covered, under the same Bash-only
- * limit as [X1], rather than the ❓ the matrix carried before the probe ran.
+ * Hook-coverage matrix row (`docs/hook-coverage-matrix.md`). `PreToolUse` fires
+ * for the shell tools, `apply_patch`, every MCP tool call and every other
+ * function tool ([X1]/[X2], read from Codex's own source at the enforcement
+ * floor). It never fires for `write_stdin`, which types into a process an
+ * earlier call started, nor for a tool OpenAI runs on its own side, so builtin
+ * and MCP are both PARTIAL. A live probe ([X3]/[X4]) fired `PreToolUse` for a
+ * SUBAGENT's call and for a call in a RESUMED session, so both are PARTIAL too.
  *
  * These rows describe PRE-TOOL routing, which is the only thing the matrix's
  * [X1]/[X2] sources speak about. `parse` applies them to a pre-tool event only
- * (see {@link vetoableCall}); Codex's `PostToolUse` fires for tools `PreToolUse`
- * never sees, so a post-tool event judged by the MCP row would drop a block
- * Codex documents it honours.
+ * (see {@link vetoableCall}); a `PostToolUse` payload in hand is proof the
+ * post-tool hook fired for that call, whatever the pre-tool row says.
  *
  * The SUBAGENT row is the one the classifier now reaches on this host: the same
  * probe found `agent_id`/`agent_type` present on a subagent's `PreToolUse`
  * payload and ABSENT on the main thread's, so {@link classifyCallClass} answers
  * SUBAGENT from that payload alone. It is PARTIAL, so such a call stays vetoable
  * — the row's job here is to be honest, not to degrade. An MCP-named call takes
- * the UNCOVERED MCP row either way, subagent or not.
+ * the MCP row either way, subagent or not.
  *
  * The RESUMED row is DECLARATIVE ONLY, for a reason no longer about coverage: a
  * resumed session announces itself on `SessionStart` (`source: "resume"`), not on
@@ -84,7 +84,7 @@ export const INTEGRATION_MODE = IntegrationMode.EXTERNAL_HOOK;
 /** @type {import("../control-plane.mjs").CoverageMap} */
 export const COVERAGE = Object.freeze({
   [CallClass.BUILTIN]: CoverageStatus.PARTIAL,
-  [CallClass.MCP]: CoverageStatus.UNCOVERED,
+  [CallClass.MCP]: CoverageStatus.PARTIAL,
   [CallClass.SUBAGENT]: CoverageStatus.PARTIAL,
   [CallClass.RESUMED]: CoverageStatus.PARTIAL,
 });
@@ -221,17 +221,13 @@ export function canEnforce(version) {
 /**
  * Whether an event of `kind` may be marked vetoable, given the tool it names.
  *
- * PRE_TOOL takes the coverage floor: `PreToolUse` fires for Bash only, so an
- * MCP-sourced call is un-vetoable regardless of version (COVERAGE.mcp).
+ * PRE_TOOL takes the coverage floor ({@link COVERAGE}).
  *
  * POST_TOOL does NOT, and that is deliberate: {@link COVERAGE} records which
  * calls reach `PreToolUse`, and a `PostToolUse` payload in hand is proof the
- * post-tool hook already fired for this call — Codex documents PostToolUse
- * firing for tools (apply_patch, MCP) that `PreToolUse` never sees. Judging it
- * by the pre-tool MCP row would degrade a block Codex honours to a notify,
- * which is a fail-CLOSED error but still a wrong one. It stays gated on
- * GATED_EVENTS and on the version floor, so nothing here can mark an unmodelled
- * or pre-0.135 event vetoable.
+ * post-tool hook already fired for this call. It stays gated on GATED_EVENTS
+ * and on the version floor, so nothing here can mark an unmodelled or pre-0.135
+ * event vetoable.
  * @param {string} kind an {@link EventKind} value
  * @param {string|null} nativeTool
  * @param {Record<string, unknown>} raw the native payload, for `mcp_context`

package/src/control-plane.mjs

@@ -958,3 +958,34 @@ export function gatedResponse(
     [row.reason_stream]: blockReason(reason),
   });
 }
+
+/**
+ * Render `verdict` on `adapter`'s host, escalating to a `deny` when the host
+ * would otherwise let the call run without the gate it asked for. A non-allow
+ * verdict that renders unenforced on a vetoable call is re-rendered as a deny,
+ * unless it is an `ask` and the host honours its own ask tier
+ * ({@link Adapter} `NATIVE_ASK_TIER`). Nothing changes for an allow, for a call
+ * this guardrail cannot veto (a deny there blocks nothing either), or for a
+ * render the host already enforces. The deny keeps the verdict's other fields.
+ * @param {Adapter} adapter
+ * @param {Verdict} verdict
+ * @param {ToolCallEvent} event
+ * @param {{ soleGate?: boolean }} [options] passed through to `render`
+ * @returns {NativeResponse}
+ */
+export function renderEscalated(adapter, verdict, event, options = {}) {
+  const { decision } = normalizeVerdict(verdict);
+  const response = adapter.render(verdict, event, options);
+  if (
+    response.enforced ||
+    decision === Decision.ALLOW ||
+    !event.this_call_vetoable ||
+    (decision === Decision.ASK && adapter.NATIVE_ASK_TIER)
+  )
+    return response;
+  return adapter.render(
+    { ...verdict, decision: Decision.DENY },
+    event,
+    options,
+  );
+}

package/src/fixtures/codex.json

@@ -146,7 +146,7 @@
       }
     },
     {
-      "name": "PreToolUse MCP tool is non-vetoable (hook fires for Bash only)",
+      "name": "PreToolUse MCP tool is vetoable (the hook fires for MCP calls)",
       "call_class": "mcp",
       "native": {
         "hook_event_name": "PreToolUse",
@@ -162,7 +162,7 @@
         "input": {
           "title": "hi"
         },
-        "this_call_vetoable": false,
+        "this_call_vetoable": true,
         "meta": {
           "agent": "codex",
           "native_event": "PreToolUse",
@@ -195,15 +195,16 @@
           },
           "native": {
             "transport": "external_hook",
-            "exit_code": 0,
-            "enforced": false,
+            "exit_code": 2,
+            "enforced": true,
             "stdout": {
               "hookSpecificOutput": {
                 "hookEventName": "PreToolUse",
                 "permissionDecision": "deny",
                 "permissionDecisionReason": "mcp blocked"
               }
-            }
+            },
+            "stderr": "mcp blocked"
           }
         }
       }

package/types/adapters/amp.d.mts

@@ -98,7 +98,10 @@ export const NATIVE_EVENT_FOR: Record<string, string | undefined>;
 export const UNRENDERED_FIELDS: Record<string, ReadonlySet<string> | undefined>;
 /**
  * Amp honours a distinct ask tier: exit 1 is its "ask the user", a code Amp
- * treats as neither the allow (0) nor the reject (2). {@link render} emits it
+ * treats as neither the allow (0) nor the reject (2). Source: Amp's own notes,
+ * "`0` allows the tool call, `1` makes Amp ask, and `2` rejects the tool call"
+ * (https://ampcode.com/notes/permissions). No live probe has measured it, and
+ * no source says what exit 1 does in a headless run. {@link render} emits it
  * for every `ask`, so a consumer must NOT escalate an `ask` to a `deny` here.
  * The table below leans on the same tier for the non-vetoable deny, which is
  * only honest because the tier is real.

package/types/adapters/codex.d.mts

@@ -72,25 +72,25 @@ export function createCodexAdapter({ version }?: {
 export const AGENT: "codex";
 export const INTEGRATION_MODE: "external_hook";
 /**
- * Hook-coverage matrix row (`docs/hook-coverage-matrix.md`). `PreToolUse`
- * intercepts the shell (Bash) tool ONLY — other builtins and MCP tools never
- * reach it — so builtin is PARTIAL and MCP is UNCOVERED. A live probe
- * ([X3]/[X4]) fired `PreToolUse` for a SUBAGENT's call and for a call in a
- * RESUMED session, so both are PARTIAL too: covered, under the same Bash-only
- * limit as [X1], rather than the ❓ the matrix carried before the probe ran.
+ * Hook-coverage matrix row (`docs/hook-coverage-matrix.md`). `PreToolUse` fires
+ * for the shell tools, `apply_patch`, every MCP tool call and every other
+ * function tool ([X1]/[X2], read from Codex's own source at the enforcement
+ * floor). It never fires for `write_stdin`, which types into a process an
+ * earlier call started, nor for a tool OpenAI runs on its own side, so builtin
+ * and MCP are both PARTIAL. A live probe ([X3]/[X4]) fired `PreToolUse` for a
+ * SUBAGENT's call and for a call in a RESUMED session, so both are PARTIAL too.
  *
  * These rows describe PRE-TOOL routing, which is the only thing the matrix's
  * [X1]/[X2] sources speak about. `parse` applies them to a pre-tool event only
- * (see {@link vetoableCall}); Codex's `PostToolUse` fires for tools `PreToolUse`
- * never sees, so a post-tool event judged by the MCP row would drop a block
- * Codex documents it honours.
+ * (see {@link vetoableCall}); a `PostToolUse` payload in hand is proof the
+ * post-tool hook fired for that call, whatever the pre-tool row says.
  *
  * The SUBAGENT row is the one the classifier now reaches on this host: the same
  * probe found `agent_id`/`agent_type` present on a subagent's `PreToolUse`
  * payload and ABSENT on the main thread's, so {@link classifyCallClass} answers
  * SUBAGENT from that payload alone. It is PARTIAL, so such a call stays vetoable
  * — the row's job here is to be honest, not to degrade. An MCP-named call takes
- * the UNCOVERED MCP row either way, subagent or not.
+ * the MCP row either way, subagent or not.
  *
  * The RESUMED row is DECLARATIVE ONLY, for a reason no longer about coverage: a
  * resumed session announces itself on `SessionStart` (`source: "resume"`), not on

package/types/control-plane.d.mts

@@ -288,6 +288,23 @@ export function gatedResponse(agent: string, { transport, enforced, unblocked_ex
     stdout?: unknown;
     reason?: string;
 }): NativeResponse;
+/**
+ * Render `verdict` on `adapter`'s host, escalating to a `deny` when the host
+ * would otherwise let the call run without the gate it asked for. A non-allow
+ * verdict that renders unenforced on a vetoable call is re-rendered as a deny,
+ * unless it is an `ask` and the host honours its own ask tier
+ * ({@link Adapter} `NATIVE_ASK_TIER`). Nothing changes for an allow, for a call
+ * this guardrail cannot veto (a deny there blocks nothing either), or for a
+ * render the host already enforces. The deny keeps the verdict's other fields.
+ * @param {Adapter} adapter
+ * @param {Verdict} verdict
+ * @param {ToolCallEvent} event
+ * @param {{ soleGate?: boolean }} [options] passed through to `render`
+ * @returns {NativeResponse}
+ */
+export function renderEscalated(adapter: Adapter, verdict: Verdict, event: ToolCallEvent, options?: {
+    soleGate?: boolean;
+}): NativeResponse;
 /**
  * The vendor-neutral control-plane contract.
  *