agent-control-plane-core 0.5.2 → 0.6.0

package/types/control-plane.d.mts

@@ -76,63 +76,54 @@ export function assertGatedKinds(kinds: Set<string>, agent: string): void;
 export function isCoverageStatus(status: unknown): boolean;
 /**
  * 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: string | null, native?: Record<string, unknown>): string;
 /**
- * @typedef {object} EventMeta
- * @property {string} agent producing agent id ("claude", "codex", …)
- * @property {string} native_event original native event name, preserved verbatim
- * @property {string} [native_tool] original native tool name, preserved verbatim when `event.tool` was canonicalized (present iff the event carries a tool)
- * @property {"external_hook"|"in_process"|"observe_only"} integration_mode how the guardrail attaches
- * @property {boolean} primary_gate_present the agent's own native gate already ran (⇒ the monitor is a SECOND opinion; the LLM call can be skipped when the native gate already blocked)
- * @property {string} [session_id]
- * @property {string} [cwd]
- * @property {string} [permission_mode]
- * @property {string} [transcript_path]
- * @property {Record<string, unknown>} passthrough unmodelled native top-level fields, verbatim
- */
-/**
- * The result of rendering a {@link Verdict} for a specific agent's transport —
- * the ATTACH mechanism, not the decision. A caller applies whichever channels
- * are present: write `stdout`, exit with `exit_code`, or `throw`.
- * @typedef {object} NativeResponse
- * @property {"external_hook"|"in_process"|"observe_only"} transport
- * @property {number} exit_code process exit code carrying the decision (0 = proceed)
- * @property {boolean} enforced whether THIS render actually blocks (false ⇒ advisory only)
- * @property {unknown} [stdout] native JSON body to write to stdout, when the transport uses one
- * @property {string} [stderr] text the host reads from STDERR — the block reason on a transport (e.g. Gemini CLI's exit-2 System Block) that takes its rationale from stderr rather than the stdout body. The caller writes it to fd 2 before exiting.
- */
-/**
- * A normalized, agent-agnostic view of one agent event.
- * @typedef {object} ToolCallEvent
- * @property {number} schema_version stamped {@link SCHEMA_VERSION}
- * @property {"pre_tool"|"post_tool"|"prompt_submit"|"session_start"|"unknown"} event
- * @property {string|null} tool CANONICAL tool name — a native alias (e.g. Gemini's `run_shell_command`) is normalized to its {@link MODELED_TOOLS} canon (`Bash`); the raw native name is preserved on `meta.native_tool`. An unknown tool passes through verbatim. null for prompt/session events.
- * @property {Record<string, unknown>} input passthrough tool input; a submitted prompt is folded into `input.prompt`
- * @property {unknown} [response] tool output, post_tool only (string or structured), verbatim
- * @property {boolean} this_call_vetoable false ⇒ the guardrail cannot veto THIS call; a monitor must auto-degrade deny to notify, and any render of it stays advisory (never `enforced`)
- * @property {EventMeta} meta
- */
-/**
- * A normalized guardrail decision.
- * @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 {string} [additional_context] extra context to splice into the agent's stream
- * @property {string} [reason] human-readable rationale (shown on deny/ask)
+ * 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: Iterable<string>): ReadonlySet<string>;
 /**
  * The translator for one agent's protocol. `parse` maps a native event to a
  * {@link ToolCallEvent} (never throwing on unmodelled input, stamping the
@@ -144,6 +135,8 @@ export function classifyCallClass(tool: string | null, native?: Record<string, u
  * @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.
  */
 /**
  * Build a normalized {@link ToolCallEvent}, stamping the schema version. Pure —
@@ -208,6 +201,26 @@ export function sanitizeVerdict(verdict: unknown, sanitizeText: (text: string) =
  * @returns {Record<string, unknown>}
  */
 export function collectPassthrough(native: Record<string, unknown>, consumed: Set<string>): Record<string, unknown>;
+/**
+ * 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, }: {
+    agent: string;
+    native_event: string;
+    integration_mode: string;
+    primary_gate_present: boolean;
+    native: Record<string, unknown>;
+    consumed: Set<string>;
+}): EventMeta;
 /**
  * The value if it is a plain (non-array) object, else `{}`.
  * @param {unknown} value
@@ -275,6 +288,14 @@ export function nativeResponse({ transport, exit_code, enforced, stdout, stderr,
  * 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. */
 export const CONTROL_PLANE_SCHEMA: "control-plane/v1";
@@ -399,6 +420,111 @@ export const CoverageStatus: Readonly<{
     UNCOVERED: "uncovered";
     UNKNOWN: "unknown";
 }>;
