agent-sanitizer 2.67.1 → 2.68.0

package/claude-hooks/lib/secret-annotate.mjs

@@ -17,70 +17,25 @@ import charset from "../../python/agent_sanitizer/data/invisible-charset.json" w
 // Invisible characters an attacker can splice between a value's characters to
 // break an exact-substring pre-gate while the daemon's redactor still matches
 // across them. Built from the SAME pinned charset Layer 1 strips and the daemon
-// tolerates (`invisible_run_pattern` in agent_sanitizer.secrets.invisible
-// builds the same shape from the same set), not a hand-curated subset: a subset
-// pre-gate silently under-matches whenever this gate runs on text Layer 1 has
-// not already stripped (the module is exported and callable on its own), and a
-// value spliced with a code point in the gap then never reaches the daemon at
-// all. A run of zero-or-more is allowed at each interior gap, so the plain
-// value still matches (a superset of `includes`). The required literals between
-// every gap are what bound the match — a `*` gap is never adjacent to another
-// gap, so there is no ambiguity to backtrack over and no ReDoS. (The class size
-// is irrelevant to that: a character class matches in O(1) whether it holds one
-// member or all 435.) That argument holds only while no literal is itself a
-// member of the class, so {@link envValueRegex} drops the value's own invisible
-// code points before it splices: `a<ZWSP>a` would otherwise build
-// `a[…]*<ZWSP>[…]*a`, whose two stars share the literal and backtrack
-// quadratically over a long run of ZWSP.
-const ENV_INVIS_CODEPOINTS = [
-  ...new Set([...charset.cf_codepoints, ...charset.extra_codepoints]),
-].sort((a, b) => a - b);
-const ENV_INVIS_SET = new Set(ENV_INVIS_CODEPOINTS);
-const ENV_INVIS_RUN =
+// tolerates (`_env_value_spans` in agent_sanitizer.secrets.engine), not
+// a hand-curated subset: a subset pre-gate silently under-matches whenever this
+// gate runs on text Layer 1 has not already stripped, and a value spliced with a
+// code point in the gap then never reaches the daemon at all.
+const ENV_INVIS_RE = new RegExp(
   "[" +
-  ENV_INVIS_CODEPOINTS.map((cp) => `\\u{${cp.toString(16)}}`).join("") +
-  "]*";
-
-/** @param {string} ch */
-const escapeLiteral = (ch) => ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    [...new Set([...charset.cf_codepoints, ...charset.extra_codepoints])]
+      .map((cp) => `\\u{${cp.toString(16)}}`)
+      .join("") +
+    "]",
+  "gu",
+);
 
 /**
- * Regex matching `value` tolerating invisible chars spliced between its
- * characters (mirrors the engine's env-value regex). Code-point split so
- * an astral character is escaped whole, not as two surrogate halves — and the
- * `u` flag, which the astral `\u{…}` class members in {@link ENV_INVIS_RUN}
- * require.
- * Memoized per distinct value: {@link ENV_INVIS_RUN} renders ~435 code points
- * as ~4 KB of source and is joined at EVERY interior gap, so a 20-char secret
- * compiles a ~75 KB pattern — and `hasEnvBoundSecret` builds one per configured
- * var on every PostToolUse output. Env values are stable for the process's
- * lifetime, so the cache is bounded by the number of distinct values. Sharing an
- * instance is safe because the regex carries no `g`/`y` flag, hence no
- * `lastIndex` state to leak between calls.
- * @param {string} value
- * @returns {RegExp}
+ * `s` with every charset invisible removed.
+ * @param {string} s
+ * @returns {string}
  */
