agent-sanitizer 2.3.0 → 2.4.1

package/README.md

@@ -30,11 +30,9 @@ placeholders where hidden HTML was spliced out.
 
 ## Entry points
 
-Split into subpaths so the heavy HTML dependency stays opt-in. The **seam**
-column marks entry points that inject the agent-specific concern (a callback
-you supply) rather than baking it in; `—` means the function is a pure
-transform with no such hook, and `fs (direct)` means it does its own file I/O
-(Node's filesystem, not an agent harness) instead of taking a callback.
+Split into subpaths so the heavy HTML dependency stays opt-in. **Seam** names
+the callback you inject for the agent-specific concern; `—` is a pure transform,
+`fs (direct)` does its own file I/O instead of taking one.
 
 | #   | Import          | Purpose                                                                                                                                                    | Seam                        |
 | --- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
@@ -69,16 +67,12 @@ without notice.
 
 ### `FILTER_WARNING` codes (Layer 5)
 
-The Layer-5 `filterInjection` seam is deliberately thin: the injected filter may
-only ask for **verbatim span deletions** (`removeSpans`) and may only warn with a
-**closed enum code** (`warning`), never free text. Because the filter runs on
-attacker-influenced content and its `warning` would otherwise be concatenated
-straight into the model-facing context **without** re-passing Layer 1, a
-compromised or prompt-injected filter emitting arbitrary text would defeat the
-"a compromised filter can only remove bytes, never inject" contract. So the
-**library owns the message** for each code, and a filter returning any value
-outside this enum makes `sanitizeText` **throw** (fail loud). Branch on the code,
-like `found`:
+The Layer-5 `filterInjection` seam is deliberately thin: the filter may only
+request **verbatim span deletions** (`removeSpans`) and warn with a **closed
+enum code**, never free text. Its warning reaches the model-facing context
+without re-passing Layer 1, so a prompt-injected filter emitting arbitrary text
+would defeat the "can only remove bytes, never inject" contract. The library
+owns each message, and any value outside the enum makes `sanitizeText` **throw**:
 
 | `FILTER_WARNING` code | Meaning                                                                                 |
 | --------------------- | --------------------------------------------------------------------------------------- |
@@ -86,15 +80,59 @@ like `found`:
 | `filter-flagged`      | The filter flagged the output as a possible injection without deleting (content intact) |
 | `filter-error`        | The filter reported a non-fatal internal error while scanning (a fatal filter throws)   |
 
+## Using it with Claude Code
+
+Four hooks put Layers 1–4 on the tool stream: tool input, tool output, user
+prompts, and a session-start scan of the instruction files.
+
+```
+/plugin marketplace add AlexanderMattTurner/agent-sanitizer
+/plugin install agent-sanitizer@agent-sanitizer
+```
+
+The plugin needs no `node_modules` and no build step — just `python3` on PATH
+for Layer 4.
+
+To wire them yourself instead, one entry dispatches all four modes on `--hook=`:
+
+```jsonc
+// settings.json — one entry per event; PreToolUse/PostToolUse also take "matcher": "*"
+{
+  "type": "command",
+  "command": "node ./node_modules/agent-sanitizer/claude-hooks/plugin-hooks.mjs --hook=sanitize-output",
+}
+```
+
+| Event              | `--hook=`              |
+| ------------------ | ---------------------- |
+| `UserPromptSubmit` | `sanitize-user-prompt` |
+| `PreToolUse`       | `pretooluse-sanitize`  |
+| `PostToolUse`      | `sanitize-output`      |
+| `SessionStart`     | `scan-invisible-chars` |
+
+`require.resolve("agent-sanitizer/claude-hooks")` gives the path without
+hardcoding a layout. Importing the module rather than spawning it is a no-op.
+
+**Layer 4 needs the Python engine** — `pip install 'agent-sanitizer[secrets]'`,
+version-matched to the npm package. Without it `sanitize-output` fails closed:
+secret-shaped output is suppressed, not shown unvetted. Layers 1–3 still run.
+
+**Layer 5 (second-model injection filtering) is not included.** These hooks
+never supply the `/output` seam's `filterInjection` callback, so nothing here
+calls a model or leaves the machine.
+
+Hook internals are tuned by `_AGENT_SANITIZER_*` variables (redactor daemon
+path/socket/timeouts, sanitize budget, trace channel, Layer-2 reveal dir). The
+leading underscore marks them unstable — the supported surface is the `--hook=`
+CLI above.
+
 ## How this compares
 
-The "sanitize untrusted LLM input" space mostly splits into two camps: ML
-classifiers that score a prompt's _intent_ (Lakera Guard, Meta's Prompt
-Guard, Rebuff, NeMo Guardrails' input rails), and PII-focused redactors
-(Microsoft Presidio). Neither targets the byte-level hiding channel this
-library covers, and that gap is exactly where invisible-Unicode and
-hidden-HTML payloads live—content a semantic classifier never "sees" as
-suspicious because it renders as blank space or doesn't render at all.
+The space splits into ML classifiers that score a prompt's _intent_ (Lakera
+Guard, Meta's Prompt Guard, Rebuff, NeMo Guardrails) and PII redactors
+(Presidio). Neither targets the byte-level hiding channel — content a semantic
+classifier never "sees" as suspicious because it renders as blank space or
+doesn't render at all.
 
 |                               | `agent-sanitizer`                                                                                                        | Semantic guard/classifier (Lakera, Prompt Guard, Rebuff, NeMo rails)                                       | PII redactor (Presidio)                                      |
 | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
@@ -106,13 +144,10 @@ suspicious because it renders as blank space or doesn't render at all.
 | **Reversibility**             | `/rehydrate` re-anchors a model's edit from the sanitized view back onto real bytes, denying anything ambiguous          | N/A—classifiers only pass/block, they don't rewrite-and-reverse                                            | N/A                                                          |
 | **Non-JS support**            | Same verdicts via a bundled CLI/worker—Python client included, no reimplementation                                       | Usually a hosted API (language-agnostic) or Python-only SDK                                                | Python-first (spaCy-based)                                   |
 
-In practice these are complementary, not competing: run a semantic guard for
-intent, Presidio for PII you must not leak, and this library for the hidden
-channel both of those are blind to. If you already run a classifier and are
-still getting bitten by zero-width payloads or `display:none` instructions
-riding along in RAG context, that's the gap this library closes.
+These are complementary: a semantic guard for intent, Presidio for PII, and this
+for the hidden channel both are blind to.
 
-### Examples
+## Examples
 
 ```js
 import { stripInvisibleWithReport } from "agent-sanitizer/invisible";
@@ -162,25 +197,21 @@ await rehydrateRedacted("Edit", toolInput, {
 }); // { updatedInput, context } | { deny } | null — a deny never exposes a secret
 ```
 
-The credential-noun vocabulary — the words that make an identifier name a secret —
-is published as data so a consumer with its own matcher derives it from one list
-instead of forking one. Each noun carries the `uses` it is valid for: `env-name`
-for a matcher that inspects a variable NAME only, `field-value` for one that
-redacts whatever follows `noun = ` (a broad noun there mangles ordinary text, so
-`key` and `pat` are name-only).
+The credential-noun vocabulary — the words that make an identifier name a
+secret — is published as data so a consumer with its own matcher derives it
+rather than forking it. Each noun's `uses` marks where it is valid: `env-name`
+inspects a variable NAME only, `field-value` also redacts what follows
+`noun = ` (too broad for `key` and `pat`, which stay name-only).
 
 ```js
 import { createRequire } from "node:module";
-const vocabulary = createRequire(import.meta.url)(
-  "agent-sanitizer/credential-names",
-);
-vocabulary.nouns; // [{ parts: ["api", "key"], uses: ["env-name", "field-value"] }, …]
+createRequire(import.meta.url)("agent-sanitizer/credential-names").nouns;
+// [{ parts: ["api", "key"], uses: ["env-name", "field-value"] }, …]
 ```
 
 ```python
 from agent_sanitizer.secrets import credential_name_segments
-
-credential_name_segments()  # ("API_KEY", "APIKEY", "ACCESS_KEY", …) — rendered for a NAME matcher
+credential_name_segments()  # ("API_KEY", "APIKEY", "ACCESS_KEY", …)
 ```
 
 ## Limits
@@ -199,17 +230,14 @@ layer does and does not defend against.
 
 ## Non-JS pipelines (Python, etc.)
 
-The JS is the **single source of truth**—non-JS callers drive the same verdicts
-through the bundled CLI, so there’s
-no second implementation to drift. An `op` field selects the entry point
-(default `sanitize`); the self-contained ones—`sanitizeText`, `classifyPrompt`,
-`scanInstructionFiles`, `cleanFile`—are all bridged. Entry points with an
-injected JS callback have no wire form and stay JS-only. The bridged
-`sanitizeText` runs Layers 1–3 only (invisible/ANSI strip, HTML hidden-content
-splice, exfil detection): it never redacts secrets (Layer 4) or runs injection
-filtering (Layer 5), and the wire protocol's `sgrNote` (Python's
-`TextResult.sgr_note`) is always `false`, since the bridge never wires
-`sgrCarveOut`.
+The JS is the **single source of truth** — non-JS callers drive the same
+verdicts through the bundled CLI, so no second implementation can drift. An `op`
+field selects the entry point (default `sanitize`); the self-contained ones —
+`sanitizeText`, `classifyPrompt`, `scanInstructionFiles`, `cleanFile` — are
+bridged, while entry points taking a JS callback have no wire form. Bridged
+`sanitizeText` runs Layers 1–3 only: no secret redaction (Layer 4), no injection
+filtering (Layer 5), and `sgrNote` is always `false` since the bridge never
+wires `sgrCarveOut`.
 
 ```sh
 echo '{"text":"a​b"}' | npx sanitize-cli           # default op: sanitize
@@ -217,16 +245,13 @@ echo '{"op":"classifyPrompt","text":"…"}' | npx sanitize-cli
 sanitize-cli --worker                              # newline-delimited, one response/line
 ```
 