+/**
+ * @typedef {object} EventMeta
+ * @property {string} agent producing agent id ("claude", "codex", …)
+ * @property {string} native_event original native event name, preserved verbatim
+ * @property {string} [native_tool] original native tool name, preserved verbatim when `event.tool` was canonicalized (present iff the event carries a tool)
+ * @property {"external_hook"|"in_process"|"observe_only"} integration_mode how the guardrail attaches
+ * @property {boolean} primary_gate_present the agent's own native gate already ran (⇒ the monitor is a SECOND opinion; the LLM call can be skipped when the native gate already blocked)
+ * @property {string} [session_id]
+ * @property {string} [cwd]
+ * @property {string} [permission_mode]
+ * @property {string} [transcript_path]
+ * @property {Record<string, unknown>} passthrough unmodelled native top-level fields, verbatim
+ */
+/**
+ * The result of rendering a {@link Verdict} for a specific agent's transport —
+ * the ATTACH mechanism, not the decision. A caller applies whichever channels
+ * are present: write `stdout`, exit with `exit_code`, or `throw`.
+ * @typedef {object} NativeResponse
+ * @property {"external_hook"|"in_process"|"observe_only"} transport
+ * @property {number} exit_code process exit code carrying the decision (0 = proceed)
+ * @property {boolean} enforced whether THIS render actually blocks (false ⇒ advisory only)
+ * @property {unknown} [stdout] native JSON body to write to stdout, when the transport uses one
+ * @property {string} [stderr] text the host reads from STDERR — the block reason on a transport (e.g. Gemini CLI's exit-2 System Block) that takes its rationale from stderr rather than the stdout body. The caller writes it to fd 2 before exiting.
+ */
+/**
+ * A normalized, agent-agnostic view of one agent event.
+ * @typedef {object} ToolCallEvent
+ * @property {number} schema_version stamped {@link SCHEMA_VERSION}
+ * @property {"pre_tool"|"post_tool"|"prompt_submit"|"session_start"|"unknown"} event
+ * @property {string|null} tool CANONICAL tool name — a native alias (e.g. Gemini's `run_shell_command`) is normalized to its {@link MODELED_TOOLS} canon (`Bash`); the raw native name is preserved on `meta.native_tool`. An unknown tool passes through verbatim. null for prompt/session events.
+ * @property {Record<string, unknown>} input passthrough tool input; a submitted prompt is folded into `input.prompt`
+ * @property {unknown} [response] tool output, post_tool only (string or structured), verbatim
+ * @property {boolean} this_call_vetoable false ⇒ the guardrail cannot veto THIS call; a monitor must auto-degrade deny to notify, and any render of it stays advisory (never `enforced`)
+ * @property {EventMeta} meta
+ */
+/**
+ * A normalized guardrail decision.
+ * @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 `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: readonly string[];
+/**
+ * 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<string>;
+/**
+ * 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: readonly string[];
+/**
+ * The translator for one agent's protocol. `parse` maps a native event to a
+ * {@link ToolCallEvent} (never throwing on unmodelled input, stamping the
+ * integration mode / enforcement flags on `meta`); `render` maps a {@link Verdict}
+ * to that agent's native transport ({@link NativeResponse}), not just a JSON body.
+ */
+export type Adapter = {
+    AGENT: string;
+    INTEGRATION_MODE: "external_hook" | "in_process" | "observe_only";
+    /**
+     * per-{@link CallClass} hook-coverage status; must classify every {@link CALL_CLASSES} entry
+     */
+    COVERAGE: Record<string, "covered" | "partial" | "uncovered" | "unknown">;
+    parse: (native: any) => ToolCallEvent;
+    render: (verdict: Verdict, event: ToolCallEvent, options?: {
+        soleGate?: boolean;
+    }) => NativeResponse;
+    /**
+     * 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`.
+     */
+    NATIVE_EVENT_FOR?: Record<string, string | undefined> | undefined;
+    /**
+     * 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.
+     */
+    UNRENDERED_FIELDS: Record<string, ReadonlySet<string> | undefined>;
+};
+export type CoverageStatusValue = "covered" | "partial" | "uncovered" | "unknown";
+/**
+ * a per-{@link CallClass} coverage map (an adapter's `COVERAGE`)
+ */
+export type CoverageMap = Record<string, CoverageStatusValue>;
 export type EventMeta = {
     /**
      * producing agent id ("claude", "codex", …)
@@ -490,7 +616,7 @@ export type Verdict = {
      */
     mutated_input?: Record<string, unknown> | undefined;
     /**
-     * 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).
+     * 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).
      */
     mutated_output?: unknown;
     /**
@@ -502,26 +628,3 @@ export type Verdict = {
      */
     reason?: string | undefined;
 };
-/**
- * The translator for one agent's protocol. `parse` maps a native event to a
- * {@link ToolCallEvent} (never throwing on unmodelled input, stamping the
- * integration mode / enforcement flags on `meta`); `render` maps a {@link Verdict}
- * to that agent's native transport ({@link NativeResponse}), not just a JSON body.
- */
-export type Adapter = {
-    AGENT: string;
-    INTEGRATION_MODE: "external_hook" | "in_process" | "observe_only";
-    /**
-     * per-{@link CallClass} hook-coverage status; must classify every {@link CALL_CLASSES} entry
-     */
-    COVERAGE: Record<string, "covered" | "partial" | "uncovered" | "unknown">;
-    parse: (native: any) => ToolCallEvent;
-    render: (verdict: Verdict, event: ToolCallEvent, options?: {
-        soleGate?: boolean;
-    }) => NativeResponse;
-};
-export type CoverageStatusValue = "covered" | "partial" | "uncovered" | "unknown";
-/**
- * a per-{@link CallClass} coverage map (an adapter's `COVERAGE`)
- */
-export type CoverageMap = Record<string, CoverageStatusValue>;

package/types/index.d.mts

@@ -2,6 +2,6 @@ export * from "./control-plane.mjs";
 export { codexAdapter } from "./adapters/codex.mjs";
 export { ampAdapter } from "./adapters/amp.mjs";
 export { claudeAdapter, HookEvent } from "./adapters/claude.mjs";
-export { geminiAdapter, GEMINI_TOOL_ALIASES } from "./adapters/gemini.mjs";
+export { geminiAdapter, GEMINI_TOOL_ALIASES, POST_TOOL_REDACTION_UNSUPPORTED } from "./adapters/gemini.mjs";
 export { ADAPTERS, AGENT_IDS, adapterFor, assertRegistryConsistent } from "./registry.mjs";
 export { runAdapterConformance, assertCoverageWellFormed, assertToolAliasesCovered, assertAliasedInputsCanonical } from "./conformance.mjs";