agent-control-plane-core 0.5.3 → 0.6.0

package/src/control-plane.mjs

@@ -33,6 +33,14 @@
  * field, a new modeled tool, a new tool alias) is backward-compatible and stays
  * at v1; RENAMING or REMOVING a field, or changing a decision/event vocabulary,
  * is breaking and bumps the version.
+ *
+ * That version covers the WIRE shapes an event or verdict carries, not the
+ * {@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.
  */
 
 /** Wire identifier for this schema version; bump on a breaking shape change. */
@@ -315,16 +323,40 @@ export function isCoverageStatus(status) {
 
 /**
  * Classify a tool call into a {@link CallClass} from what a single pre-tool
- * payload reveals. Only MCP is reliably detectable here — from the tool NAME
- * (`mcp__server__tool` / `mcp_server_tool`) or an explicit `mcp_context` object
- * on the native payload. Subagent- and resumed-session calls carry no universal
- * signal in a lone pre-tool event (detecting them needs the live probe of
- * item ⑤), so they are NOT distinguished here and fall through to BUILTIN — an
- * adapter whose host leaves those classes un-gated relies on the sandbox, not
- * this classifier. An adapter feeds the result into `coverageAllowsVeto(this.
- * COVERAGE[class])` so a call in an uncovered/unknown class parses non-vetoable.
+ * payload reveals. Two classes are detectable here:
+ *
+ * - MCP, from the tool NAME (`mcp__server__tool` / `mcp_server_tool`) or an
+ *   explicit `mcp_context` object on the native payload. Checked FIRST: an MCP
+ *   call made from inside a subagent is still routed through the host's MCP
+ *   surface, and that is the axis a host most often leaves un-gated.
+ * - SUBAGENT, from a non-empty `agent_type` on the payload — the field a host
+ *   stamps on a call made by a subagent rather than the main thread. Claude Code
+ *   carries it (with `agent_id`) on its hook inputs, and a live Codex probe
+ *   ([X3] in `docs/hook-coverage-matrix.md`) found both fields present on a
+ *   subagent's `PreToolUse` and ABSENT on the main thread's, with the `agent_id`
+ *   matching the one `SubagentStart` announced. Absence is what makes the field
+ *   a DISCRIMINATOR rather than decoration, which is why it is read here.
+ *
+ * RESUMED is not detectable from a tool payload on any host measured so far.
+ * Codex does announce a resumed session — `SessionStart` carries
+ * `source: "resume"` ([X4]) — but that is a different event, and correlating it
+ * would mean keeping cross-event state this package deliberately does not have:
+ * `parse` is a pure function of one payload. So a resumed session's call falls
+ * through to BUILTIN (or MCP) and is judged by that row. An adapter feeds the
+ * result into `coverageAllowsVeto(this.COVERAGE[class])` so a call in an
+ * uncovered/unknown class parses non-vetoable.
+ *
+ * The fail-closed reading of a ❓ row therefore reaches BUILTIN, MCP, and — on a
+ * host that stamps `agent_type` — SUBAGENT. An adapter's RESUMED row is still
+ * never selected, so declaring it UNKNOWN would not make a resumed session's
+ * call non-vetoable: it is judged by the row its TOOL selects. Honouring that
+ * row would mean taking the minimum status across the classes this classifier
+ * cannot separate — which collapses BUILTIN to UNKNOWN and disables enforcement
+ * outright for every adapter that has a ❓ there, so it is deliberately not
+ * done. Where a host's resumed coverage is unmeasured, that gap is the
+ * sandbox's to cover, and the row stands as documentation.
  * @param {string|null} tool tool name (null for non-tool events)
- * @param {Record<string, unknown>} [native] the raw native payload, for `mcp_context`
+ * @param {Record<string, unknown>} [native] the raw native payload, for `mcp_context` and `agent_type`
  * @returns {string} a {@link CallClass} value
  */
 export function classifyCallClass(tool, native) {
@@ -336,6 +368,13 @@ export function classifyCallClass(tool, native) {
   // and silently downgrades a legitimate veto).
   if (ctx !== null && typeof ctx === "object" && !Array.isArray(ctx))
     return CallClass.MCP;
+  // A NON-EMPTY string only: a host that stamps the key with `""` or `null` on a
+  // main-thread call is saying "no subagent", and reading that as one would
+  // degrade every ordinary call on a host whose SUBAGENT row is ❓. Codex's
+  // probed value for its default subagent is the literal "default" — a real
+  // agent type, not an empty marker, so it classifies as one.
+  if (typeof native?.agent_type === "string" && native.agent_type !== "")
+    return CallClass.SUBAGENT;
   return CallClass.BUILTIN;
 }
 
@@ -382,11 +421,74 @@ export function classifyCallClass(tool, native) {
  * @typedef {object} Verdict
  * @property {"allow"|"deny"|"ask"} decision
  * @property {Record<string, unknown>} [mutated_input] replacement tool input (pre_tool)
- * @property {unknown} [mutated_output] replacement tool output (post_tool) — the normalized channel for a PostToolUse content transform (redaction/sanitize); a string or the tool's structured output, verbatim. An adapter renders it into whatever native output-mutation channel the host has, or drops it when the host has none (the same per-adapter fidelity gap `reason` has on Amp).
+ * @property {unknown} [mutated_output] replacement tool output (post_tool) — the normalized channel for a PostToolUse content transform (redaction/sanitize); a string or the tool's structured output, verbatim. An adapter renders it into whatever native output-mutation channel the host has, or drops it when the host has none (the same per-adapter fidelity gap `additional_context` has on Codex).
  * @property {string} [additional_context] extra context to splice into the agent's stream
  * @property {string} [reason] human-readable rationale (shown on deny/ask)
  */
 
+/**
+ * The {@link Verdict} fields that carry CONTENT into the agent's stream, as
+ * opposed to the decision itself. Every adapter either renders each one into a
+ * native channel or has no channel for it and drops it; `UNRENDERED_FIELDS`
+ * declares which, and the conformance harness holds each adapter to its own
+ * declaration. `reason` is not listed: it is only live on deny/ask, so it is not
+ * probeable from a single abstaining verdict the way these three are.
+ */
+export const VERDICT_CONTENT_FIELDS = Object.freeze([
+  "mutated_input",
+  "mutated_output",
+  "additional_context",
+]);
+
+/**
+ * A genuinely immutable set of `values`, for a row a consumer can reach.
+ *
+ * `Object.freeze` does not freeze a Set's CONTENTS — `frozen.delete(x)` still
+ * succeeds — and these rows are shared between adapters, so one `delete` would
+ * make several declarations report a channel their renders still discard. The
+ * wrapper holds the Set privately and exposes only the read half, frozen.
+ * @param {Iterable<string>} values
+ * @returns {ReadonlySet<string>}
+ */
+export function readonlySet(values) {
+  const inner = new Set(values);
+  /** @type {ReadonlySet<string>} */
+  const facade = Object.freeze(
+    /** @type {any} */ ({
+      /** @param {string} value */
+      has: (value) => inner.has(value),
+      keys: () => inner.keys(),
+      values: () => inner.values(),
+      entries: () => inner.entries(),
+      // The callback's third argument is the SET, and forwarding to
+      // `inner.forEach` hands the private mutable one straight to a consumer —
+      // `row.forEach((v, k, set) => set.clear())` would empty a row several
+      // adapters share. The shim passes the facade, so there is no reference to
+      // the inner Set anywhere a caller can reach.
+      /**
+       * @param {(value: string, key: string, set: ReadonlySet<string>) => void} fn
+       * @param {unknown} [thisArg]
+       */
+      forEach: (fn, thisArg) =>
+        inner.forEach((value) => fn.call(thisArg, value, value, facade)),
+      [Symbol.iterator]: () => inner[Symbol.iterator](),
+      get size() {
+        return inner.size;
+      },
+    }),
+  );
+  return facade;
+}
+
+/**
+ * The `UNRENDERED_FIELDS` row every adapter uses for {@link EventKind.UNKNOWN}.
+ * An event the adapter could not name is one whose host channels nobody
+ * established, so claiming any of them is the same fail-open `assertGatedKinds`
+ * refuses for the veto: the caller reads a mutation as applied while the host
+ * ignores the key it was written into.
+ */
+export const UNRENDERED_ON_UNKNOWN = readonlySet(VERDICT_CONTENT_FIELDS);
+
 /**
  * The translator for one agent's protocol. `parse` maps a native event to a
  * {@link ToolCallEvent} (never throwing on unmodelled input, stamping the
@@ -398,6 +500,8 @@ export function classifyCallClass(tool, native) {
  * @property {Record<string, "covered"|"partial"|"uncovered"|"unknown">} COVERAGE per-{@link CallClass} hook-coverage status; must classify every {@link CALL_CLASSES} entry
  * @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 {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.
  */
 
 /**
@@ -603,6 +707,65 @@ export function collectPassthrough(native, consumed) {
   return rest;
 }
 
+/**
+ * The optional {@link EventMeta} string fields a host may carry, and the SSOT
+ * {@link baseMeta} reads off every native payload.
+ *
+ * PROBLEM CLASS — an adapter drops a normalized metadata field. Each adapter
+ * hand-copied these, one copy omitted `permission_mode`, and a guardrail keyed
+ * on `event.meta.permission_mode` then read `undefined` for that agent alone and
+ * took its no-value branch. Nothing distinguished "this host never sends the
+ * field" from "this adapter forgot it". Every adapter now maps the WHOLE set
+ * through {@link baseMeta}, so a field a host does not send is simply absent and
+ * no adapter carries an omission of its own.
+ */
+export const STANDARD_META_FIELDS = Object.freeze([
+  "session_id",
+  "cwd",
+  "permission_mode",
+  "transcript_path",
+]);
+
+/**
+ * Build the {@link EventMeta} base every adapter shares: the four required
+ * fields, whichever {@link STANDARD_META_FIELDS} the payload carries, and the
+ * unmodelled remainder in `passthrough`. A mapped field is consumed here too, so
+ * a value that reached `meta` can never also appear in `meta.passthrough`.
+ *
+ * A non-string value leaves its field ABSENT rather than stamping a number or
+ * null onto a contract field consumers read as text. The result is deliberately
+ * mutable: the caller adds the agent-specific `native_tool` after the base.
+ * @param {{ agent: string, native_event: string, integration_mode: string, primary_gate_present: boolean, native: Record<string, unknown>, consumed: Set<string> }} parts
+ * @returns {EventMeta}
+ */
+export function baseMeta({
+  agent,
+  native_event,
+  integration_mode,
+  primary_gate_present,
+  native,
+  consumed,
+}) {
+  /** @type {EventMeta} */
+  const meta = {
+    agent,
+    native_event,
+    integration_mode: /** @type {EventMeta["integration_mode"]} */ (
+      integration_mode
+    ),
+    primary_gate_present,
+    passthrough: collectPassthrough(
+      native,
+      new Set([...consumed, ...STANDARD_META_FIELDS]),
+    ),
+  };
+  for (const field of STANDARD_META_FIELDS) {
+    const value = lookup(native, field);
+    if (typeof value === "string") Object.assign(meta, { [field]: value });
+  }
+  return meta;
+}
+
 // ─── Coercion primitives ─────────────────────────────────────────────────────
 // Adapters read untrusted native JSON: a field may be absent, null, or the wrong
 // type. These coerce to a safe shape (never throw) so a malformed field degrades

package/src/fixtures/amp.json

@@ -10,7 +10,9 @@
           "command": "ls -la"
         },
         "session_id": "a1",
-        "cwd": "/w"
+        "cwd": "/w",
+        "permission_mode": "default",
+        "transcript_path": "/t.jsonl"
       },
       "event": {
         "schema_version": 1,
@@ -28,7 +30,9 @@
           "primary_gate_present": true,
           "passthrough": {},
           "session_id": "a1",
-          "cwd": "/w"
+          "cwd": "/w",
+          "permission_mode": "default",
+          "transcript_path": "/t.jsonl"
         }
       },
       "render": {
@@ -50,7 +54,8 @@
           "native": {
             "transport": "external_hook",
             "exit_code": 2,
-            "enforced": true
+            "enforced": true,
+            "stderr": "blocked"
           }
         },
         "ask": {

package/src/fixtures/codex.json

@@ -53,6 +53,38 @@
             }
           }
         },
