agent-control-plane-core 0.1.0 → 0.2.0

package/types/adapters/gemini.d.mts

@@ -0,0 +1,73 @@
+/**
+ * Parse a raw Gemini CLI hook payload into a normalized {@link ToolCallEvent}.
+ * Never throws on an unmodelled event type or tool-input field. A payload comes
+ * from a hooks-capable Gemini (v0.26.0+) whose `BeforeTool` can pre-empt builtin
+ * tools via exit 2. But MCP firing is only medium-confidence (COVERAGE.mcp is
+ * UNKNOWN), so an MCP-sourced call — flagged by `mcp_context` or an `mcp_`-named
+ * tool — parses non-vetoable until an item-⑤ probe confirms the hook fires.
+ * `BeforeAgent` (fires after the user submits a prompt, before planning) maps to
+ * `prompt_submit`: no tool, the submitted text folded into `input.prompt`.
+ * @param {any} native
+ * @returns {ToolCallEvent}
+ */
+export function parse(native: any): ToolCallEvent;
+/**
+ * Render into Gemini CLI's native external-hook transport. An enforceable deny
+ * renders as exit 2 (the System Block on BeforeTool; documented on BeforeAgent
+ * as "same as decision: deny" — it aborts the turn); everything else exits 0
+ * with a JSON decision body (or none, when `allow` abstains). `soleGate`
+ * (default false) is the same dangerous opt-in as the other adapters: it makes
+ * an `allow` emit the real `decision: "allow"` instead of abstaining (tool
+ * events only — BeforeAgent documents no allow behavior to opt into).
+ * @param {Verdict} verdict
+ * @param {ToolCallEvent} event
+ * @param {{ soleGate?: boolean }} [options]
+ * @returns {NativeResponse}
+ */
+export function render(verdict: Verdict, event: ToolCallEvent, { soleGate }?: {
+    soleGate?: boolean;
+}): NativeResponse;
+/** @typedef {import("../control-plane.mjs").ToolCallEvent} ToolCallEvent */
+/** @typedef {import("../control-plane.mjs").Verdict} Verdict */
+/** @typedef {import("../control-plane.mjs").EventMeta} EventMeta */
+/** @typedef {import("../control-plane.mjs").NativeResponse} NativeResponse */
+export const AGENT: "gemini";
+export const INTEGRATION_MODE: "external_hook";
+/**
+ * Hook-coverage matrix row (`docs/hook-coverage-matrix.md`). `BeforeTool` gates
+ * builtins on v0.26+ (COVERED). MCP routing through the same matcher is only
+ * MEDIUM-confidence and unproven, subagent firing for a loaded agent is
+ * undocumented, and resumed-session behavior has no source — all three are
+ * UNKNOWN, held at fail-closed until an item-⑤ probe upgrades them. A guessed ✅
+ * here would be a silent fail-open.
+ */
+/** @type {import("../control-plane.mjs").CoverageMap} */
+export const COVERAGE: import("../control-plane.mjs").CoverageMap;
+/** Gemini CLI native hook event names (the `hook_event_name` field). */
+export const HookEvent: Readonly<{
+    BEFORE_TOOL: "BeforeTool";
+    AFTER_TOOL: "AfterTool";
+    BEFORE_AGENT: "BeforeAgent";
+}>;
+/**
+ * Adapter-scoped native-builtin → canonical tool aliases, applied ONLY when a
+ * call classifies as BUILTIN. These names are too generic for the global
+ * {@link TOOL_ALIASES} (an MCP server could export a `read_file`), but Gemini
+ * CLI removes the ambiguity at parse time: every MCP tool is unconditionally
+ * registered — and surfaced in hook payloads — under its fully qualified
+ * `mcp_{server}_{tool}` name (gemini-cli docs/tools/mcp-server.md), so a bare
+ * builtin name in `tool_name` can only be the builtin. The builtin's native
+ * input fields still pass through verbatim (e.g. read_file's `absolute_path`,
+ * not Read's `file_path`) — `meta.native_tool` tells a consumer which field
+ * dialect to expect. Targets are pinned to {@link MODELED_TOOLS} at import, and
+ * every entry must be witnessed by a gemini conformance fixture
+ * (`assertToolAliasesCovered`).
+ * @type {Readonly<Record<string, string>>}
+ */
+export const GEMINI_TOOL_ALIASES: Readonly<Record<string, string>>;
+/** @type {import("../control-plane.mjs").Adapter} */
+export const geminiAdapter: import("../control-plane.mjs").Adapter;
+export type ToolCallEvent = import("../control-plane.mjs").ToolCallEvent;
+export type Verdict = import("../control-plane.mjs").Verdict;
+export type EventMeta = import("../control-plane.mjs").EventMeta;
+export type NativeResponse = import("../control-plane.mjs").NativeResponse;