-export function envValueRegex(value) {
-  let re = ENV_VALUE_REGEX_CACHE.get(value);
-  if (re === undefined) {
-    const visible = [...value].filter(
-      (ch) => !ENV_INVIS_SET.has(/** @type {number} */ (ch.codePointAt(0))),
-    );
-    // A value made only of invisibles has no literal to anchor a gap on: match
-    // it exactly rather than build a pattern that is nothing but gaps.
-    re = new RegExp(
-      visible.length > 0
-        ? visible.map(escapeLiteral).join(ENV_INVIS_RUN)
-        : [...value].map(escapeLiteral).join(""),
-      "u",
-    );
-    ENV_VALUE_REGEX_CACHE.set(value, re);
-  }
-  return re;
-}
-
-/** value → compiled matcher; see {@link envValueRegex}. */
-const ENV_VALUE_REGEX_CACHE = new Map();
+const stripInvisibles = (s) => s.replace(ENV_INVIS_RE, "");
 
 /**
  * True when tool output contains the literal value of a configured env-bound
@@ -88,19 +43,34 @@ const ENV_VALUE_REGEX_CACHE = new Map();
  * credential, so the pre-gate must also fire on the value itself — otherwise
  * the engine's env-bound redaction never runs. Invisible-tolerant so a
  * value with spliced Cf chars (which the daemon still redacts) trips it too.
+ *
+ * Both sides are stripped and compared as substrings, which is exactly
+ * equivalent: the value's visible characters appear contiguously in the
+ * stripped text iff they appear in the original separated only by invisibles.
+ * It is linear and independent of the value's length — a regex with an
+ * invisible class at every gap grows ~4 KB per character, and a long secret (a
+ * PEM key) overflows V8's regex size limit and throws on every output.
+ *
+ * Callers pass post-Layer-1 text: terminal escapes are already gone, so a value
+ * split by one is contiguous here. Raw text spliced with an escape is not
+ * matched.
  * @param {string} text
  * @param {NodeJS.ProcessEnv} [env]
  * @returns {boolean}
  */
 export function hasEnvBoundSecret(text, env = process.env) {
   const minLen = minEnvSecretLen();
+  /** @type {string | undefined} */
+  let strippedText;
   return envBoundSecretVars(env).some((name) => {
     const value = env[name];
-    // Code-point length to match envValueRegex's code-point split — an astral
-    // char counts once, not as two UTF-16 units, so minLen means the same thing
-    // on both sides of the gate.
-    return (
-      value && [...value].length >= minLen && envValueRegex(value).test(text)
-    );
+    // Code-point length, so an astral char counts once, not as two UTF-16 units.
+    if (!value || [...value].length < minLen) return false;
+    const needle = stripInvisibles(value);
+    // A value made only of invisibles has no visible character to anchor on:
+    // match it exactly rather than as the empty string, which matches anything.
+    if (needle === "") return text.includes(value);
+    strippedText ??= stripInvisibles(text);
+    return strippedText.includes(needle);
   });
 }

package/claude-hooks/plugin-hooks.mjs

@@ -26,7 +26,6 @@ import {
 } from "./lib/hook-io.mjs";
 import {
   registerFaultPolicy,
-  KNOB_DECIDES,
   hookFaultOutcome,
   writeFaultOutcome,
 } from "./lib/hook-fault.mjs";