+        "output_mutation": {
+          "verdict": {
+            "decision": "allow",
+            "mutated_output": "file1\n[REDACTED: secret]"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false,
+            "stdout": {
+              "hookSpecificOutput": {
+                "hookEventName": "PreToolUse"
+              }
+            }
+          }
+        },
+        "context": {
+          "verdict": {
+            "decision": "allow",
+            "additional_context": "redacted 1 secret"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false,
+            "stdout": {
+              "hookSpecificOutput": {
+                "hookEventName": "PreToolUse"
+              }
+            }
+          }
+        },
         "deny": {
           "verdict": {
             "decision": "deny",
@@ -175,6 +207,126 @@
         }
       }
     },
+    {
+      "name": "PreToolUse v0.151 from a subagent (agent_type present)",
+      "call_class": "subagent",
+      "native": {
+        "hook_event_name": "PreToolUse",
+        "version": "0.151.0",
+        "session_id": "c-sub",
+        "cwd": "/w",
+        "permission_mode": "default",
+        "transcript_path": "/r.jsonl",
+        "tool_name": "Bash",
+        "tool_input": {
+          "command": ["ls", "-la"]
+        },
+        "agent_id": "agt_7f3",
+        "agent_type": "default",
+        "model": "gpt-5-codex",
+        "tool_use_id": "call_1",
+        "turn_id": "turn_3"
+      },
+      "event": {
+        "schema_version": 1,
+        "event": "pre_tool",
+        "tool": "Bash",
+        "input": {
+          "command": ["ls", "-la"]
+        },
+        "this_call_vetoable": true,
+        "meta": {
+          "agent": "codex",
+          "native_event": "PreToolUse",
+          "integration_mode": "external_hook",
+          "primary_gate_present": true,
+          "passthrough": {
+            "agent_id": "agt_7f3",
+            "agent_type": "default",
+            "model": "gpt-5-codex",
+            "tool_use_id": "call_1",
+            "turn_id": "turn_3"
+          },
+          "session_id": "c-sub",
+          "cwd": "/w",
+          "permission_mode": "default",
+          "transcript_path": "/r.jsonl",
+          "native_tool": "Bash"
+        }
+      },
+      "render": {
+        "allow": {
+          "verdict": {
+            "decision": "allow"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false,
+            "stdout": {
+              "hookSpecificOutput": {
+                "hookEventName": "PreToolUse"
+              }
+            }
+          }
+        },
+        "input_mutation": {
+          "verdict": {
+            "decision": "allow",
+            "mutated_input": {
+              "command": ["ls"]
+            }
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false,
+            "stdout": {
+              "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "updatedInput": {
+                  "command": ["ls"]
+                }
+              }
+            }
+          }
+        },
+        "deny": {
+          "verdict": {
+            "decision": "deny",
+            "reason": "subagent shell blocked"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 2,
+            "enforced": true,
+            "stdout": {
+              "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": "subagent shell blocked"
+              }
+            }
+          }
+        },
+        "ask": {
+          "verdict": {
+            "decision": "ask"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false,
+            "stdout": {
+              "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "ask"
+              }
+            }
+          }
+        }
+      }
+    },
     {
       "name": "PermissionRequest round-trips the native event name",
       "native": {
@@ -285,6 +437,131 @@
           }
         }
       }