package/types/conformance.d.mts

@@ -0,0 +1,83 @@
+/**
+ * Assert an adapter's {@link import("./control-plane.mjs").Adapter.COVERAGE}
+ * hook-coverage matrix is well-formed: it classifies EXACTLY the canonical
+ * {@link CALL_CLASSES} (no class missing, none unknown) and every value is a
+ * valid coverage status. This is the SSOT gate — adding a new call class to the
+ * contract fails every adapter until it declares that class, so a coverage hole
+ * can't be introduced by omission.
+ * @param {import("./control-plane.mjs").Adapter} adapter
+ * @param {any} assert node:assert/strict (injected)
+ */
+export function assertCoverageWellFormed(adapter: import("./control-plane.mjs").Adapter, assert: any): void;
+/**
+ * Assert every tool alias — the global {@link TOOL_ALIASES} entries AND each
+ * adapter-scoped alias map — is WITNESSED by a golden fixture: a case whose
+ * native tool name equals the alias key and whose normalized `event.tool`
+ * equals the canonical target. This is what ties the alias SSOTs to the
+ * fixtures: an alias added without a golden payload that exercises it fails
+ * here, so an alias "a new judge keys on" can't ship unproven. A global alias
+ * may be witnessed by any agent's fixtures; an adapter-scoped alias must be
+ * witnessed by THAT agent's fixtures (another agent's payload proves nothing
+ * about the scoping adapter's parse). Also cross-checks each witnessed pair:
+ * `event.tool` must be either the global {@link canonicalTool} result or the
+ * owning adapter's scoped target, so a fixture that preserved `native_tool` but
+ * mis-normalized `event.tool` is caught — including a scoped alias applied by
+ * the wrong agent's fixtures.
+ * @param {any[]} fixturesList the golden fixtures for every shipped adapter
+ * @param {any} assert node:assert/strict (injected)
+ * @param {Record<string, Record<string, string>>} [adapterAliases] agent id → that adapter's scoped alias map (e.g. `{ gemini: GEMINI_TOOL_ALIASES }`)
+ */
+export function assertToolAliasesCovered(fixturesList: any[], assert: any, adapterAliases?: Record<string, Record<string, string>>): void;
+/**
+ * The control-plane conformance harness.
+ *
+ * Any adapter — the reference claude one, codex, or a future
+ * cursor/cline/gemini-cli/aider translator — must pass this against its own
+ * golden fixtures. It pins the two directions of the contract:
+ *
+ *   1. parse is golden: adapter.parse(native) deep-equals the fixture's
+ *      normalized `event` (and never throws — an adapter that threw would fail
+ *      here rather than in production).
+ *   2. render is golden: for each verdict scenario, adapter.render(verdict,
+ *      parsedEvent) deep-equals the fixture's native response. An `allow` with
+ *      the unmutated input renders to the agent's native allow; deny/ask/mutation
+ *      each render to their native shape.
+ *   3. non-vacuity: the fixture set collectively renders an allow, a deny, an
+ *      ask, AND a mutated_input, so a suite can't pass while silently skipping a
+ *      decision the contract requires every adapter to express.
+ *   4. enforcement honesty: an enforceable deny (`rendered.enforced === true`)
+ *      MUST carry a real block signal — a non-zero `exit_code` — not just a JSON
+ *      body the agent is free to ignore. At least one enforced deny must appear,
+ *      so the honesty check is never vacuous.
+ *   5. non-vetoable honesty: when the parsed event's `this_call_vetoable` is
+ *      false, EVERY render for that case must be `enforced === false` — a
+ *      guardrail that cannot veto this call must never render as if it did.
+ *   6. allow = abstain: by default (no `soleGate` opt-in) every `allow` render
+ *      is `enforced === false` AND `exit_code === 0` — an "I have no objection"
+ *      verdict never renders as a block, on any adapter. At least one `allow`
+ *      must be rendered, so this is never vacuous.
+ *   7. coverage honesty: the adapter's COVERAGE matrix is well-formed (item ③),
+ *      and a fixture case tagged with a `call_class` whose coverage does NOT
+ *      permit a veto (uncovered/unknown — an ❓ is treated as ❌) MUST parse to
+ *      `this_call_vetoable: false`. An adapter cannot claim a class is un-gated
+ *      while parsing its calls as vetoable.
+ *
+ * `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, enforcedDenySeen: boolean, coverageClassesChecked: Set<string> }}
+ */
+export function runAdapterConformance({ adapter, fixtures, assert }: {
+    adapter: import("./control-plane.mjs").Adapter;
+    fixtures: any;
+    assert: any;
+}): {
+    cases: number;
+    renders: number;
+    decisionsSeen: Set<string>;
+    mutationSeen: boolean;
+    enforcedDenySeen: boolean;
+    coverageClassesChecked: Set<string>;
+};

