agent-control-plane-core 0.1.0 → 0.2.0

package/src/conformance.mjs

@@ -1,3 +1,107 @@
+import {
+  CALL_CLASSES,
+  TOOL_ALIASES,
+  canonicalTool,
+  coverageAllowsVeto,
+  isCoverageStatus,
+} from "./control-plane.mjs";
+
+/**
+ * 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, assert) {
+  assert.ok(
+    adapter.COVERAGE && typeof adapter.COVERAGE === "object",
+    `adapter '${adapter.AGENT}' declares no COVERAGE matrix`,
+  );
+  const declared = Object.keys(adapter.COVERAGE).sort();
+  assert.deepEqual(
+    declared,
+    [...CALL_CLASSES].sort(),
+    `adapter '${adapter.AGENT}' COVERAGE must classify exactly the call classes ${JSON.stringify([...CALL_CLASSES])}`,
+  );
+  for (const cls of CALL_CLASSES) {
+    assert.ok(
+      isCoverageStatus(adapter.COVERAGE[cls]),
+      `adapter '${adapter.AGENT}' COVERAGE.${cls} is not a valid coverage status: ${JSON.stringify(adapter.COVERAGE[cls])}`,
+    );
+  }
+}
+
+/**
+ * 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,
+  assert,
+  adapterAliases = {},
+) {
+  /** @type {Map<string, Map<string, Set<string>>>} agent → native tool name → canonical names seen */
+  const witnessedByAgent = new Map();
+  for (const fixtures of fixturesList) {
+    let witnessed = witnessedByAgent.get(fixtures.agent);
+    if (witnessed === undefined)
+      witnessedByAgent.set(fixtures.agent, (witnessed = new Map()));
+    const scopedMap = adapterAliases[fixtures.agent] ?? {};
+    for (const testCase of fixtures.cases) {
+      const nativeTool = testCase.event?.meta?.native_tool;
+      if (typeof nativeTool !== "string") continue;
+      const canon = testCase.event.tool;
+      const allowed = new Set([canonicalTool(nativeTool)]);
+      if (scopedMap[nativeTool] !== undefined)
+        allowed.add(scopedMap[nativeTool]);
+      assert.ok(
+        allowed.has(canon),
+        `fixture '${testCase.name}' (${fixtures.agent}): native_tool ${JSON.stringify(nativeTool)} normalized to ${JSON.stringify(canon)}, but only ${JSON.stringify([...allowed])} are valid canonicalizations for this agent`,
+      );
+      let canons = witnessed.get(nativeTool);
+      if (canons === undefined) witnessed.set(nativeTool, (canons = new Set()));
+      canons.add(canon);
+    }
+  }
+  /** @type {(nativeName: string, canonical: string) => boolean} */
+  const witnessedAnywhere = (nativeName, canonical) =>
+    [...witnessedByAgent.values()].some((w) =>
+      w.get(nativeName)?.has(canonical),
+    );
+  for (const [nativeName, canonical] of Object.entries(TOOL_ALIASES)) {
+    assert.ok(
+      witnessedAnywhere(nativeName, canonical),
+      `tool alias ${JSON.stringify(nativeName)} -> ${JSON.stringify(canonical)} is not witnessed by any conformance fixture — add a golden case whose native tool is ${JSON.stringify(nativeName)}`,
+    );
+  }
+  for (const [agent, scopedMap] of Object.entries(adapterAliases)) {
+    for (const [nativeName, canonical] of Object.entries(scopedMap)) {
+      assert.ok(
+        witnessedByAgent.get(agent)?.get(nativeName)?.has(canonical),
+        `adapter-scoped tool alias ${JSON.stringify(nativeName)} -> ${JSON.stringify(canonical)} (${agent}) is not witnessed by a '${agent}' conformance fixture — add a golden ${agent} case whose native tool is ${JSON.stringify(nativeName)}`,
+      );
+    }
+  }
+}
+
 /**
  * The control-plane conformance harness.
  *
@@ -16,9 +120,9 @@
  *      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` or a `throw_` —
- *      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.
+ *      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.
@@ -26,13 +130,18 @@
  *      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 }}
+ * @returns {{ cases: number, renders: number, decisionsSeen: Set<string>, mutationSeen: boolean, enforcedDenySeen: boolean, coverageClassesChecked: Set<string> }}
  */
 export function runAdapterConformance({ adapter, fixtures, assert }) {
   assert.equal(
@@ -41,8 +150,12 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
     `adapter AGENT '${adapter.AGENT}' does not match fixtures.agent '${fixtures.agent}'`,
   );
 
+  assertCoverageWellFormed(adapter, assert);
+
   /** @type {Set<string>} */
   const decisionsSeen = new Set();
+  /** @type {Set<string>} call classes exercised by a tagged fixture case */
+  const coverageClassesChecked = new Set();
   let mutationSeen = false;
   let enforcedDenySeen = false;
   let renders = 0;
@@ -55,6 +168,21 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
       `parse mismatch: ${testCase.name}`,
     );
 