@@ -55,7 +54,6 @@ const unknownMode = (/** @type {{ message: string }} */ ctx) => ({
 registerFaultPolicy(HOOK_NAME, {
   event: null,
   guarded: "hook payload",
-  alwaysClosed: KNOB_DECIDES,
   open: unknownMode,
   closed: unknownMode,
 });
@@ -90,7 +88,7 @@ const LAZY_LOADERS = {
  * as a non-blocking hook error and shows the raw tool output. That is a
  * fail-OPEN on the very hook that withholds secrets. Registering what resolves
  * and leaving the rest absent hands the gap to each hook's own lazyImport
- * guard, whose posture is to block.
+ * guard, which answers it loudly under the operator's fault posture.
  * @returns {Promise<void>}
  */
 async function registerAvailableModules() {

package/claude-hooks/pretooluse-sanitize.mjs

@@ -44,7 +44,6 @@ import {
 } from "./lib/hook-io.mjs";
 import {
   registerFaultPolicy,
-  KNOB_DECIDES,
   hookFaultOutcome,
   defaultOpen,
 } from "./lib/hook-fault.mjs";
@@ -845,7 +844,6 @@ export function hookFailureFields(parsedOk, err, opts = {}) {
 registerFaultPolicy(HOOK_NAME, {
   event: HookEvent.PRE_TOOL_USE,
   guarded: "tool input",
-  alwaysClosed: KNOB_DECIDES,
   open: (ctx) => {
     // Non-carve-out faults take the SHARED open rendering, not a copy of it —
     // hook-fault.mjs owns that body, and a restated one would silently drift.

package/claude-hooks/sanitize-output.mjs

@@ -50,11 +50,7 @@ import { registerFaultPolicy, hookFaultOutcome } from "./lib/hook-fault.mjs";
 import { controlPlane, runJudgeCli } from "./lib/control-plane.mjs";
 import { hookTrace, TraceEvent } from "./lib/trace.mjs";
 import { hasEnvBoundSecret } from "./lib/secret-annotate.mjs";
-import {
-  digestFlaggingEnabled,
-  secretsEnabled,
-  SECRETS_ENABLED_ENV,
-} from "./lib/env-config.mjs";
+import { digestFlaggingEnabled, secretsEnabled } from "./lib/env-config.mjs";
 import {
   persistReveal,
   persistSpan,
@@ -120,16 +116,17 @@ const HOOK_NAME = "sanitize-output";
 // reaches the model-facing context. Exported so tests assert it by reference.
 export const REVEAL_WITHHELD_WARNING = withheldWarning("reveal sidecar");
 
-// Total wall-clock budget for one hook invocation's blocking daemon calls — the
-// Layer-4 redactor — SHARED across every string leaf of the tool output. Each
-// call is handed the budget remaining at that moment; once it is spent, a further
-// secret-shaped leaf fails CLOSED (the redactor throws → the output is
-// suppressed). The per-call timeouts already bound each call, but not their SUM:
-// a structured output with many secret-shaped leaves could otherwise pile up past
-// the PostToolUse hook kill — a killed hook is non-blocking, so the RAW output
-// would be shown (fail OPEN). The default sits comfortably above one legitimately
-// slow leaf (a cold redactor respawn + a full scan) yet far under the hook
-// timeout; env-tunable so tests can drive the exhausted-budget path fast.
+/**
+ * Total wall-clock budget for one hook invocation's blocking Layer-4 redactor
+ * calls, SHARED across every string leaf of the tool output. Each call gets the
+ * budget remaining at that moment; once it is spent, a further secret-shaped
+ * leaf throws, answered under the operator's fault posture. The per-call
+ * timeouts bound each call but not their SUM, and a structured output with many
+ * secret-shaped leaves could otherwise run past the PostToolUse hook kill,
+ * which shows the RAW output with no warning. The default sits above one slow
+ * leaf (a cold redactor respawn plus a full scan) and far under the hook
+ * timeout; env-tunable so tests can drive the exhausted-budget path fast.
+ */
 const SANITIZE_BUDGET_MS = readKnob("_AGENT_SANITIZER_SANITIZE_BUDGET_MS");
 
 // Web-ingress tools always get the Layer 2 HTML rewrite; local tools — Read,
@@ -172,11 +169,13 @@ function isUntrustedIngress(toolName) {
 
 /**
  * Redact secrets via the long-lived redactor daemon (lib/redactor-client.mjs).
- * Returns `{text, found}` or null when nothing was redacted; throws (fail closed)
- * when secret-shaped text cannot be vetted, which the caller turns into
- * suppression. The cheap pre-gate runs first so plain output never touches the
- * daemon. A transient daemon failure fails only THIS call — no session-wide
- * sentinel — and the client respawns a dead daemon on the next call.
+ * Returns `{text, found}` or null when nothing was redacted; throws when
+ * secret-shaped text cannot be vetted, which the CLI answers under the
+ * operator's fault posture. The cheap pre-gate runs first so plain output never
+ * touches the daemon. `text` is post-Layer-1, so it carries no terminal escape
+ * and the pre-gate needs no escape-stripped view. A transient daemon failure
+ * fails only THIS call — no session-wide sentinel — and the client respawns a
+ * dead daemon on the next call.
  * @param {string} text
  * @param {boolean} webIngress
  * @param {{remainingMs: () => number}} [deadline] shared wall-clock budget
@@ -288,9 +287,9 @@ export async function sanitizeText(
     // Layer 4 — OPT-IN (`secretsOn`): with the knob unset the seam gets no
     // redact callback at all, so plain output never spawns the daemon and no
     // placeholder ever enters the model's view. When it runs, the seam rethrows
-    // a redactor throw wrapped, and this hook's fault policy suppresses the
-    // output under either posture (alwaysClosed). Surface the failure to the
-    // operator's terminal here first: the suppression note rides in what only
+    // a redactor throw wrapped, and this hook's fault policy answers it under
+    // the operator's AGENT_SANITIZER_FAIL_OPEN posture. Surface the failure to
+    // the operator's terminal here first: the fault note rides in what only
     // the model sees, so a degraded redactor would otherwise be invisible to
     // the human.
     redact: !secretsOn
@@ -579,7 +578,7 @@ function failClosedParts(
  * fail-OPEN by default — a warning context and NO `updatedToolOutput`, leaving
  * the original tool output in the model's view — or the fail-closed
  * suppression of {@link emitFailClosed} when the caller set
- * AGENT_SANITIZER_FAIL_OPEN=0, or opted into Layer 4 (see the policy below).
+ * AGENT_SANITIZER_FAIL_OPEN=0.
  *
  * This is the hook where the two postures diverge the most, so state the open
  * one plainly: several of these layers throw on inputs an attacker composes (a
@@ -625,29 +624,17 @@ function suppressionMessage(cause) {
   return `[SANITIZATION FAILED — original output suppressed for safety. Hook error: ${cause}]`;
 }
 
-/** Why an open knob still suppressed: the secret layer's own guarantee. */
-const SECRETS_PIN_NOTE =
-  ` Secret redaction is on (${SECRETS_ENABLED_ENV}=1), so output it could ` +
-  "not vet is withheld under either AGENT_SANITIZER_FAIL_OPEN posture.";
-
 // This hook's entry in the one posture table (lib/hook-fault.mjs). OPEN is the
 // shared default (a warning context, the original output left in the model's
 // view); CLOSED replaces every string leaf of the output with the placeholder.
-// With Layer 4 opted in, a fault here means the output was never vetted for
-// secrets — a dead daemon, a spent budget, a walk that overflowed before the
-// redactor ran — so this pin is what keeps the open default from handing an
-// unredacted credential to the model.
+// Layer 4 follows the same knob: a redactor that cannot run (a dead daemon, a
+// spent budget) leaves the output unvetted and says so, rather than blocking
+// every tool call on an availability failure.
 registerFaultPolicy(HOOK_NAME, {
   event: HookEvent.POST_TOOL_USE,
   guarded: "tool output",
-  alwaysClosed: secretsEnabled,
   closed: (ctx) =>
-    failClosedParts(
-      ctx.input,
-      suppressionMessage(ctx.message) +
-        (ctx.pinnedClosed ? SECRETS_PIN_NOTE : ""),
-      ctx.remedy,
-    ),
+    failClosedParts(ctx.input, suppressionMessage(ctx.message), ctx.remedy),
 });
 
 /**

package/claude-hooks/sanitize-user-prompt.mjs

@@ -28,7 +28,6 @@ import {
 } from "./lib/hook-io.mjs";
 import {
   registerFaultPolicy,
-  KNOB_DECIDES,
   hookFaultOutcome,
   writeFaultOutcome,
 } from "./lib/hook-fault.mjs";
@@ -86,7 +85,6 @@ const HOOK_NAME = "sanitize-user-prompt";
 registerFaultPolicy(HOOK_NAME, {
   event: HookEvent.USER_PROMPT_SUBMIT,
   guarded: "prompt",
-  alwaysClosed: KNOB_DECIDES,
   closed: (ctx) => ({
     envelope: {
       decision: "block",
@@ -145,9 +143,8 @@ export function judgeSanitizeUserPrompt(
   const { Decision, EventKind } = controlPlane();
   // A payload the adapter cannot classify carries no readable prompt, so an
   // abstain would fail OPEN on harness contract drift; this gate's posture is
-  // deny-when-blind. (Renders through the adapter's top-level decision:"block"
-  // channel — a non-PRE_TOOL event has no permissionDecision body — which Claude
-  // honors on UserPromptSubmit.)
+  // deny-when-blind. (runJudgeCli's renderEscalated blocks it with exit 2 and
+  // the reason on stderr, which Claude honors on UserPromptSubmit.)
   if (event.event === EventKind.UNKNOWN)
     return { decision: Decision.DENY, reason: messages.unknownEvent };
   if (event.event !== EventKind.PROMPT_SUBMIT)

package/claude-hooks/scan-invisible-chars.mjs

@@ -39,7 +39,6 @@ import {
 } from "./lib/hook-io.mjs";
 import {
   registerFaultPolicy,
-  KNOB_DECIDES,
   hookFaultOutcome,
   writeFaultOutcome,
 } from "./lib/hook-fault.mjs";
@@ -166,7 +165,6 @@ function faultLine(ctx) {
 registerFaultPolicy(HOOK_NAME, {
   event: HookEvent.SESSION_START,
   guarded: "instruction files",
-  alwaysClosed: KNOB_DECIDES,
   open: (ctx) => ({
     stderr: `${faultLine(ctx)} Passing through unguarded; set AGENT_SANITIZER_FAIL_OPEN=0 to arm the tool-call gate instead.\n`,
     exitCode: 1,

package/claude-hooks/scan-loaded-instructions.mjs

@@ -32,7 +32,6 @@ import {
 } from "./lib/hook-io.mjs";
 import {
   registerFaultPolicy,
-  KNOB_DECIDES,
   hookFaultOutcome,
   writeFaultOutcome,
 } from "./lib/hook-fault.mjs";
@@ -123,7 +122,6 @@ function emptyPayloadParts(ctx) {
 registerFaultPolicy(HOOK_NAME, {
   event: HookEvent.INSTRUCTIONS_LOADED,
   guarded: "a loaded instruction file",
-  alwaysClosed: KNOB_DECIDES,
   open: (ctx) =>
     emptyPayloadParts(ctx) ?? {
       stderr: `${faultLine(ctx)} Passing through unguarded; set AGENT_SANITIZER_FAIL_OPEN=0 to arm the tool-call gate instead.\n`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.67.1",
+  "version": "2.68.0",
   "description": "Defend an agent against hidden-content injection: strip payload-capable invisible Unicode and ANSI, splice out human-invisible HTML, and flag data-exfil URLs in untrusted text before any model sees it.",
   "type": "module",
   "repository": {
@@ -227,7 +227,7 @@
     "SECURITY.md"
   ],
   "dependencies": {
-    "agent-control-plane-core": "0.8.1",
+    "agent-control-plane-core": "0.11.2",
     "css-tree": "^3.2.1",
     "hast-util-from-parse5": "8.0.3",
     "mdast-util-gfm": "3.1.0",

package/src/output.mjs

@@ -174,18 +174,19 @@ function mutate(state, text, report) {
  * Run Layer 4 (`options.redact`, when set) over the state's current text and
  * fold any finding back in. The single Layer-4 invocation site FOR THE PIPELINE
  * STATE: the first pass and the re-run after a span deletion are the same call,
- * so they share one fail-closed handling, warning prose and invariants.
+ * so they share one throw-on-fault handling, warning prose and invariants.
  *
  * One other site runs Layer 4 deliberately: {@link vetStageValue}, which vets a
  * stage value on its way out and has no `PipelineState` to fold a finding into.
  * It shares the post-redaction invariant (normalize what the redactor's own
- * output may have stranded) but NOT the fail-closed policy — it withholds the
- * one field rather than suppressing the whole output. Adding a third site means
+ * output may have stranded) but NOT the fault handling — it withholds the one
+ * field instead of throwing. Adding a third site means
  * re-deciding both halves, so route through one of these two instead.
  *
- * Fails CLOSED: a redactor we could not run might have let a secret through, so
- * the throw is rethrown wrapped and the caller suppresses the output rather than
- * emitting an unvetted value with a warning.
+ * Throws rather than returning unvetted text: a redactor we could not run might
+ * have let a secret through, so the seam never hands back a value as if it were
+ * vetted. The throw is rethrown wrapped and the CALLER's fault posture decides
+ * what reaches the model (the Claude Code hooks: AGENT_SANITIZER_FAIL_OPEN).
  * @param {PipelineState} state
  * @param {SanitizeTextOptions} options
  * @returns {Promise<void>}
@@ -200,7 +201,7 @@ async function runRedact(state, options) {
   } catch (l4err) {
     throw new Error(
       `CRITICAL: secret redaction failed (${errMessage(l4err)}). ` +
-        "Failing closed — tool output suppressed.",
+        "This text was not vetted for secrets.",
       { cause: l4err },
     );
   }
@@ -599,8 +600,8 @@ async function vetStageValue(text, redact, findings, label) {
     return secrets ? normalizeLoneSurrogates(secrets.text) : text;
   } catch {
     // A WARNING: the caller asked for this field and is not getting it, and the
-    // reason is an unrunnable redactor — the same fault that fails `cleaned`
-    // closed, just with a survivable remedy here.
+    // reason is an unrunnable redactor — the same fault that makes `cleaned`
+    // throw, just with a survivable remedy here.
     findings.push(warning(withheldWarning(label)));
     return undefined;
   }
@@ -629,11 +630,10 @@ async function vetStageValue(text, redact, findings, label) {
 
 /**
  * Run the configured layers over a single text blob. Layer 1 always runs; the
- * rest are opt-in via `options`. Layer 4 (`redact`) is the fail-closed path: a
- * redactor that throws is rethrown wrapped, so the caller suppresses the
- * output rather than emitting an unvetted value. That fail-closed behavior
- * also applies to Layer 4's re-scan after a Layer-5 span deletion (see Layer
- * 5, below) — a redactor failure there fails the whole call closed too.
+ * rest are opt-in via `options`. A Layer 4 (`redact`) redactor that throws is
+ * rethrown wrapped, so the caller answers it under its fault posture rather
+ * than receiving unvetted text as vetted. The same holds for Layer 4's re-scan
+ * after a Layer-5 span deletion (see Layer 5, below).
  * `reveal` is the pre-Layer-2 text, present only when the HTML splice removed
  * bytes, so a caller can persist what was hidden for later inspection (see
  * {@link applyMarkdownPipeline}); the field is omitted otherwise, and also when
@@ -677,7 +677,7 @@ export async function sanitizeText(text, options = {}) {
   const { reveal: revealText, splices: stageSplices } =
     await applyMarkdownPipeline(state, options);
 
-  // Layer 4 — fail closed (see runRedact).
+  // Layer 4 — throws on a redactor fault (see runRedact).
   await runRedact(state, options);
 
   // Layer 5 — secure span-deletion slot (see module doc). A warning-only result

package/types/claude-hooks/lib/control-plane.d.mts

@@ -2,30 +2,33 @@
  * 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]
+ * @param {{ claudeAdapter?: unknown, Decision?: unknown, EventKind?: unknown, renderEscalated?: unknown }} [overrides]
  * @returns {{
  *   claudeAdapter: typeof import("agent-control-plane-core/claude").claudeAdapter,
  *   Decision: typeof import("agent-control-plane-core/contract").Decision,
  *   EventKind: typeof import("agent-control-plane-core/contract").EventKind,
+ *   renderEscalated: typeof import("agent-control-plane-core/contract").renderEscalated,
  * }}
  */
 export function controlPlane(overrides?: {
     claudeAdapter?: unknown;
     Decision?: unknown;
     EventKind?: unknown;
+    renderEscalated?: unknown;
 }): {
     claudeAdapter: typeof import("agent-control-plane-core/claude").claudeAdapter;
     Decision: typeof import("agent-control-plane-core/contract").Decision;
     EventKind: typeof import("agent-control-plane-core/contract").EventKind;
+    renderEscalated: typeof import("agent-control-plane-core/contract").renderEscalated;
 };
 /**
  * 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.
+ * stdout as JSON only on exit 0, and that body is the one channel that carries
+ * every verdict field (updatedInput, additionalContext) beside the decision.
+ * For this host the stdout JSON's permissionDecision IS the enforcement
+ * channel, and a rendered verdict always exits 0.
  * @param {{ stdout?: unknown }} response a NativeResponse from adapter.render
  * @returns {string | null}
  */
@@ -38,8 +41,10 @@ export function nativeStdout(response: {
  * 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 —
+ * and a verdict exits 0 in the stdout JSON (see nativeStdout). The verdict
+ * renders through the package's renderEscalated: a response with no stdout body
+ * that still blocks (a deny on a payload that names no event) blocks through its
+ * exit code and stderr instead. 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.
@@ -57,15 +62,19 @@ export function nativeStdout(response: {
  * @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
+ * @param {(chunk: string) => void} [opts.writeErr]  injectable stderr writer
+ * @param {(code: number) => void} [opts.setExitCode]  injectable exit-code setter
  * @param {import("./hook-timing.mjs").ReportTo} [opts.reportTo]  the composer
  *   that owns this hook, which a slow-run notice names and sends the report to;
  *   omitted, the notice names this package
  * @returns {Promise<void>}
  */
-export function runJudgeCli(hookName: string, judge: (event: import("agent-control-plane-core").ToolCallEvent) => import("agent-control-plane-core").Verdict | Promise<import("agent-control-plane-core").Verdict>, { onError, transformInput, readInput, write, reportTo, }: {
+export function runJudgeCli(hookName: string, judge: (event: import("agent-control-plane-core").ToolCallEvent) => import("agent-control-plane-core").Verdict | Promise<import("agent-control-plane-core").Verdict>, { onError, transformInput, readInput, write, writeErr, setExitCode, reportTo, }: {
     onError: (err: unknown, input: unknown) => void;
     transformInput?: ((input: unknown) => unknown) | undefined;
     readInput?: (() => Promise<unknown>) | undefined;
     write?: ((chunk: string) => void) | undefined;
+    writeErr?: ((chunk: string) => void) | undefined;
+    setExitCode?: ((code: number) => void) | undefined;
     reportTo?: import("./hook-timing.mjs").ReportTo | undefined;
 }): Promise<void>;

package/types/claude-hooks/lib/hook-fault.d.mts

@@ -32,8 +32,7 @@ export function defaultOpen(ctx: FaultContext): FaultParts;
 /**
  * Resolve `hook`'s response to its own failure under the caller's posture. This
  * is the ONLY place {@link failOpenEnabled} is consulted on a hook fault, so the
- * knob cannot be honored in three hooks and skipped in the fourth — and the
- * only place a policy's `alwaysClosed` can override it.
+ * knob cannot be honored in three hooks and skipped in the fourth.
  * @param {string} hook
  * @param {unknown} err
  * @param {Record<string, any> & {
@@ -65,63 +64,6 @@ export function writeFaultOutcome(outcome: FaultOutcome, write?: (chunk: string)
  * @type {readonly string[]}
  */
 export const FAULT_POLICY_HOOKS: readonly string[];
-/**
- * What a hook's fault renders to. `fields`/`envelope` are the stdout response
- * (`fields` is the `hookSpecificOutput` body, wrapped with the policy's event;
- * `envelope` is a hook that answers with a top-level shape instead, like
- * UserPromptSubmit's `{decision:"block"}`); `stderr` and `exitCode` are the
- * process-level halves a hook with no stdout channel uses; `armAlert` asks the
- * caller to persist its cross-hook alert so a LATER gate carries the closed
- * posture the faulting hook could not express itself.
- * @typedef {{
- *   posture: "open" | "closed",
- *   fields: Record<string, unknown> | null,
- *   fallbackFields: Record<string, unknown> | null,
- *   envelope: object | null,
- *   stderr: string | null,
- *   exitCode: number,
- *   armAlert: boolean,
- * }} FaultOutcome
- */
-/**
- * What a policy's `open`/`closed` builder returns: any subset of a
- * {@link FaultOutcome}'s renderable slots. Everything omitted takes its default
- * (no output, exit 0, no alert).
- * @typedef {{
- *   fields?: Record<string, unknown>,
- *   fallbackFields?: Record<string, unknown>,
- *   envelope?: object,
- *   stderr?: string,
- *   exitCode?: number,
- *   armAlert?: boolean,
- * }} FaultParts
- */
-/**
- * The context a builder is handed: the caller's own inputs (whatever it passed
- * to {@link hookFaultOutcome}) plus the values every hook derived by hand
- * before — the hook name, the scrubbed error message, and the model-facing
- * open-posture warning — and `pinnedClosed`, true when the policy's
- * `alwaysClosed` overrode an open knob, so the closed arm can say why.
- * @typedef {Record<string, any> & {
- *   hook: string,
- *   err: unknown,
- *   message: string,
- *   openContext: string,
- *   pinnedClosed: boolean,
- * }} FaultContext
- */
-/**
- * Whether a hook's faults are withheld whatever AGENT_SANITIZER_FAIL_OPEN says,
- * for the caller's environment.
- * @typedef {(
- *   env: NodeJS.ProcessEnv | Record<string, string | undefined> | undefined,
- * ) => boolean} AlwaysClosed
- */
-/**
- * The `alwaysClosed` of a hook whose posture the knob alone decides.
- * @type {AlwaysClosed}
- */
-export const KNOB_DECIDES: AlwaysClosed;
 /**
  * What a hook's fault renders to. `fields`/`envelope` are the stdout response
  * (`fields` is the `hookSpecificOutput` body, wrapped with the policy's event;
@@ -157,32 +99,23 @@ export type FaultParts = {
  * The context a builder is handed: the caller's own inputs (whatever it passed
  * to {@link hookFaultOutcome}) plus the values every hook derived by hand
  * before — the hook name, the scrubbed error message, and the model-facing
- * open-posture warning — and `pinnedClosed`, true when the policy's
- * `alwaysClosed` overrode an open knob, so the closed arm can say why.
+ * open-posture warning.
  */
 export type FaultContext = Record<string, any> & {
     hook: string;
     err: unknown;
     message: string;
     openContext: string;
-    pinnedClosed: boolean;
 };
 /**
- * Whether a hook's faults are withheld whatever AGENT_SANITIZER_FAIL_OPEN says,
- * for the caller's environment.
- */
-export type AlwaysClosed = (env: NodeJS.ProcessEnv | Record<string, string | undefined> | undefined) => boolean;
-/**
- * A hook's declared posture. `alwaysClosed` is REQUIRED, so every hook states
- * on the record whether the knob can open it: {@link KNOB_DECIDES}, or a
- * predicate that pins the CLOSED arm — how a guarantee the docs make
- * unconditionally (Layer 4 withholds what it could not vet) is enforced in the
- * one posture resolver rather than by a hook re-reading the knob.
+ * A hook's declared posture. There is deliberately no way for a policy to pin
+ * the CLOSED arm: AGENT_SANITIZER_FAIL_OPEN alone decides, so no hook fault can
+ * withhold a tool output or block a prompt unless the operator set the knob to
+ * `0`. A pin turns any bug in the guarded layer into every tool call failing.
  */
 export type FaultPolicy = {
     event: string | null;
     guarded: string;
-    alwaysClosed: AlwaysClosed;
     open?: (ctx: FaultContext) => FaultParts;
     closed: (ctx: FaultContext) => FaultParts;
 };