-The [`python/`](./python) client wraps every bridged op (`sanitize`,
-`sanitize_text`, `classify_prompt`, `scan_instruction_files`, `clean_file`). The
-wheel ships a self-contained, single-file build of the CLI (`src/` and its npm
-dependencies bundled into one `.mjs` at release time), so a `pip install` plus
-Node.js (>=22) on `PATH` works with no separate JavaScript checkout to clone.
-`AGENT_SANITIZER_CLI` is only an override escape hatch (e.g. to point at a
-custom/dev build)—a normal install never needs to set it. The first
-`html=True` call starts a shared worker, so the ~200 ms HTML module-load is
-paid **once per process**; Layer-1 calls stay one-shot. `persist=True/False`
-forces the mode and `shutdown_worker()` (also an `atexit` hook) stops it.
+The [`python/`](./python) client wraps every bridged op. The wheel ships a
+single-file build of the CLI, so `pip install` plus Node.js (>=22) on `PATH`
+needs no JavaScript checkout; `AGENT_SANITIZER_CLI` is an override escape hatch
+a normal install never sets. The first `html=True` call starts a shared worker,
+paying the ~200 ms HTML module-load **once per process**; Layer-1 calls stay
+one-shot. `persist=True/False` forces the mode; `shutdown_worker()` (also an
+`atexit` hook) stops it.
 
 ```python
 from agent_sanitizer import sanitize, Sanitizer

package/claude-hooks/config/credential-var-names.json

@@ -0,0 +1,23 @@
+{
+  "comment": "The credential-shaped ENV-VAR NAME vocabulary the hook-side pre-gate builds its regexes from (looksLikeCredentialVar in lib/env-config.mjs). `segments`: a var whose trailing underscore-delimited segment is one of these is treated as credential-bearing (matched as `(?:^|_)(?:<segment>)$`, case-insensitive). `excludeSuffixes` / `excludeNames`: names that end like a credential but hold a non-secret (an identifier, a public key, the ssh-agent socket path) and must NOT be redacted out of tool output. Every token is restricted to A-Z and _ so it carries no regex metacharacter; the consumer enforces that and fails closed on a violation, an empty list, or a missing field.",
+  "segments": [
+    "TOKEN",
+    "SECRET",
+    "SECRETS",
+    "PASSWORD",
+    "PASSWD",
+    "PASSPHRASE",
+    "APIKEY",
+    "API_KEY",
+    "ACCESS_KEY",
+    "SECRET_KEY",
+    "PRIVATE_KEY",
+    "AUTH_TOKEN",
+    "PAT",
+    "CREDENTIAL",
+    "CREDENTIALS",
+    "KEY"
+  ],
+  "excludeSuffixes": ["_KEY_ID", "_PUBLIC_KEY"],
+  "excludeNames": ["SSH_AUTH_SOCK"]
+}

package/claude-hooks/config/inference-key-vars.json

@@ -0,0 +1,17 @@
+{
+  "description": "Inference-provider API-key env vars whose VALUES the redactor masks by exact match, plus the placeholder floor below which a configured value is treated as a doc stub rather than a real key. Mirrors agent_sanitizer.secrets.config.DEFAULT_MIN_SECRET_LEN; the hooks send these names' current values to the redactor daemon per request (see lib/redactor-client.mjs).",
+  "min_secret_len": 16,
+  "vars": [
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN",
+    "OPENAI_API_KEY",
+    "OPENROUTER_API_KEY",
+    "GEMINI_API_KEY",
+    "GOOGLE_API_KEY",
+    "MISTRAL_API_KEY",
+    "GROQ_API_KEY",
+    "DEEPSEEK_API_KEY",
+    "XAI_API_KEY",
+    "VENICE_INFERENCE_KEY"
+  ]
+}

package/claude-hooks/config/scrubbed-env-vars.json

@@ -0,0 +1,15 @@
+{
+  "description": "The GUARANTEED FLOOR of credential-bearing environment variables whose values must never reach the model through tool output. On top of this list the redactor self-populates with any credential-shaped var present in the environment (looksLikeCredentialVar in lib/env-config.mjs), so a newly-forwarded token is redacted without editing this file — this list only pins the names that must always be covered regardless of shape. The Layer-4 secret redactor treats each as an env-bound secret (env_secrets).",
+  "vars": [
+    "CLAUDE_CODE_OAUTH_TOKEN",
+    "GH_TOKEN",
+    "GITHUB_TOKEN",
+    "AWS_ACCESS_KEY_ID",
+    "AWS_SECRET_ACCESS_KEY",
+    "AWS_SESSION_TOKEN",
+    "NPM_TOKEN",
+    "PYPI_TOKEN",
+    "DOCKER_PASSWORD",
+    "DOCKER_AUTH_CONFIG"
+  ]
+}

package/claude-hooks/lib/authored-content.mjs

@@ -0,0 +1,166 @@
+/**
+ * Sanitize content the *model authors* into tool calls — file writes, edits,
+ * notebook cells, and command bodies (commit messages, PR/issue bodies passed on
+ * the command line). Two complementary protections:
+ *
+ *   1. Covert channel (steganography). Format chars (Cf — including the U+E00xx
+ *      TAG block used for ASCII smuggling and zero-width joiners) and variation
+ *      selectors can encode a hidden message that another AI reading the
+ *      committed file / PR / commit later decodes, while staying invisible to a
+ *      human reviewer. Stripped when payload-capable (see isPayloadCapable):
+ *      gated on volume because incidental joiners / emoji selectors are benign
+ *      and authored content is *persisted*, so over-stripping is costly.
+ *
+ *   2. Terminal-display rewriting. ANSI/terminal control sequences (CSI/OSC)
+ *      authored into a command — echoed and executed live — or into file
+ *      content (a latent bomb when the file is later `cat`'d) can clear the
+ *      screen, reposition the cursor, or overwrite what the user sees, hiding
+ *      the real command behind spoofed output. Stripped *unconditionally*: a
+ *      single sequence already does harm, so there is no volume threshold. The
+ *      false-positive rate is low because real source represents escapes as
+ *      *literals* (`\033`, `\x1b`, `\e`) — a *raw* ESC byte in authored content
+ *      is anomalous.
+ *
+ * Distinct from sanitize-output.mjs, which scrubs tool *responses* flowing
+ * toward the model (data the model reads). This scrubs what the model emits
+ * (data the model writes out). In pretooluse-sanitize.mjs it runs *after*
+ * confusable normalization, so on the shared `command` field it sees the
+ * already-normalized text and the two protections compose deterministically.
+ *
+ * Opt-outs are granular so dropping one protection doesn't drop the other:
+ * AGENT_SANITIZER_INVISIBLE_DISABLED=1 keeps invisible chars (legitimate i18n
+ * text relying on ZWNJ/ZWJ joiners) while terminal-control stripping stays on;
+ * AGENT_SANITIZER_TERMINAL_DISABLED=1 keeps raw escape sequences (fixtures that
+ * must contain them) while stego stripping stays on; and
+ * AGENT_SANITIZER_OUTPUT_DISABLED=1 disables both.
+ */
+import { lazyImport } from "./hook-io.mjs";
+
+// Bound via lazyImport (see its doc for the fail-OPEN hazard of a bare static
+// npm import — here the load crash would fire inside pretooluse-sanitize.mjs's
+// static import of this module, before its fail-closed catch runs). A failed
+// load leaves these bindings undefined, so sanitizeField's calls throw into
+// the fail-closed catch (ask) instead.
+const { stripAnsiFully } = /** @type {typeof import("agent-sanitizer")} */ (
+  await lazyImport("agent-sanitizer")
+);
+const { STRIP, LONG_RUN_RE, SCATTERED_THRESHOLD, stripInvisible } =
+  /** @type {typeof import("agent-sanitizer/invisible")} */ (
+    await lazyImport("agent-sanitizer/invisible")
+  );
+
+// Content fields the model authors, per tool. Paths and confusables are the
+// confusable layer's domain; here we target the free-text fields that carry
+// model-authored prose / code / data out into persisted or displayed artifacts.
+// A "key[].sub" entry addresses `sub` on every element of the array at `key`
+// (MultiEdit batches its writes as edits[].new_string), so the nested authored
+// content is sanitized too — not just the top-level fields.
+/** @type {Record<string, string[]>} */
+const FIELDS = {
+  Write: ["content"],
+  Edit: ["new_string"],
+  MultiEdit: ["edits[].new_string"],
+  NotebookEdit: ["new_source"],
+  Bash: ["command"],
+};
+
+// Payload-capable: a long contiguous run, or enough scattered invisibles to
+// carry a message. Mirrors sanitize-user-prompt so the model→world and
+// user→model surfaces share one definition of "stego payload".
+/** @param {string} text */
+function isPayloadCapable(text) {
+  LONG_RUN_RE.lastIndex = 0;
+  if (LONG_RUN_RE.test(text)) return true;
+  return (text.match(STRIP)?.length ?? 0) >= SCATTERED_THRESHOLD;
+}
+
+// Returns the cleaned value plus the human-readable actions applied, or null if
+// the field is already clean. Each protection has its own opt-out (see the
+// header) so a deployment can keep one while dropping the other.
+/** @param {string} value */
+function sanitizeField(value) {
+  const actions = [];
+  let cleaned = value;
+
+  // Strip terminal-control sequences first, so the invisible scan below runs on
+  // the same de-ANSI'd view sanitize-output uses (both go through the package's
+  // stripAnsiFully, which strips to a fixed point — so a sequence reconstituted
+  // when an inner one is removed is itself stripped on the next pass). Compare
+  // before/after rather than pre-testing for ESC: a lone control byte that forms
+  // no real sequence does not rewrite the display and is left alone, so we only
+  // report a genuine strip.
+  if (process.env.AGENT_SANITIZER_TERMINAL_DISABLED !== "1") {
+    const deAnsi = stripAnsiFully(cleaned);
+    if (deAnsi !== cleaned) {
+      cleaned = deAnsi;
+      actions.push("terminal-control sequences");
+    }
+  }
+
+  if (
+    process.env.AGENT_SANITIZER_INVISIBLE_DISABLED !== "1" &&
+    isPayloadCapable(cleaned)
+  ) {
+    cleaned = stripInvisible(cleaned);
+    actions.push("invisible characters");
+  }
+
+  return actions.length > 0 ? { cleaned, actions } : null;
+}
+
+/** @param {string[]} changed */
+export function authoredContext(changed) {
+  return `Sanitized model-authored content in: ${changed.join("; ")}. This removes a covert channel to other AIs and prevents authored content from rewriting the user's terminal. Opt out granularly with AGENT_SANITIZER_INVISIBLE_DISABLED=1 (i18n joiners) or AGENT_SANITIZER_TERMINAL_DISABLED=1 (raw-escape fixtures), or fully with AGENT_SANITIZER_OUTPUT_DISABLED=1.`;
+}
+
+/**
+ * Strip authored stego / terminal-control sequences from the model-authored
+ * fields of a tool call. Returns the updated input plus a per-field description
+ * of what was stripped, or null when nothing changed. Throws on internal error
+ * (caller fails closed).
+ * @param {string} tool
+ * @param {any} toolInput
+ * @returns {{ updatedInput: any, changed: string[] } | null}
+ */
+export function sanitizeAuthoredContent(tool, toolInput) {
+  const keys = FIELDS[tool];
+  if (!keys || toolInput === null || toolInput === undefined) return null;
+
+  const changed = [];
+  // Null-prototype copy: toolInput is untrusted parsed JSON where a `__proto__`
+  // key is own-enumerable, and the computed writes below would otherwise route
+  // it through the prototype chain. Object.assign onto Object.create(null) copies
+  // every own field (including a literal `__proto__`) as a plain own property.
+  const updatedInput = Object.assign(Object.create(null), toolInput);
+  for (const k of keys) {
+    // Named groups satisfy prefer-named-capture-group; reading the numeric
+    // indices keeps the values typed as string (match.groups is optional).
+    const nested = k.match(/^(?<arr>\w+)\[\]\.(?<sub>\w+)$/);
+    if (nested) {
+      const arrKey = nested[1];
+      const subKey = nested[2];
+      const arr = toolInput[arrKey];
+      if (!Array.isArray(arr)) continue;
+      let nestedChanged = false;
+      const newArr = arr.map((el) => {
+        const val = el?.[subKey];
+        if (typeof val !== "string") return el;
+        const result = sanitizeField(val);
+        if (!result) return el;
+        nestedChanged = true;
+        changed.push(`${arrKey}[].${subKey} (${result.actions.join(", ")})`);
+        return { ...el, [subKey]: result.cleaned };
+      });
+      if (nestedChanged) updatedInput[arrKey] = newArr;
+      continue;
+    }
+    if (typeof toolInput[k] !== "string") continue;
+    const result = sanitizeField(toolInput[k]);
+    if (!result) continue;
+    updatedInput[k] = result.cleaned;
+    changed.push(`${k} (${result.actions.join(", ")})`);
+  }
+
+  if (changed.length === 0) return null;
+  return { updatedInput, changed };
+}