package/types/control-plane.d.mts

@@ -0,0 +1,454 @@
+/**
+ * Load-bearing use of MODELED_TOOLS: assert every alias target is a modeled
+ * tool, so the alias SSOT can never normalize a native name onto a canon the
+ * contract doesn't model. Throws (fail loud) on the first bad target — a typo'd
+ * target is a bug, not a silent passthrough. Called at import against
+ * {@link TOOL_ALIASES}, and by adapters against their adapter-scoped alias
+ * maps; exported so a test can drive both branches.
+ * @param {Record<string, string>} aliases
+ */
+export function assertAliasTargetsModeled(aliases: Record<string, string>): void;
+/**
+ * Canonicalize a native tool name to its {@link MODELED_TOOLS} equivalent, or
+ * return it UNCHANGED when it is not a known alias — an unknown tool is never
+ * silently reclassified. `null` (a non-tool event) passes through as `null`.
+ * @param {string|null} tool native tool name
+ * @returns {string|null} the canonical name, or the native name verbatim
+ */
+export function canonicalTool(tool: string | null): string | null;
+/**
+ * Whether a coverage status PERMITS an adapter to mark a call in that class
+ * `this_call_vetoable: true`. Only a hook confirmed to fire does: COVERED, or
+ * PARTIAL (for the tools in its covered subset). UNCOVERED and UNKNOWN both
+ * forbid it — an unknown is fail-closed to uncovered, which is the whole point
+ * of the matrix. Throws on an unrecognized status (fail loud — a typo must not
+ * quietly read as "permitted").
+ * @param {string} status a {@link CoverageStatus} value
+ * @returns {boolean}
+ */
+export function coverageAllowsVeto(status: string): boolean;
+/**
+ * True when `status` is a recognized {@link CoverageStatus} value.
+ * @param {unknown} status
+ * @returns {boolean}
+ */
+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.
+ * @param {string|null} tool tool name (null for non-tool events)
+ * @param {Record<string, unknown>} [native] the raw native payload, for `mcp_context`
+ * @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
+ */
+/**
+ * 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)
+ */
+/**
+ * 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.
+ * @typedef {object} Adapter
+ * @property {string} AGENT
+ * @property {"external_hook"|"in_process"|"observe_only"} INTEGRATION_MODE
+ * @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
+ */
+/**
+ * Build a normalized {@link ToolCallEvent}, stamping the schema version. Pure —
+ * adapters pass already-normalized parts. `response` is omitted unless defined
+ * so a pre_tool event has no `response` key at all.
+ * @param {{ event: string, tool: string|null, input: Record<string, unknown>, response?: unknown, this_call_vetoable: boolean, meta: EventMeta }} parts
+ * @returns {ToolCallEvent}
+ */
+export function makeEvent({ event, tool, input, response, this_call_vetoable, meta, }: {
+    event: string;
+    tool: string | null;
+    input: Record<string, unknown>;
+    response?: unknown;
+    this_call_vetoable: boolean;
+    meta: EventMeta;
+}): ToolCallEvent;
+/**
+ * Validate and normalize a {@link Verdict}. The decision must be one of
+ * allow/deny/ask — a verdict is produced internally, so an out-of-range
+ * decision is a bug and throws (fail loud), unlike the pass-through tolerance
+ * `parse` extends to untrusted upstream events. Returns a fresh object carrying
+ * only the modeled optional fields that are present; never mutates its input.
+ * @param {Verdict} verdict
+ * @returns {Verdict}
+ */
+export function normalizeVerdict(verdict: Verdict): Verdict;
+/**
+ * Harden an UNTRUSTED {@link Verdict} — one authored by a separate
+ * monitor/judge process (e.g. claude-guard's scrub-monitor-response) — before
+ * it is rendered. Two defenses:
+ *
+ *   1. Decision clamp (fail-to-ask): a `decision` outside allow/deny/ask
+ *      becomes `"ask"`, and the clamp is made observable by appending a
+ *      bracketed note to `reason` naming the rejected value — a malformed
+ *      monitor answer escalates to a human instead of throwing (the internal
+ *      strictness of {@link normalizeVerdict}) or silently allowing.
+ *   2. Text scrubbing: the caller-supplied `sanitizeText` runs over every
+ *      monitor-authored PROSE field present — `reason` and
+ *      `additional_context` (a non-string value in either is dropped; prose
+ *      channels carry strings). `mutated_input`/`mutated_output` are NOT
+ *      sanitized: they are data channels (replacement tool input/output the
+ *      guardrail computed, often deliberately containing the very bytes a text
+ *      scrubber would mangle), not monitor-authored prose. `mutated_input` is
+ *      shape-checked only (a non-object is dropped — see the inline note);
+ *      `mutated_output` is carried verbatim.
+ *
+ * `sanitizeText` is injected so this module stays dependency-free. It must be
+ * a function and must return a string — a sanitizer that eats the value is a
+ * bug, so a non-string return throws. Returns a fresh normalized verdict;
+ * never mutates its input.
+ * @param {unknown} verdict the untrusted verdict object
+ * @param {(text: string) => string} sanitizeText
+ * @returns {Verdict}
+ */
+export function sanitizeVerdict(verdict: unknown, sanitizeText: (text: string) => string): Verdict;
+/**
+ * Return a shallow copy of `native` with the `consumed` keys removed — the
+ * unmodelled remainder an adapter carries in `meta.passthrough` so an additive
+ * upstream field survives instead of being silently dropped.
+ * @param {Record<string, unknown>} native
+ * @param {Set<string>} consumed
+ * @returns {Record<string, unknown>}
+ */
+export function collectPassthrough(native: Record<string, unknown>, consumed: Set<string>): Record<string, unknown>;
+/**
+ * The value if it is a plain (non-array) object, else `{}`.
+ * @param {unknown} value
+ * @returns {Record<string, unknown>}
+ */
+export function asObject(value: unknown): Record<string, unknown>;
+/**
+ * The value if it is a string, else `null`.
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+export function asStringOrNull(value: unknown): string | null;
+/**
+ * The value if it is a string, else `fallback`.
+ * @param {unknown} value
+ * @param {string} fallback
+ * @returns {string}
+ */
+export function asString(value: unknown, fallback: string): string;
+/**
+ * Assemble a {@link NativeResponse}, omitting an absent `stdout` so a pure
+ * exit-code transport carries no `stdout` key.
+ * @param {{ transport: string, exit_code: number, enforced: boolean, stdout?: unknown }} parts
+ * @returns {NativeResponse}
+ */
+export function nativeResponse({ transport, exit_code, enforced, stdout }: {
+    transport: string;
+    exit_code: number;
+    enforced: boolean;
+    stdout?: unknown;
+}): NativeResponse;
+/**
+ * The vendor-neutral control-plane contract.
+ *
+ * This is the published seam between an agent's native hook/tool-call protocol
+ * and claude-guard's guardrails (monitor, deny-match, redaction, sanitizers).
+ * It defines TWO normalized shapes — {@link ToolCallEvent} (what an agent is
+ * about to / just did) and {@link Verdict} (what the guardrail decided) — plus
+ * the {@link Adapter} pair that translates a specific agent's protocol to and
+ * from them. Every downstream consumer imports THESE types, never an agent's
+ * raw hook JSON; the agent-specific field names live only in that agent's
+ * adapter (see adapter-claude.mjs / adapter-codex.mjs).
+ *
+ * DRIFT DISCIPLINE — the reason the seam earns its keep. An agent protocol
+ * drifts additively and independently (N agents, N release cadences). So an
+ * adapter's `parse` MUST NOT throw on an event type or tool-input field it does
+ * not model: the unmodelled remainder is carried through verbatim (an unknown
+ * event becomes {@link EventKind.UNKNOWN} with its native name preserved; extra
+ * top-level fields land in `meta.passthrough`). An additive upstream change is
+ * then a no-op here, not an outage. The core models ONLY the stable middle:
+ * four event kinds, three decisions, and the Bash/Edit/Write/Read/WebFetch tool
+ * inputs. Exotic per-agent tools pass through untouched.
+ *
+ * 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},
+ * {@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
+ * deliberate, reviewed version bump). ADDING to the contract (a new optional
+ * 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.
+ */
+/** Wire identifier for this schema version; bump on a breaking shape change. */
+export const CONTROL_PLANE_SCHEMA: "control-plane/v1";
+/** Numeric schema version stamped onto every {@link ToolCallEvent}. */
+export const SCHEMA_VERSION: 1;
+/**
+ * The normalized event kinds the core models. A native event that maps to none
+ * of these is carried as {@link EventKind.UNKNOWN} with its native name kept in
+ * `meta.native_event`.
+ */
+export const EventKind: Readonly<{
+    PRE_TOOL: "pre_tool";
+    POST_TOOL: "post_tool";
+    PROMPT_SUBMIT: "prompt_submit";
+    SESSION_START: "session_start";
+    UNKNOWN: "unknown";
+}>;
+/** The normalized verdict decisions a guardrail can return. */
+export const Decision: Readonly<{
+    ALLOW: "allow";
+    DENY: "deny";
+    ASK: "ask";
+}>;
+/**
+ * Tools whose input shape the core models. Every other tool passes through
+ * unmodelled — its input object is preserved verbatim and no field is required.
+ */
+export const MODELED_TOOLS: readonly string[];
+/**
+ * Native-tool-name → canonical {@link MODELED_TOOLS} name. The SSOT that lets a
+ * judge key on `event.tool` without a per-agent lookup: an agent whose native
+ * name for the shell tool is `run_shell_command` (Gemini) is normalized to the
+ * same `Bash` a Claude/Codex/Amp payload already carries, with the raw native
+ * name preserved on `meta.native_tool`. Only globally-unambiguous native
+ * BUILTIN names belong here — a name that also occurs as an MCP tool (e.g. a
+ * `read_file` MCP server) must NOT be aliased, or the normalization would
+ * reclassify an unrelated tool. An adapter whose host makes such a name
+ * unambiguous at parse time (Gemini's `mcp_{server}_{tool}` FQN discipline)
+ * may carry its own ADAPTER-SCOPED alias map instead (see the gemini adapter's
+ * `GEMINI_TOOL_ALIASES`), applied only to calls classified BUILTIN. An unknown
+ * tool is never in the map, so it passes through verbatim (see
+ * {@link canonicalTool}). Every target is a
+ * {@link MODELED_TOOLS} member (enforced at load below), and every entry is
+ * witnessed by a conformance fixture (see `assertToolAliasesCovered`), so an
+ * alias cannot be added without a golden payload that exercises it.
+ */
+export const TOOL_ALIASES: Readonly<{
+    run_shell_command: "Bash";
+}>;
+/**
+ * How a guardrail ATTACHES to an agent — the transport, kept separate from the
+ * normalized decision so the judge/Verdict core stays transport-agnostic:
+ *   - EXTERNAL_HOOK: the agent shells out to a hook (stdin JSON → deny body /
+ *     exit code). The decision can pre-empt the tool call.
+ *   - IN_PROCESS: an embedded analyzer or a driven confirm/reject loop over the
+ *     agent's own API. Can pre-empt.
+ *   - OBSERVE_ONLY: transcript reader; cannot pre-empt, so its Verdict is
+ *     advisory — the hard stop is the sandbox, not the hook.
+ */
+export const IntegrationMode: Readonly<{
+    EXTERNAL_HOOK: "external_hook";
+    IN_PROCESS: "in_process";
+    OBSERVE_ONLY: "observe_only";
+}>;
+/**
+ * The CLASSES of tool call a host may or may not route through its pre-tool
+ * guardrail hook. Whether the hook fires is orthogonal to the tool's INPUT shape
+ * (which {@link MODELED_TOOLS} covers) — a host can gate its builtin tools while
+ * an MCP-sourced or subagent-spawned call of the SAME tool never reaches the
+ * hook. Each adapter declares a coverage status per class (see the adapter
+ * `COVERAGE` maps and `docs/hook-coverage-matrix.md`); the conformance harness
+ * enforces that an uncovered class is never marked `this_call_vetoable`.
+ */
+export const CallClass: Readonly<{
+    BUILTIN: "builtin";
+    MCP: "mcp";
+    SUBAGENT: "subagent";
+    RESUMED: "resumed";
+}>;
+/** Canonical ordered list of {@link CallClass} values — the SSOT every adapter's `COVERAGE` must classify exactly. */
+export const CALL_CLASSES: readonly ("builtin" | "mcp" | "subagent" | "resumed")[];
+/**
+ * Whether a host's pre-tool hook fires for a {@link CallClass} — the machine
+ * form of the ✅/❌/⚠️/❓ matrix:
+ *   - COVERED (✅): the hook fires for every tool in the class.
+ *   - PARTIAL (⚠️): it fires for only SOME tools in the class (e.g. Codex gates
+ *     Bash but not other builtins) — a call in the covered subset may be vetoed.
+ *   - UNCOVERED (❌): it never fires; the call reaches the tool un-gated.
+ *   - UNKNOWN (❓): undocumented — NOT yet proven to fire by a live probe.
+ * The doctrine (`docs/hook-coverage-matrix.md`): an UNKNOWN is treated as
+ * UNCOVERED until a probe proves ✅, because a guessed ✅ is a silent fail-open.
+ */
+export const CoverageStatus: Readonly<{
+    COVERED: "covered";
+    PARTIAL: "partial";
+    UNCOVERED: "uncovered";
+    UNKNOWN: "unknown";
+}>;
+export type EventMeta = {
+    /**
+     * producing agent id ("claude", "codex", …)
+     */
+    agent: string;
+    /**
+     * original native event name, preserved verbatim
+     */
+    native_event: string;
+    /**
+     * original native tool name, preserved verbatim when `event.tool` was canonicalized (present iff the event carries a tool)
+     */
+    native_tool?: string | undefined;
+    /**
+     * how the guardrail attaches
+     */
+    integration_mode: "external_hook" | "in_process" | "observe_only";
+    /**
+     * 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)
+     */
+    primary_gate_present: boolean;
+    session_id?: string | undefined;
+    cwd?: string | undefined;
+    permission_mode?: string | undefined;
+    transcript_path?: string | undefined;
+    /**
+     * unmodelled native top-level fields, verbatim
+     */
+    passthrough: Record<string, unknown>;
+};
+/**
+ * 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`.
+ */
+export type NativeResponse = {
+    transport: "external_hook" | "in_process" | "observe_only";
+    /**
+     * process exit code carrying the decision (0 = proceed)
+     */
+    exit_code: number;
+    /**
+     * whether THIS render actually blocks (false ⇒ advisory only)
+     */
+    enforced: boolean;
+    /**
+     * native JSON body to write to stdout, when the transport uses one
+     */
+    stdout?: unknown;
+};
+/**
+ * A normalized, agent-agnostic view of one agent event.
+ */
+export type ToolCallEvent = {
+    /**
+     * stamped {@link SCHEMA_VERSION}
+     */
+    schema_version: number;
+    event: "pre_tool" | "post_tool" | "prompt_submit" | "session_start" | "unknown";
+    /**
+     * 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.
+     */
+    tool: string | null;
+    /**
+     * passthrough tool input; a submitted prompt is folded into `input.prompt`
+     */
+    input: Record<string, unknown>;
+    /**
+     * tool output, post_tool only (string or structured), verbatim
+     */
+    response?: unknown;
+    /**
+     * false ⇒ the guardrail cannot veto THIS call; a monitor must auto-degrade deny to notify, and any render of it stays advisory (never `enforced`)
+     */
+    this_call_vetoable: boolean;
+    meta: EventMeta;
+};
+/**
+ * A normalized guardrail decision.
+ */
+export type Verdict = {
+    decision: "allow" | "deny" | "ask";
+    /**
+     * replacement tool input (pre_tool)
+     */
+    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).
+     */
+    mutated_output?: unknown;
+    /**
+     * extra context to splice into the agent's stream
+     */
+    additional_context?: string | undefined;
+    /**
+     * human-readable rationale (shown on deny/ask)
+     */
+    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