+    },
+    {
+      "name": "PostToolUse v0.151 blocks on the post-tool schema",
+      "native": {
+        "hook_event_name": "PostToolUse",
+        "version": "0.151.0",
+        "session_id": "c2",
+        "cwd": "/w",
+        "tool_name": "Bash",
+        "tool_input": {
+          "command": "cat .env"
+        },
+        "tool_response": "OPENAI_API_KEY=sk-live-1",
+        "tool_use_id": "call_9"
+      },
+      "event": {
+        "schema_version": 1,
+        "event": "post_tool",
+        "tool": "Bash",
+        "input": {
+          "command": "cat .env"
+        },
+        "this_call_vetoable": true,
+        "meta": {
+          "agent": "codex",
+          "native_event": "PostToolUse",
+          "integration_mode": "external_hook",
+          "primary_gate_present": true,
+          "passthrough": {
+            "tool_use_id": "call_9"
+          },
+          "session_id": "c2",
+          "cwd": "/w",
+          "native_tool": "Bash"
+        },
+        "response": "OPENAI_API_KEY=sk-live-1"
+      },
+      "render": {
+        "context": {
+          "verdict": {
+            "decision": "allow",
+            "additional_context": "1 secret in this output"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false,
+            "stdout": {
+              "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": "1 secret in this output"
+              }
+            }
+          }
+        },
+        "output_mutation": {
+          "verdict": {
+            "decision": "allow",
+            "mutated_output": "[REDACTED]"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false,
+            "stdout": {
+              "hookSpecificOutput": {
+                "hookEventName": "PostToolUse"
+              }
+            }
+          }
+        },
+        "ask": {
+          "verdict": {
+            "decision": "ask",
+            "reason": "secret in output"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false,
+            "stdout": {
+              "hookSpecificOutput": {
+                "hookEventName": "PostToolUse"
+              },
+              "decision": "block",
+              "reason": "secret in output"
+            }
+          }
+        },
+        "deny": {
+          "verdict": {
+            "decision": "deny",
+            "reason": "leaked credential"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 2,
+            "enforced": true,
+            "stdout": {
+              "hookSpecificOutput": {
+                "hookEventName": "PostToolUse"
+              },
+              "decision": "block",
+              "reason": "leaked credential"
+            }
+          }
+        },
+        "deny_no_reason": {
+          "verdict": {
+            "decision": "deny"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 2,
+            "enforced": true,
+            "stdout": {
+              "hookSpecificOutput": {
+                "hookEventName": "PostToolUse"
+              },
+              "decision": "block",
+              "reason": "blocked by monitor"
+            }
+          }
+        }
+      }
     }
   ]
 }