package/claude-hooks/lib/control-plane.mjs

@@ -0,0 +1,138 @@
+/**
+ * Bridge to the agent-agnostic control plane (agent-control-plane-core).
+ * Guardrail judges consume the normalized ToolCallEvent and return a Verdict;
+ * a per-agent adapter parses the native payload and renders the native
+ * response, so the same judge runs unchanged under any agent the package has
+ * an adapter for. This module owns the package load, the one Claude-specific
+ * transport rule (nativeStdout), and the shared judge-CLI transport
+ * (runJudgeCli).
+ */
+import { errMessage, lazyImport, readStdinJson } from "./hook-io.mjs";
+
+// Loaded via a *caught* dynamic import — never a bare static `import … from`.
+// A static npm import resolves before any try/catch, so a missing node_modules
+// would crash every importing hook at load; the harness treats that as a
+// non-blocking error and the tool call sails through UNGUARDED — fail OPEN. A
+// failed load leaves the bindings undefined, so controlPlane() throws into the
+// calling hook's catch and each hook takes its declared failure posture
+// (deny/ask for gates, suppression for the output sanitizer) instead.
+/** @type {typeof import("agent-control-plane-core/claude").claudeAdapter | undefined} */
+let claudeAdapter;
+/** @type {typeof import("agent-control-plane-core").Decision | undefined} */
+let Decision;
+/** @type {typeof import("agent-control-plane-core").EventKind | undefined} */
+let EventKind;
+
+/* c8 ignore start -- module-load boundary: the real import resolves in every
+   in-process test and spawned CLI run, and a missing node_modules can't be
+   simulated in-process, so this glue's failure arm is unobservable here. The
+   observable behaviour is controlPlane()'s throw, unit-tested directly. */
+// Stryker disable all
+{
+  const { claudeAdapter: adapter } =
+    /** @type {Partial<typeof import("agent-control-plane-core/claude")>} */ (
+      await lazyImport("agent-control-plane-core/claude")
+    );
+  const { Decision: decision, EventKind: eventKind } =
+    /** @type {Partial<typeof import("agent-control-plane-core")>} */ (
+      await lazyImport("agent-control-plane-core")
+    );
+  claudeAdapter = adapter;
+  Decision = decision;
+  EventKind = eventKind;
+}
+// Stryker restore all
+/* c8 ignore stop */
+
+/**
+ * The loaded control-plane bindings, narrowed to non-undefined — or a throw
+ * the calling hook's catch converts into its own failure posture. Overrides
+ * exist so tests can drive the unavailable arm in-process.
+ * @param {{ claudeAdapter?: unknown, Decision?: unknown, EventKind?: unknown }} [overrides]
+ * @returns {{
+ *   claudeAdapter: typeof import("agent-control-plane-core/claude").claudeAdapter,
+ *   Decision: typeof import("agent-control-plane-core").Decision,
+ *   EventKind: typeof import("agent-control-plane-core").EventKind,
+ * }}
+ */
+export function controlPlane(overrides = {}) {
+  const bindings = { claudeAdapter, Decision, EventKind, ...overrides };
+  if (!bindings.claudeAdapter || !bindings.Decision || !bindings.EventKind)
+    throw new Error("agent-control-plane-core is unavailable");
+  return /** @type {ReturnType<typeof controlPlane>} */ (bindings);
+}
+
+/**
+ * Serialize a rendered NativeResponse for Claude Code's stdout, or null when
+ * the body carries nothing a silent exit 0 doesn't already say. The adapter's
+ * exit_code is deliberately NOT honored by the hooks: Claude Code parses hook
+ * stdout as JSON only on exit 0 — under the adapter's exit-2 enforced-deny
+ * channel it discards stdout and reads the (empty) stderr instead, so the
+ * deny would land without its reason. For this host the stdout JSON's
+ * permissionDecision IS the enforcement channel, and hooks always exit 0.
+ * @param {{ stdout?: unknown }} response a NativeResponse from adapter.render
+ * @returns {string | null}
+ */
+export function nativeStdout(response) {
+  const stdout = /** @type {Record<string, unknown> | undefined} */ (
+    response.stdout
+  );
+  if (!stdout) return null;
+  // Directives live either inside hookSpecificOutput (permissionDecision,
+  // updatedInput, additionalContext) or at the top level (the non-gating
+  // decision:"block"/reason the adapter uses for post-tool and unclassified
+  // events). A body that is only the echoed hookEventName says nothing.
+  const body = /** @type {Record<string, unknown> | undefined} */ (
+    stdout.hookSpecificOutput
+  );
+  const meaningful =
+    Object.keys(stdout).some((key) => key !== "hookSpecificOutput") ||
+    (body !== undefined &&
+      Object.keys(body).some((key) => key !== "hookEventName"));
+  return meaningful ? JSON.stringify(stdout) : null;
+}
+
+/**
+ * Run a judge hook's CLI transport: read the native payload from stdin, parse
+ * it through the claude adapter, render the judge's verdict, and write the
+ * native response. This encodes the two transport invariants every gate hook
+ * shares: stdin is read BEFORE the control-plane bindings are touched, so a
+ * package-load failure still lands in `onError` with the parsed input in hand;
+ * and the process always exits 0 with the verdict in the stdout JSON (see
+ * nativeStdout — exit-code enforcement is deliberately not used). Any throw —
+ * unparsable stdin, missing package, a judge error — is reported on stderr and
+ * routed to `onError(err, input)` (`input` undefined when stdin never parsed),
+ * where the hook applies its declared fail posture.
+ * @param {string} hookName  prefix for the stderr diagnostic
+ * @param {(event: import("agent-control-plane-core").ToolCallEvent) =>
+ *   import("agent-control-plane-core").Verdict |
+ *   Promise<import("agent-control-plane-core").Verdict>} judge
+ * @param {object} opts
+ * @param {(err: unknown, input: unknown) => void} opts.onError  fail-posture emitter
+ * @param {(input: unknown) => unknown} [opts.transformInput]  raw-payload normalization before adapter.parse
+ * @param {() => Promise<unknown>} [opts.readInput]  injectable stdin reader
+ * @param {(chunk: string) => void} [opts.write]  injectable stdout writer
+ * @returns {Promise<void>}
+ */
+export async function runJudgeCli(
+  hookName,
+  judge,
+  {
+    onError,
+    transformInput = (raw) => raw,
+    readInput = readStdinJson,
+    write = (chunk) => process.stdout.write(chunk),
+  },
+) {
+  let input;
+  try {
+    input = await readInput();
+    const { claudeAdapter: adapter } = controlPlane();
+    const event = adapter.parse(transformInput(input));
+    const out = nativeStdout(adapter.render(await judge(event), event));
+    if (out !== null) write(out);
+  } catch (err) {
+    process.stderr.write(`${hookName} hook error: ${errMessage(err)}\n`);
+    onError(err, input);
+  }
+}