@@ -0,0 +1,7 @@
+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 { ADAPTERS, AGENT_IDS, adapterFor, assertRegistryConsistent } from "./registry.mjs";
+export { runAdapterConformance, assertCoverageWellFormed, assertToolAliasesCovered } from "./conformance.mjs";

package/types/registry.d.mts

@@ -0,0 +1,35 @@
+/**
+ * Assert every {@link ADAPTERS} key equals its adapter's own `AGENT`. A registry
+ * whose id disagrees with the adapter it resolves is a latent selector/dispatcher
+ * split, so this throws (fail loud) rather than resolving a surprising adapter.
+ * Called at import against {@link ADAPTERS}; exported so the conformance suite can
+ * drive it against a constructed-bad map too.
+ * @param {Record<string, Adapter>} adapters
+ */
+export function assertRegistryConsistent(adapters: Record<string, Adapter>): void;
+/**
+ * Resolve an agent id to its adapter. Throws (fail loud) on an unknown id — a
+ * selection signal that names no shipped adapter is a misconfiguration, not a
+ * reason to silently fall back to a default agent (which would run the wrong
+ * translator against the payloads and mis-render every verdict).
+ * @param {string} id agent id (a {@link AGENT_IDS} member)
+ * @returns {Adapter}
+ */
+export function adapterFor(id: string): Adapter;
+/** @typedef {import("./control-plane.mjs").Adapter} Adapter */
+/**
+ * Every shipped adapter. Adding an adapter to the package means adding it here —
+ * the registry is the enrollment point, and {@link assertRegistryConsistent}
+ * (run at import and in the conformance suite) fails if a key does not equal its
+ * adapter's `AGENT`, so a typo'd or mismatched id cannot ship.
+ * @type {Readonly<Record<string, Adapter>>}
+ */
+export const ADAPTERS: Readonly<Record<string, Adapter>>;
+/**
+ * The canonical set of agent ids, frozen — the closed vocabulary a launch
+ * signal is validated against. Derived from {@link ADAPTERS} so it cannot list
+ * an id the registry does not resolve.
+ * @type {readonly string[]}
+ */
+export const AGENT_IDS: readonly string[];
+export type Adapter = import("./control-plane.mjs").Adapter;