agent-sanitizer 2.14.14 → 2.16.0

package/README.md

@@ -114,12 +114,17 @@ buy you:
    first web page, and the occasional over-redaction of credential-shaped text —
    `AGENT_SANITIZER_OUTPUT_DISABLED=1` opts out of the rewrites.
 
-Failure is loud by design: every layer fails closed, so you see suppressed tool
-output (`[output sanitizer unavailable — original output suppressed]`), blocked
-prompts, or permission asks whose reason names the cause. The exception is a
-plugin that never loaded at all — Claude Code reads a crashed hook as "no
-objection", so confirm with `/plugin` rather than reading a quiet session as a
-working one.
+Failure is loud by design. Installed as Claude Code hooks the layers fail
+**open**: a hook that could not run lets the action through rather than halting
+your session on its own breakage — but it says so, in a warning the model and
+the transcript both carry. Set `AGENT_SANITIZER_FAIL_OPEN=0` and the same
+failures block instead: suppressed tool output
+(`[output sanitizer unavailable — original output suppressed]`), blocked
+prompts, permission asks whose reason names the cause. Either way, a plugin that
+never loaded at all is invisible — Claude Code reads a crashed hook as "no
+objection" — so confirm with `/plugin` rather than reading a quiet session as a
+working one. Neither posture touches what a sanitizer that RAN decided (see
+`plugin/README.md`).
 
 ## Using it with Claude Code
 
@@ -182,8 +187,8 @@ surface is the `--hook=` CLI, so these move between minor versions.
 
 **`sanitize-output` takes a host-extension bag** — an optional last argument on
 `sanitizeText`, `sanitizeValue`, `evaluateToolOutput`, `judgeSanitizeOutput`, and
-`cliMain`, so a composer that wraps `cliMain` gets the hook's exact fail-closed
-CLI wiring plus its own policy:
+`cliMain`, so a composer that wraps `cliMain` gets the hook's exact CLI wiring
+plus its own policy:
 
 | Field        | Runs                                                     | Does                                                                                 |
 | ------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------ |
@@ -194,11 +199,13 @@ CLI wiring plus its own policy:
 
 Omit the bag and every seam is inert — the verdicts are byte-identical to this
 module alone. A callback that throws is **not** caught: it lands in the CLI's
-fail-closed catch and the tool output is suppressed, so a broken extension can
-never degrade into showing unvetted output. `postText` deliberately does not run
-on object field NAMES: a callback sees only the string and the tool, so it cannot
+failure catch, so a broken extension gets the caller's failure posture — the
+warning-and-pass-through default, or suppression under
+`AGENT_SANITIZER_FAIL_OPEN=0`. Wire `emitFailClosed` yourself if a host must
+suppress regardless of the environment. `postText` deliberately does not run on
+object field NAMES: a callback sees only the string and the tool, so it cannot
 tell a schema key from content, and rewriting a key can collapse two fields into
-one name — which this hook turns into whole-output suppression.
+one name — which this hook answers with that same failure path.
 
 Beyond the credential-shaped names it infers, the env-bound redaction set unions
 `_AGENT_SANITIZER_EXTRA_SECRET_VARS` — a comma-separated list of `[A-Z0-9_]`