+    if (testCase.call_class !== undefined) {
+      assert.ok(
+        CALL_CLASSES.includes(testCase.call_class),
+        `unknown call_class '${testCase.call_class}': ${testCase.name}`,
+      );
+      if (!coverageAllowsVeto(adapter.COVERAGE[testCase.call_class])) {
+        assert.equal(
+          parsed.this_call_vetoable,
+          false,
+          `call_class '${testCase.call_class}' is ${adapter.COVERAGE[testCase.call_class]} (no veto) but parsed this_call_vetoable !== false: ${testCase.name}`,
+        );
+      }
+      coverageClassesChecked.add(testCase.call_class);
+    }
+
     for (const [scenario, raw] of Object.entries(testCase.render)) {
       const spec = /** @type {{ verdict: any, native: any }} */ (raw);
       const rendered = adapter.render(spec.verdict, parsed);
@@ -65,7 +193,7 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
       );
       if (rendered.enforced) {
         assert.ok(
-          rendered.exit_code !== 0 || rendered.throw_ !== undefined,
+          rendered.exit_code !== 0,
           `enforced deny carries no block signal: ${testCase.name} / ${scenario}`,
         );
         enforcedDenySeen = true;
@@ -117,5 +245,6 @@ export function runAdapterConformance({ adapter, fixtures, assert }) {
     decisionsSeen,
     mutationSeen,
     enforcedDenySeen,
+    coverageClassesChecked,
   };
 }

package/src/control-plane.mjs

@@ -26,12 +26,13 @@
  * 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},