package/src/fixtures/gemini.json

@@ -13,7 +13,8 @@
         "tool_name": "run_shell_command",
         "tool_input": {
           "command": "echo hi"
-        }
+        },
+        "permission_mode": "default"
       },
       "event": {
         "schema_version": 1,
@@ -34,7 +35,8 @@
           },
           "session_id": "g1",
           "cwd": "/w",
-          "transcript_path": "/t.json"
+          "transcript_path": "/t.json",
+          "permission_mode": "default"
         }
       },
       "render": {
@@ -186,6 +188,21 @@
             "exit_code": 0,
             "enforced": false
           }
+        },
+        "output_mutation": {
+          "verdict": {
+            "decision": "allow",
+            "mutated_output": "file1\n[REDACTED: secret]",
+            "additional_context": "redacted 1 secret"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false,
+            "stdout": {
+              "systemMessage": "redacted 1 secret\n\nThe monitor redacted this tool output, but Gemini CLI has no AfterTool channel to replace it. Treat the tool output above as UNREDACTED and unvetted."
+            }
+          }
         }
       }
     },
@@ -437,6 +454,86 @@
           }
         }
       }
+    },
+    {
+      "name": "BeforeTool builtin read_file without absolute_path stays native",
+      "call_class": "builtin",
+      "native": {
+        "hook_event_name": "BeforeTool",
+        "tool_name": "read_file",
+        "tool_input": {
+          "path": "/w/notes.txt"
+        }
+      },
+      "event": {
+        "schema_version": 1,
+        "event": "pre_tool",
+        "tool": "read_file",
+        "input": {
+          "path": "/w/notes.txt"
+        },
+        "this_call_vetoable": true,
+        "meta": {
+          "agent": "gemini",
+          "native_event": "BeforeTool",
+          "native_tool": "read_file",
+          "integration_mode": "external_hook",
+          "primary_gate_present": true,
+          "passthrough": {}
+        }
+      },
+      "render": {
+        "allow": {
+          "verdict": {
+            "decision": "allow"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false
+          }
+        }
+      }
+    },
+    {
+      "name": "BeforeTool builtin write_file without file_path stays native",
+      "call_class": "builtin",
+      "native": {
+        "hook_event_name": "BeforeTool",
+        "tool_name": "write_file",
+        "tool_input": {
+          "content": "hi"
+        }
+      },
+      "event": {
+        "schema_version": 1,
+        "event": "pre_tool",
+        "tool": "write_file",
+        "input": {
+          "content": "hi"
+        },
+        "this_call_vetoable": true,
+        "meta": {
+          "agent": "gemini",
+          "native_event": "BeforeTool",
+          "native_tool": "write_file",
+          "integration_mode": "external_hook",
+          "primary_gate_present": true,
+          "passthrough": {}
+        }
+      },
+      "render": {
+        "allow": {
+          "verdict": {
+            "decision": "allow"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false
+          }
+        }
+      }
     }
   ]
 }