@@ -208,8 +215,9 @@ choosing. A malformed entry throws rather than being dropped.
 **Layer 4 needs the Python engine.** The plugin ships it and provisions it at
 SessionStart; a hand-wired npm install does not, so install it yourself —
 `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.
+Without it `sanitize-output` fails: secret-shaped output reaches the model
+unredacted with a warning attached, or is suppressed under
+`AGENT_SANITIZER_FAIL_OPEN=0`. 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
@@ -244,8 +252,8 @@ hook module, and every consumer waits on that path instead. `lib/control-plane`
 resolves the marker at module scope, so a call that lands after that import
 warns on stderr — it cannot steer the wait that already started.
 
-**A host's own remedy can replace the packaged one in every fail-closed
-reason.** Deep call sites (`lib/control-plane`'s missing-package throw) take no
+**A host's own remedy can replace the packaged one in every failure reason**
+(the fail-closed verdicts and the fail-open warning alike). Deep call sites (`lib/control-plane`'s missing-package throw) take no
 remedy argument, so by default they can only say `pnpm install`. A host whose
 install has one entry point calls `configureMissingPackageRemedy(text)` (from
 `lib/hook-io`) — typically at its bundle entry — and every remedy-less
@@ -262,7 +270,7 @@ credentials (and their length floor) in a registry of its own feeds the packaged
 helpers from it instead of forking the module. Unset fields keep the package
 derivation; `null` restores it entirely. A malformed source — a non-object, a
 key the seam does not read, a bad field — throws on first use, inside the
-consuming hook's fail-closed catch, never at configure time.
+consuming hook's failure catch, never at configure time.
 
 Hook internals are tuned by `_AGENT_SANITIZER_*` variables (redactor daemon
 path/socket/timeouts, sanitize budget, trace channel, Layer-2 reveal dir). The

package/THREAT-MODEL.md

@@ -215,3 +215,49 @@ are load-bearing and **fail closed**:
 
 File access and the redactor are injected via `io`; the package performs no I/O
 of its own and bundles no secret engine.
+
+## Failure posture (`AGENT_SANITIZER_FAIL_OPEN`)
+
+Installed as Claude Code hooks, these fail **open**: a hook that could not
+complete lets the guarded action through with a warning in `additionalContext`
+rather than blocking the session. `AGENT_SANITIZER_FAIL_OPEN=0` (or `false`)
+restores the fail-closed verdicts — block, ask, suppress. The posture covers
+every way a hook can fail: the launcher not starting (no `node`, missing or
+corrupt bundle), the package never loading, a payload that never parsed, and a
+layer that ran and threw.
+
+**The open default is not enforceable against content.** Several of those
+failures are composable by whoever authored the payload — in the output hook
+alone, the key-collision guard (two field names that collapse to one after
+Layer 1), a nesting depth that overflows the sanitize walk, and a redaction
+budget exhausted by many secret-shaped leaves. Under the open posture a tool
+response crafted to provoke one is shown to the model verbatim, secrets
+included. So an attacker who controls tool output has a route past these layers
+whenever the default is left in place, and the mitigation is the knob, not a
+narrower failure classification: `=0` closes all of it.
+
+That trade is deliberate, and it is scoped to the Claude Code plugin. The
+library's own fail-closed entry points are unchanged and knob-blind —
+`failClosedFields` in `claude-hooks/pretooluse-sanitize.mjs` and `emitFailClosed`
+in `claude-hooks/sanitize-output.mjs` — so a host that wires those directly (as
+`test/downstream-parity.test.mjs` shows) keeps strict failure semantics by
+construction, with no env var to remember and none an agent could set for it.
+
+Two things the posture does NOT reach, in either direction:
+
+- **Detection verdicts.** It speaks only to the hook FAILING; a working
+  sanitizer that found an injection blocks under both settings.
+- **An unknown `--hook=` mode**, which still exits 2. That is static wiring
+  corruption, and passing it through would mean no hook ever runs — silently,
+  for the life of the install.
+
+The knob is operator configuration read from the process environment, so
+anything that can set it for a session — `.claude/settings.json`'s `env` block,
+a shell rc file, `direnv` — can also set it the other way, and a prompt-injected
+agent with edit access to those files is such a thing. That is not a regression
+under an open default (there is nothing for it to disarm), but it does mean `=0`
+is only as durable as the files carrying it.
+
+The knob adds no layer and changes no layer's semantics. Ambiguous input still
+fails open at the detection level (precision over recall), as it always has —
+that is a separate, and unrelated, sense of the phrase.

package/claude-hooks/lib/hook-io.mjs

@@ -194,6 +194,86 @@ export const PermissionDecision = Object.freeze({
   ASK: "ask",
 });
 
+/**
+ * The public knob over the hooks' INFRASTRUCTURE failure posture. Installed as
+ * Claude Code hooks these fail OPEN by default — a hook that could not run lets
+ * the guarded action through with a loud warning rather than blocking the
+ * session on its own breakage. Setting it to `"0"` restores the fail-CLOSED
+ * posture (block/ask/suppress).
+ *
+ * The knob covers the hooks' own failures ONLY. What a working sanitizer
+ * DECIDED is untouched by it, and so is the {@link failClosedFields}-style
+ * wiring a downstream host does directly — a host that wants strictness gets it
+ * by construction, not by remembering to set an env var.
+ */
+export const FAIL_OPEN_ENV = "AGENT_SANITIZER_FAIL_OPEN";
+
+/**
+ * Values that turn the default posture back to fail-closed. Matched exactly,
+ * so the launcher's shell `case` can state the same two literals — a
+ * case-insensitive match here would need `tr`, which the launcher cannot reach
+ * (it runs its no-node arm on shell builtins alone) and the two would drift.
+ */
+const FAIL_CLOSED_VALUES = new Set(["0", "false"]);
+
+/**
+ * Whether hook failures pass the guarded action through. True unless the caller
+ * explicitly asked for the closed posture.
+ *
+ * The accepted opt-out spellings are a SET rather than the single exact `"1"`
+ * the AGENT_SANITIZER_*_DISABLED knobs use, because the direction of the
+ * mistake is reversed: those default to the safe side, so an unrecognized value
+ * there costs nothing, while here it leaves an operator who asked for
+ * strictness without it. `"false"` is the one spelling reached for by reflex,
+ * so it is honored; everything else (`""`, `"no"`, `"off"`) is the open posture.
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ * @returns {boolean}
+ */
+export function failOpenEnabled(env = process.env) {
+  return !FAIL_CLOSED_VALUES.has(env[FAIL_OPEN_ENV] ?? "");
+}
+
+/**
+ * The model-facing warning accompanying a fail-open pass-through. Emitted as
+ * `additionalContext` so the transcript still carries the failure: the posture
+ * gives up ENFORCEMENT, not visibility, and stdout is never left empty (which
+ * Claude Code would record as a clean run rather than a degraded one).
+ *
+ * The reinstall remedy rides along when the failure looks like an unloaded
+ * binding. A `DEP_UNAVAILABLE` error already carries its remedy in the message
+ * `safeErrMessage` splices in below, but the bare TypeError V8 raises for an
+ * undefined binding names neither the package nor the fix — and under this
+ * posture there is no permissionDecisionReason carrying one either, so the only
+ * message telling a reader how to un-break the install would be the one that
+ * went missing. `failedPackages`/`packageMessage` are injectable for the same
+ * reason `depLoadHint`'s are: the recorded-failure set is process-wide and
+ * untestable otherwise.
+ * @param {string} hookName
+ * @param {string} guarded  what passed through, e.g. "tool output"
+ * @param {unknown} err
+ * @param {() => string[]} [failedPackages]
+ * @param {(pkg: string) => string} [packageMessage]
+ * @returns {string}
+ */
+export function failOpenContext(
+  hookName,
+  guarded,
+  err,
+  failedPackages = failedLazyPackages,
+  packageMessage = missingPackageMessage,
+) {
+  // Same inference depLoadHint makes, and confined the same way: only a
+  // TypeError, only while the loader holds a recorded failure. Naming a package
+  // on any other throw would send the reader to a reinstall that fixes nothing.
+  const [pkg] = err instanceof TypeError ? failedPackages() : [];
+  const hint = pkg === undefined ? "" : ` ${packageMessage(pkg)}`;
+  return (
+    `WARNING: the ${hookName} hook failed (${safeErrMessage(err)}) — this ` +
+    `${guarded} passed through UNSANITIZED. Treat its contents as ` +
+    `untrusted.${hint} Set ${FAIL_OPEN_ENV}=0 to fail closed on hook failures.`
+  );
+}
+
 // Unpaired UTF-16 surrogates: a high half with no low follower, or a low half
 // with no high lead. Hook text spliced into the model's context must be
 // well-formed UTF-16 there, so the sanitizers normalize these out before

package/claude-hooks/lib/redactor-client.mjs

@@ -148,15 +148,17 @@ function isRespawnable(err) {
 }
 
 /**
- * The error thrown to fail a single redaction closed; the caller suppresses the
- * output.
+ * The error thrown when a single redaction cannot be completed. What the caller
+ * then does is its posture, not this module's — the message therefore states
+ * the FACT (the output was never vetted) and no consequence, since a hook
+ * running fail-open splices it into a warning that says the opposite.
  * @param {unknown} cause
  * @returns {Error}
  */
 function failClosed(cause) {
   const detail = cause instanceof Error ? cause.message : String(cause);
   return new Error(
-    `secret redaction unavailable (${detail}); cannot vet secret-shaped output — failing closed`,
+    `secret redaction unavailable (${detail}); secret-shaped output could not be vetted`,
   );
 }
 

package/claude-hooks/pretooluse-sanitize.mjs

@@ -34,6 +34,8 @@ import {
   registeredLazyModule,
   emitHookResponse,
   safeErrMessage,
+  failOpenEnabled,
+  failOpenContext,
   HookEvent,
   PermissionDecision,
 } from "./lib/hook-io.mjs";
@@ -398,6 +400,12 @@ export function depLoadHint(
  * fatigue, no latency. A LAYER/engine throw after a clean parse (`parsedOk` true
  * — redactor daemon down, package not loaded) is the sanitizer being UNAVAILABLE,
  * so it ASKS to keep a human in the loop rather than hard-block on infrastructure.
+ *
+ * Deliberately knob-blind: this is the fail-CLOSED posture itself, so it ignores
+ * AGENT_SANITIZER_FAIL_OPEN — a host that wires it directly keeps strictness by
+ * construction, with no env var to remember. A host that instead wants the
+ * caller's posture (fail-open by default) wires {@link hookFailureFields},
+ * which delegates here when the posture is closed.
  * @param {boolean} parsedOk whether the input parsed before the failure
  * @param {unknown} err
  * @param {{ messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>, hint?: string }} [opts]
@@ -419,12 +427,37 @@ export function failClosedFields(parsedOk, err, opts = {}) {
   };
 }
 
+/**
+ * The hookSpecificOutput fields for a hook-level failure under the CALLER's
+ * chosen posture: fail-OPEN by default — a warning context and no
+ * permissionDecision, so the tool call proceeds unsanitized — or the
+ * fail-CLOSED verdict of {@link failClosedFields} when the caller set
+ * AGENT_SANITIZER_FAIL_OPEN=0.
+ *
+ * The posture covers this hook's own failures, whatever their cause. What it
+ * does NOT cover is the verdict of a sanitizer that ran: a payload
+ * judgePreToolUseSanitize denied is denied in both postures.
+ * @param {boolean} parsedOk whether the input parsed before the failure
+ * @param {unknown} err
+ * @param {{
+ *   messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>,
+ *   hint?: string,
+ *   env?: NodeJS.ProcessEnv | Record<string, string | undefined>,
+ * }} [opts]
+ * @returns {Record<string, unknown>}
+ */
+export function hookFailureFields(parsedOk, err, opts = {}) {
+  if (failOpenEnabled(opts.env))
+    return { additionalContext: failOpenContext(HOOK_NAME, "tool input", err) };
+  return failClosedFields(parsedOk, err, opts);
+}
+
 // Stryker disable all: CLI wiring — it runs only in the spawned hook
 // subprocess, never in-process, so every mutant from here down is NoCoverage.
 // The exported judgePreToolUseSanitize and failClosedFields above carry the
 // real, mutation-tested logic.
 /**
- * The hook's CLI: parse → judge → render, with this hook's fail-closed posture.
+ * The hook's CLI: parse → judge → render, under the caller's failure posture.
  * Exported so a bundle entry (which must claim the CLI slot before this module
  * loads) can run the exact same wiring instead of duplicating the onError
  * posture.
@@ -447,15 +480,16 @@ export async function cliMain(opts = {}) {
         trace: emitTrace,
       }),
     {
-      // Fail closed WITHOUT the package: unparsable INPUT (`input` undefined)
-      // hard-denies (adversary-inducible, no benefit to failing); any throw
-      // after a clean parse — a layer engine down or the control-plane package
-      // unavailable — asks to keep a human in the loop. emitHookResponse renders
-      // natively, so this posture holds even when the adapter never loaded.
+      // The caller's posture, WITHOUT the package: pass through with a warning
+      // by default, or — under AGENT_SANITIZER_FAIL_OPEN=0 — hard-deny an
+      // unparsable INPUT (`input` undefined; adversary-inducible, no benefit to
+      // failing) and ASK on any throw after a clean parse, keeping a human in
+      // the loop. emitHookResponse renders natively, so either posture holds
+      // even when the adapter never loaded.
       onError: (err, input) =>
         emitHookResponse(
           HookEvent.PRE_TOOL_USE,
-          failClosedFields(input !== undefined, err, {
+          hookFailureFields(input !== undefined, err, {
             messages,
             hint: depLoadHint(err, messages.remedy),
           }),

package/claude-hooks/sanitize-output.mjs

@@ -27,6 +27,8 @@ import {
   emitHookResponse,
   errMessage,
   safeErrMessage,
+  failOpenEnabled,
+  failOpenContext,
   makeDeadline,
   lazyImportErrorFor,
   missingPackageMessage,
@@ -247,11 +249,12 @@ export async function sanitizeText(
     exfilScan: webIngress,
     sgrCarveOut: !webIngress,
     deadline,
-    // Layer 4 — the seam fails closed on a redactor throw (rethrows wrapped,
-    // which the CLI turns into output suppression). Surface the failure to the
-    // operator's terminal here first: the suppression rides in
-    // additionalContext, which only the model sees, so a degraded redactor
-    // would otherwise be invisible to the human.
+    // Layer 4 — the seam rethrows a redactor throw wrapped, and the CLI applies
+    // the caller's posture to it. Surface the failure to the operator's
+    // terminal here first: whatever the CLI decides rides in additionalContext,
+    // which only the model sees, so a degraded redactor would otherwise be
+    // invisible to the human — and under the fail-open default this line is the
+    // ONLY signal the human gets.
     redact: async (/** @type {string} */ content) => {
       let secrets;
       try {
@@ -259,7 +262,7 @@ export async function sanitizeText(
       } catch (l4err) {
         process.stderr.write(
           `sanitize-output: CRITICAL: secret redaction failed (${errMessage(l4err)}). ` +
-            "Failing closed — tool output suppressed. Fix the redactor installation.\n",
+            "This output was never vetted for secrets. Fix the redactor installation.\n",
         );
         throw l4err;
       }
@@ -564,6 +567,48 @@ export function emitFailClosed(
   }
 }
 
+/**
+ * Emit the PostToolUse failure response under the CALLER's chosen posture:
+ * 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.
+ *
+ * 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
+ * (colliding field names, a nesting depth that overflows the walk, a redaction
+ * budget spent on a thousand secret-shaped leaves), and each of those throws is
+ * guarding content the open posture hands to the model verbatim, secrets
+ * included. An operator who cares more about withholding a secret than about
+ * keeping the session moving sets the knob to `0`.
+ * @param {any} input  parsed hook input, or undefined if parsing threw
+ * @param {unknown} err
+ * @param {(fields: Record<string, unknown>) => void} [emit]
+ * @param {string} [remedy]  what a reader should run; hosts pass their own
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ * @returns {void}
+ */
+export function emitHookFailure(
+  input,
+  err,
+  emit = (fields) => emitHookResponse(HookEvent.POST_TOOL_USE, fields),
+  remedy = DEFAULT_MISSING_PACKAGE_REMEDY,
+  env = process.env,
+) {
+  if (failOpenEnabled(env)) {
+    emit({
+      additionalContext: failOpenContext("sanitize-output", "tool output", err),
+    });
+    return;
+  }
+  emitFailClosed(
+    input,
+    `[SANITIZATION FAILED — original output suppressed for safety. Hook error: ${safeErrMessage(err)}]`,
+    emit,
+    remedy,
+  );
+}
+
 /**
  * Run the sanitization pipeline over a tool output and return the contract-
  * shaped verdict fields — `mutated_output` (the shape-matching sanitized value)
@@ -771,7 +816,7 @@ export function withPostToolUseDefault(input) {
 // failClosedReplacement) is exercised in-process by the unit suite; the
 // end-to-end wire contract is pinned by the subprocess tests.
 /**
- * The hook's CLI: parse → judge → render, with this hook's fail-closed posture.
+ * The hook's CLI: parse → judge → render, under the caller's failure posture.
  * Exported so a bundle entry (which must claim the CLI slot before this module
  * loads) can run the exact same wiring instead of duplicating the onError
  * posture. That entry is also the only place a host's {@link SanitizeExtensions}
@@ -792,16 +837,11 @@ export async function cliMain(ext = {}) {
       // back the parsed `input` even when the control-plane load failed, so the
       // suppression shape-matches the real tool_response). emitFailClosed itself
       // falls back to a bare string if that shape-matching replacement or its
-      // serialization throws, so even a pathological input fails closed.
+      // serialization throws, so even a pathological input fails closed. A caller
+      // that set AGENT_SANITIZER_FAIL_OPEN=1 gets the warning-only pass-through
+      // instead — see emitHookFailure.
       onError: (err, input) =>
-        emitFailClosed(
-          input,
-          "[SANITIZATION FAILED — original output suppressed for safety. Hook error: " +
-            safeErrMessage(err) +
-            "]",
-          undefined,
-          ext.remedy,
-        ),
+        emitHookFailure(input, err, undefined, ext.remedy),
     },
   );
 }

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

@@ -21,6 +21,9 @@
 import {
   readStdinJson,
   safeErrMessage,
+  failOpenEnabled,
+  failOpenContext,
+  HookEvent,
   isMain,
   lazyImport,
   missingPackageError,
@@ -168,12 +171,14 @@ export function judgeSanitizeUserPrompt(
  *   strip?: ((s: string) => string) | null,
  *   overrides?: Partial<typeof USER_PROMPT_MESSAGES>,
  *   trace?: import("./lib/trace.mjs").TraceFn,
+ *   env?: NodeJS.ProcessEnv | Record<string, string | undefined>,
  * }} [opts]
  *   `strip` is the ANSI stripper (defaults to the package's stripAnsiFully;
  *   injectable so the fail-closed path is testable); `overrides` are reason
  *   overrides, merged over the defaults so a partial table can never leave a field
  *   unset; `trace` is where engagement is announced, for a host with its own trace
- *   channel (see lib/trace.mjs).
+ *   channel (see lib/trace.mjs); `env` is the failure-posture source (see
+ *   failOpenEnabled), injectable so both postures are testable in-process.
  * @returns {Promise<void>}
  */
 export async function main(read, write, opts = {}) {
@@ -181,6 +186,7 @@ export async function main(read, write, opts = {}) {
     strip = stripAnsiFully,
     overrides = USER_PROMPT_MESSAGES,
     trace: sink = trace,
+    env = process.env,
   } = opts;
   const emitTrace = bestEffortTrace(sink);
   // Merged, not substituted — see judgeSanitizeUserPrompt. onError below is the
@@ -190,9 +196,11 @@ export async function main(read, write, opts = {}) {
   // runJudgeCli so this hook doesn't re-implement the control-plane boundary:
   // runJudgeCli reads stdin BEFORE loading the control-plane package, so a
   // load failure fails to this hook's posture (the onError block) instead of
-  // leaving stdin unread. The fail-closed onError writes the UserPromptSubmit
-  // `decision:"block"` envelope by hand because the adapter that would render it
-  // is exactly what may have failed to load.
+  // leaving stdin unread. onError writes its envelope by hand — the default
+  // warning-only pass-through, or the block a caller asked for with
+  // AGENT_SANITIZER_FAIL_OPEN=0 — because the adapter that would render it is
+  // exactly what may have failed to load. Either way this is the HOOK failing;
+  // a prompt the working stripper flagged is still blocked in both postures.
   await runJudgeCli(
     "sanitize-user-prompt",
     (event) => {
@@ -215,10 +223,23 @@ export async function main(read, write, opts = {}) {
       write,
       onError: (err) =>
         write(
-          JSON.stringify({
-            decision: "block",
-            reason: messages.hookFailed(safeErrMessage(err)),
-          }),
+          JSON.stringify(
+            failOpenEnabled(env)
+              ? {
+                  hookSpecificOutput: {
+                    hookEventName: HookEvent.USER_PROMPT_SUBMIT,
+                    additionalContext: failOpenContext(
+                      "sanitize-user-prompt",
+                      "prompt",
+                      err,
+                    ),
+                  },
+                }
+              : {
+                  decision: "block",
+                  reason: messages.hookFailed(safeErrMessage(err)),
+                },
+          ),
         ),
     },
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.14.14",
+  "version": "2.16.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": {

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

@@ -71,6 +71,43 @@ export function claimCliEntry(): void;
  * @returns {string|undefined}
  */
 export function readFlag(argv: string[], name: string): string | undefined;
+/**
+ * Whether hook failures pass the guarded action through. True unless the caller
+ * explicitly asked for the closed posture.
+ *
+ * The accepted opt-out spellings are a SET rather than the single exact `"1"`
+ * the AGENT_SANITIZER_*_DISABLED knobs use, because the direction of the
+ * mistake is reversed: those default to the safe side, so an unrecognized value
+ * there costs nothing, while here it leaves an operator who asked for
+ * strictness without it. `"false"` is the one spelling reached for by reflex,
+ * so it is honored; everything else (`""`, `"no"`, `"off"`) is the open posture.
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ * @returns {boolean}
+ */
+export function failOpenEnabled(env?: NodeJS.ProcessEnv | Record<string, string | undefined>): boolean;
+/**
+ * The model-facing warning accompanying a fail-open pass-through. Emitted as
+ * `additionalContext` so the transcript still carries the failure: the posture
+ * gives up ENFORCEMENT, not visibility, and stdout is never left empty (which
+ * Claude Code would record as a clean run rather than a degraded one).
+ *
+ * The reinstall remedy rides along when the failure looks like an unloaded
+ * binding. A `DEP_UNAVAILABLE` error already carries its remedy in the message
+ * `safeErrMessage` splices in below, but the bare TypeError V8 raises for an
+ * undefined binding names neither the package nor the fix — and under this
+ * posture there is no permissionDecisionReason carrying one either, so the only
+ * message telling a reader how to un-break the install would be the one that
+ * went missing. `failedPackages`/`packageMessage` are injectable for the same
+ * reason `depLoadHint`'s are: the recorded-failure set is process-wide and
+ * untestable otherwise.
+ * @param {string} hookName
+ * @param {string} guarded  what passed through, e.g. "tool output"
+ * @param {unknown} err
+ * @param {() => string[]} [failedPackages]
+ * @param {(pkg: string) => string} [packageMessage]
+ * @returns {string}
+ */
+export function failOpenContext(hookName: string, guarded: string, err: unknown, failedPackages?: () => string[], packageMessage?: (pkg: string) => string): string;
 /**
  * @param {number} [maxBytes] cap before aborting (overridable for tests)
  * @returns {Promise<any>}
@@ -380,6 +417,19 @@ export const PermissionDecision: Readonly<{
     DENY: "deny";
     ASK: "ask";
 }>;
+/**
+ * The public knob over the hooks' INFRASTRUCTURE failure posture. Installed as
+ * Claude Code hooks these fail OPEN by default — a hook that could not run lets
+ * the guarded action through with a loud warning rather than blocking the
+ * session on its own breakage. Setting it to `"0"` restores the fail-CLOSED
+ * posture (block/ask/suppress).
+ *
+ * The knob covers the hooks' own failures ONLY. What a working sanitizer
+ * DECIDED is untouched by it, and so is the {@link failClosedFields}-style
+ * wiring a downstream host does directly — a host that wants strictness gets it
+ * by construction, not by remembering to set an env var.
+ */
+export const FAIL_OPEN_ENV: "AGENT_SANITIZER_FAIL_OPEN";
 /**
  * Hard cap on hook stdin. A well-formed Claude Code hook payload is at most a
  * few MB (tool input plus the harness-truncated tool output); 64 MiB leaves

package/types/claude-hooks/pretooluse-sanitize.d.mts

@@ -57,6 +57,12 @@ export function depLoadHint(err: unknown, remedy?: string, failedPackages?: () =
  * fatigue, no latency. A LAYER/engine throw after a clean parse (`parsedOk` true
  * — redactor daemon down, package not loaded) is the sanitizer being UNAVAILABLE,
  * so it ASKS to keep a human in the loop rather than hard-block on infrastructure.
+ *
+ * Deliberately knob-blind: this is the fail-CLOSED posture itself, so it ignores
+ * AGENT_SANITIZER_FAIL_OPEN — a host that wires it directly keeps strictness by
+ * construction, with no env var to remember. A host that instead wants the
+ * caller's posture (fail-open by default) wires {@link hookFailureFields},
+ * which delegates here when the posture is closed.
  * @param {boolean} parsedOk whether the input parsed before the failure
  * @param {unknown} err
  * @param {{ messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>, hint?: string }} [opts]
@@ -67,7 +73,31 @@ export function failClosedFields(parsedOk: boolean, err: unknown, opts?: {
     hint?: string;
 }): Record<string, unknown>;
 /**
- * The hook's CLI: parse → judge → render, with this hook's fail-closed posture.
+ * The hookSpecificOutput fields for a hook-level failure under the CALLER's
+ * chosen posture: fail-OPEN by default — a warning context and no
+ * permissionDecision, so the tool call proceeds unsanitized — or the
+ * fail-CLOSED verdict of {@link failClosedFields} when the caller set
+ * AGENT_SANITIZER_FAIL_OPEN=0.
+ *
+ * The posture covers this hook's own failures, whatever their cause. What it
+ * does NOT cover is the verdict of a sanitizer that ran: a payload
+ * judgePreToolUseSanitize denied is denied in both postures.
+ * @param {boolean} parsedOk whether the input parsed before the failure
+ * @param {unknown} err
+ * @param {{
+ *   messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>,
+ *   hint?: string,
+ *   env?: NodeJS.ProcessEnv | Record<string, string | undefined>,
+ * }} [opts]
+ * @returns {Record<string, unknown>}
+ */
+export function hookFailureFields(parsedOk: boolean, err: unknown, opts?: {
+    messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>;
+    hint?: string;
+    env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+}): Record<string, unknown>;
+/**
+ * The hook's CLI: parse → judge → render, under the caller's failure posture.
  * Exported so a bundle entry (which must claim the CLI slot before this module
  * loads) can run the exact same wiring instead of duplicating the onError
  * posture.

package/types/claude-hooks/sanitize-output.d.mts

@@ -159,6 +159,28 @@ export function failClosedContext(depsLoaded?: () => boolean, remedy?: string):
  * @returns {void}
  */
 export function emitFailClosed(input: any, message: string, emit?: (fields: Record<string, unknown>) => void, remedy?: string): void;
+/**
+ * Emit the PostToolUse failure response under the CALLER's chosen posture:
+ * 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.
+ *
+ * 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
+ * (colliding field names, a nesting depth that overflows the walk, a redaction
+ * budget spent on a thousand secret-shaped leaves), and each of those throws is
+ * guarding content the open posture hands to the model verbatim, secrets
+ * included. An operator who cares more about withholding a secret than about
+ * keeping the session moving sets the knob to `0`.
+ * @param {any} input  parsed hook input, or undefined if parsing threw
+ * @param {unknown} err
+ * @param {(fields: Record<string, unknown>) => void} [emit]
+ * @param {string} [remedy]  what a reader should run; hosts pass their own
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ * @returns {void}
+ */
+export function emitHookFailure(input: any, err: unknown, emit?: (fields: Record<string, unknown>) => void, remedy?: string, env?: NodeJS.ProcessEnv | Record<string, string | undefined>): void;
 /**
  * Run the sanitization pipeline over a tool output and return the contract-
  * shaped verdict fields — `mutated_output` (the shape-matching sanitized value)
@@ -208,7 +230,7 @@ export function judgeSanitizeOutput(event: import("agent-control-plane-core").To
  */
 export function withPostToolUseDefault(input: unknown): unknown;
 /**
- * The hook's CLI: parse → judge → render, with this hook's fail-closed posture.
+ * The hook's CLI: parse → judge → render, under the caller's failure posture.
  * Exported so a bundle entry (which must claim the CLI slot before this module
  * loads) can run the exact same wiring instead of duplicating the onError
  * posture. That entry is also the only place a host's {@link SanitizeExtensions}

package/types/claude-hooks/sanitize-user-prompt.d.mts

@@ -23,18 +23,21 @@ export function judgeSanitizeUserPrompt(event: import("agent-control-plane-core"
  *   strip?: ((s: string) => string) | null,
  *   overrides?: Partial<typeof USER_PROMPT_MESSAGES>,
  *   trace?: import("./lib/trace.mjs").TraceFn,
+ *   env?: NodeJS.ProcessEnv | Record<string, string | undefined>,
  * }} [opts]
  *   `strip` is the ANSI stripper (defaults to the package's stripAnsiFully;
  *   injectable so the fail-closed path is testable); `overrides` are reason
  *   overrides, merged over the defaults so a partial table can never leave a field
  *   unset; `trace` is where engagement is announced, for a host with its own trace
- *   channel (see lib/trace.mjs).
+ *   channel (see lib/trace.mjs); `env` is the failure-posture source (see
+ *   failOpenEnabled), injectable so both postures are testable in-process.
  * @returns {Promise<void>}
  */
 export function main(read: () => Promise<any> | any, write: (chunk: string) => void, opts?: {
     strip?: ((s: string) => string) | null;
     overrides?: Partial<typeof USER_PROMPT_MESSAGES>;
     trace?: import("./lib/trace.mjs").TraceFn;
+    env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
 }): Promise<void>;
 /** @type {typeof import("agent-sanitizer/prompt").classifyPrompt} */
 export let classifyPrompt: typeof import("agent-sanitizer/prompt").classifyPrompt;