- * and {@link MODELED_TOOLS} 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) is
- * backward-compatible and stays at v1; RENAMING or REMOVING a field, or
- * changing a decision/event vocabulary, is breaking and bumps the version.
+ * {@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. */
@@ -72,6 +73,63 @@ export const MODELED_TOOLS = Object.freeze([
   "WebFetch",
 ]);
 
+/** @type {Set<string>} membership set for {@link MODELED_TOOLS}, used to constrain alias targets. */
+const MODELED_TOOL_SET = new Set(MODELED_TOOLS);
+
+/**
+ * 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 = Object.freeze({
+  run_shell_command: "Bash",
+});
+
+/**
+ * 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) {
+  for (const canonical of Object.values(aliases)) {
+    if (!MODELED_TOOL_SET.has(canonical))
+      throw new Error(
+        `control-plane: tool alias target ${JSON.stringify(canonical)} is not a modeled tool`,
+      );
+  }
+}
+
+assertAliasTargetsModeled(TOOL_ALIASES);
+
+/**
+ * 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) {
+  if (typeof tool !== "string") return tool;
+  return /** @type {Record<string, string>} */ (TOOL_ALIASES)[tool] ?? tool;
+}
+
 /**
  * How a guardrail ATTACHES to an agent — the transport, kept separate from the
  * normalized decision so the judge/Verdict core stays transport-agnostic:
@@ -88,10 +146,104 @@ export const IntegrationMode = Object.freeze({
   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 = Object.freeze({
+  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 = Object.freeze(Object.values(CallClass));
+
+/**
+ * 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 = Object.freeze({
+  COVERED: "covered",
+  PARTIAL: "partial",
+  UNCOVERED: "uncovered",
+  UNKNOWN: "unknown",
+});
+
+/** @typedef {"covered"|"partial"|"uncovered"|"unknown"} CoverageStatusValue */
+/** @typedef {Record<string, CoverageStatusValue>} CoverageMap a per-{@link CallClass} coverage map (an adapter's `COVERAGE`) */
+
+/** @type {Set<string>} the valid {@link CoverageStatus} values, for membership checks. */
+const COVERAGE_STATUS_VALUES = new Set(Object.values(CoverageStatus));
+
+/**
+ * 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) {
+  if (!COVERAGE_STATUS_VALUES.has(status)) {
+    throw new Error(
+      `control-plane: invalid coverage status ${JSON.stringify(status)}`,
+    );
+  }
+  return status === CoverageStatus.COVERED || status === CoverageStatus.PARTIAL;
+}
+
+/**
+ * True when `status` is a recognized {@link CoverageStatus} value.
+ * @param {unknown} status
+ * @returns {boolean}
+ */
+export function isCoverageStatus(status) {
+  return COVERAGE_STATUS_VALUES.has(/** @type {string} */ (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.
+ * @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, native) {
+  if (typeof tool === "string" && /^mcp__?[^_]/.test(tool))
+    return CallClass.MCP;
+  const ctx = native ? native.mcp_context : undefined;
+  if (ctx !== null && typeof ctx === "object") return CallClass.MCP;
+  return CallClass.BUILTIN;
+}
+
 /**
  * @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]
@@ -110,23 +262,6 @@ export const IntegrationMode = Object.freeze({
  * @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 {{ message: string }} [throw_] a thrown-error block signal (plugin transports, e.g. opencode)
- * @property {ConfigFallback} [fallback] an out-of-band enforcement the adapter ALSO requires (external pin / config deny-wildcards)
- */
-
-/**
- * An enforcement the adapter cannot express in-band and so hands to the sandbox
- * to apply out-of-band — because the in-agent hook has a documented hole:
- *   - `external_pin`: the agent can re-enable/override its own hook, so the
- *     sandbox must pin it from OUTSIDE (read-only config mount / PATH-shadow).
- *   - `config_deny`: an in-agent throw doesn't reach every path (e.g. opencode
- *     MCP tools / subagents), so a config-level deny-by-name wildcard is ALSO
- *     required. `uncovered` names paths still not covered (a logged, known gap).
- * @typedef {object} ConfigFallback
- * @property {"external_pin"|"config_deny"} kind
- * @property {string} reason
- * @property {string[]} [deny_globs] tool-NAME globs to deny at config level (config_deny)
- * @property {string[]} [uncovered] paths this fallback still cannot reach (known gap)
  */
 
 /**
@@ -134,7 +269,7 @@ export const IntegrationMode = Object.freeze({
  * @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 tool name (null for prompt/session events)
+ * @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`)
@@ -145,7 +280,8 @@ export const IntegrationMode = Object.freeze({
  * A normalized guardrail decision.
  * @typedef {object} Verdict
  * @property {"allow"|"deny"|"ask"} decision
- * @property {Record<string, unknown>} [mutated_input] replacement tool input
+ * @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)
  */
@@ -158,6 +294,7 @@ export const IntegrationMode = Object.freeze({
  * @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
  */
@@ -214,12 +351,99 @@ export function normalizeVerdict(verdict) {
   const out = { decision };
   if (verdict.mutated_input !== undefined)
     out.mutated_input = verdict.mutated_input;
+  if (verdict.mutated_output !== undefined)
+    out.mutated_output = verdict.mutated_output;
   if (verdict.additional_context !== undefined)
     out.additional_context = verdict.additional_context;
   if (verdict.reason !== undefined) out.reason = verdict.reason;
   return out;
 }
 
+/**
+ * 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, sanitizeText) {
+  if (typeof sanitizeText !== "function") {
+    throw new TypeError(
+      "control-plane: sanitizeVerdict requires a sanitizeText(string) => string function",
+    );
+  }
+  const raw = asObject(verdict);
+  /** @type {(field: string, value: string) => string} */
+  const scrub = (field, value) => {
+    const out = sanitizeText(value);
+    if (typeof out !== "string") {
+      throw new TypeError(
+        `control-plane: sanitizeText returned a non-string for ${field} — a sanitizer must return the sanitized text`,
+      );
+    }
+    return out;
+  };
+  const { decision } = raw;
+  const valid =
+    decision === Decision.ALLOW ||
+    decision === Decision.DENY ||
+    decision === Decision.ASK;
+  /** @type {Verdict} */
+  const out = {
+    decision: /** @type {Verdict["decision"]} */ (
+      valid ? decision : Decision.ASK
+    ),
+  };
+  // mutated_input must be a plain object (it replaces a tool's input); a
+  // malformed value is dropped rather than coerced — an empty {} substitute
+  // would silently blank the tool call. mutated_output is unconstrained by the
+  // contract, so it is carried verbatim.
+  const mutatedInput = raw.mutated_input;
+  if (
+    mutatedInput !== undefined &&
+    mutatedInput !== null &&
+    typeof mutatedInput === "object" &&
+    !Array.isArray(mutatedInput)
+  )
+    out.mutated_input = /** @type {Record<string, unknown>} */ (mutatedInput);
+  if (raw.mutated_output !== undefined) out.mutated_output = raw.mutated_output;
+  if (typeof raw.additional_context === "string")
+    out.additional_context = scrub(
+      "additional_context",
+      raw.additional_context,
+    );
+  if (typeof raw.reason === "string") out.reason = scrub("reason", raw.reason);
+  if (!valid) {
+    // The rejected value is itself untrusted text, so it is scrubbed before
+    // being embedded in the clamp note.
+    const rejected = scrub("decision", JSON.stringify(decision) ?? "undefined");
+    const note = `[control-plane: invalid verdict decision ${rejected} clamped to "ask"]`;
+    out.reason = out.reason === undefined ? note : `${out.reason} ${note}`;
+  }
+  return normalizeVerdict(out);
+}
+
 /**
  * Return a shallow copy of `native` with the `consumed` keys removed — the
  * unmodelled remainder an adapter carries in `meta.passthrough` so an additive
@@ -273,19 +497,12 @@ export function asString(value, fallback) {
 }
 
 /**
- * Assemble a {@link NativeResponse}, omitting absent optional channels so a
- * pure exit-code transport carries no `stdout` key and vice versa.
- * @param {{ transport: string, exit_code: number, enforced: boolean, stdout?: unknown, throw_?: {message:string}, fallback?: ConfigFallback }} parts
+ * 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,
-  throw_,
-  fallback,
-}) {
+export function nativeResponse({ transport, exit_code, enforced, stdout }) {
   /** @type {NativeResponse} */
   const out = {
     transport: /** @type {NativeResponse["transport"]} */ (transport),
@@ -293,7 +510,5 @@ export function nativeResponse({
     enforced,
   };
   if (stdout !== undefined) out.stdout = stdout;
-  if (throw_ !== undefined) out.throw_ = throw_;
-  if (fallback !== undefined) out.fallback = fallback;
   return out;
 }

package/src/fixtures/amp.json

@@ -3,6 +3,7 @@
   "cases": [
     {
       "name": "delegate Bash, exit-code transport, all verdicts",
+      "call_class": "builtin",
       "native": {
         "tool": "Bash",
         "input": {
@@ -22,6 +23,7 @@
         "meta": {
           "agent": "amp",
           "native_event": "delegate",
+          "native_tool": "Bash",
           "integration_mode": "external_hook",
           "primary_gate_present": true,
           "passthrough": {},
@@ -97,6 +99,7 @@
         "meta": {
           "agent": "amp",
           "native_event": "delegate",
+          "native_tool": "Read",
           "integration_mode": "external_hook",
           "primary_gate_present": true,
           "passthrough": {

package/src/fixtures/claude.json

@@ -3,6 +3,7 @@
   "cases": [
     {
       "name": "pre_tool Bash, full meta, all verdicts",
+      "call_class": "builtin",
       "native": {
         "hook_event_name": "PreToolUse",
         "session_id": "s1",
@@ -25,6 +26,7 @@
         "meta": {
           "agent": "claude",
           "native_event": "PreToolUse",
+          "native_tool": "Bash",
           "integration_mode": "external_hook",
           "primary_gate_present": true,
           "passthrough": {},
@@ -134,6 +136,7 @@
         "meta": {
           "agent": "claude",
           "native_event": "PreToolUse",
+          "native_tool": "Read",
           "integration_mode": "external_hook",
           "primary_gate_present": true,
           "passthrough": {
@@ -183,6 +186,7 @@
         "meta": {
           "agent": "claude",
           "native_event": "PostToolUse",
+          "native_tool": "Bash",
           "integration_mode": "external_hook",
           "primary_gate_present": true,
           "passthrough": {}
@@ -206,6 +210,25 @@
             }
           }
         },
+        "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": {
+              "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "updatedToolOutput": "file1\n[REDACTED: secret]",
+                "additionalContext": "redacted 1 secret"
+              }
+            }
+          }
+        },
         "deny": {
           "verdict": {
             "decision": "deny",