agent-sanitizer 2.26.3 → 2.27.0

package/README.md

@@ -58,7 +58,7 @@ the callback you inject for the agent-specific concern; `—` is a pure transfor
 | 5   | `/instructions` | Scan/auto-clean `CLAUDE.md`, `AGENTS.md`, `SKILL.md`, etc., decoding Unicode-tag + zero-width-binary payloads.                                                              | `fs` (direct)               |
 | 6   | `/prompt`       | Classify a prompt pass / note / block on payload-capable invisible/ANSI content (inert escapes get the note).                                                               | —                           |
 | 7   | `/output`       | Run Layers 1–4 over structured tool output, preserving shape. The Layer-5 slot takes a delete-only filter.                                                                  | `redact`, `filterInjection` |
-| 8   | `/rehydrate`    | Re-anchor a model Edit composed from the _sanitized_ view back onto real bytes; deny anything ambiguous or secret-exposing.                                                 | `io`                        |
+| 8   | `/rehydrate`    | Re-anchor a model Edit/Write composed from the _sanitized_ view back onto real bytes; gate MultiEdit on a verified view==disk; deny anything ambiguous or secret-exposing.  | `io`                        |
 | —   | `/view-map`     | Pure offset/text machinery mapping a file's on-disk bytes ↔ the sanitized view (Layer-1 deletions, Layer-4 redactions). No I/O — consumed by `/rehydrate`.                  | —                           |
 
 See [`THREAT-MODEL.md`](./THREAT-MODEL.md) for per-vector detail.
@@ -120,6 +120,25 @@ a single ordered pass, so the bytes a filter can remove are exactly the bytes it
 spans matched in the input — an earlier deletion can never manufacture a match
 for a later span (overlapping spans resolve first-match-wins).
 
+## Secret redaction
+
+Secrets in tool output are redacted **locally**, before the model ever sees
+them. The engine is an injected seam — the plugin wires
+[`detect-secrets`](https://github.com/Yelp/detect-secrets), running entirely
+on-machine; the library bundles no engine. The model reads stable `[REDACTED…]`
+placeholders instead of the values. The write path closes the loop: Edits
+composed against the redacted view are re-anchored onto the real bytes, and
+placeholders in new content resolve back to the real secrets — disk → tool
+input only, never into the model's view. Anything ambiguous is denied rather
+than guessed, the redactor's own map is verified against the file before any
+splice, and a write that would persist placeholder text over a real secret
+asks instead of passing through even when the hook's own machinery fails
+mid-session. The whole layer is opt-in — its denies and asks are friction, so it
+engages only when asked for: set `AGENT_SANITIZER_SECRETS_ENABLED=1` in the
+environment Claude Code runs the hooks with; unset, no redactor runs and no
+placeholders exist.
+Per-vector detail in [`THREAT-MODEL.md`](./THREAT-MODEL.md).
+
 ## What installing entails
 
 Installing the plugin puts four hooks on every session, and this is what they
@@ -136,8 +155,9 @@ buy you:
    walk a command past a deny rule.
 4. Tool output has invisible characters and terminal escapes stripped, hidden
    HTML spliced out with a placeholder, and exfil-shaped URLs flagged.
-5. Secrets in tool output are redacted locally by `detect-secrets` — the engine
-   ships with the plugin and provisions itself on first run, no setup from you.
+5. With `AGENT_SANITIZER_SECRETS_ENABLED=1` set, secrets in tool output are
+   redacted locally by `detect-secrets` — the engine ships with the plugin and
+   provisions itself on first run, no further setup from you.
 6. Edits the model composes against the redacted view are re-anchored onto the
    real bytes on disk, and anything ambiguous is denied rather than guessed.
 7. The costs are a few seconds on the first secret-shaped output, ~200 ms on the
@@ -150,7 +170,10 @@ 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
+prompts, permission asks whose reason names the cause. One carve-out to the
+open default, with secrets enabled: a write-shaped call carrying `[REDACTED…]` placeholder text asks
+instead of passing through when the hook itself is broken, since letting it
+through would overwrite the real secret with the placeholder. 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

package/THREAT-MODEL.md

@@ -284,7 +284,14 @@ RECONSTITUTES during stripping is judged as the sequence it becomes.
 (a harness that gets a shape-mismatched value silently shows the raw output).
 Layer 4 (secret redaction) is an **injected** redactor and is the one
 fail-closed path: a redactor that throws makes the pipeline rethrow, so the
-caller suppresses the output rather than emit an unvetted value. Layer 5 is a
+caller suppresses the output rather than emit an unvetted value. In the Claude
+Code hooks the entire secret layer is **opt-in**: `secretsEnabled()`
+(`claude-hooks/lib/env-config.mjs`) reads `AGENT_SANITIZER_SECRETS_ENABLED=1`,
+and every secret-layer guarantee below — Layer-4 redaction, rehydration, the
+placeholder guards, the placeholder-write carve-out, SessionStart engine
+provisioning — is conditional on that knob being set; unset, no redactor is
+spawned and no placeholders enter the model's view, because the layer's denies
+and asks are friction an operator must ask for. Layer 5 is a
 deliberately thin, safe slot: the injected filter returns **verbatim spans to
 delete** (never replacement text), so even a compromised filter can only remove
 legitimate content—it can never inject bytes into the model’s view. That removal
@@ -334,6 +341,28 @@ are load-bearing and **fail closed**:
   edit would re-run redaction on every `Edit` call and risk false denials on a
   legitimate relabel in a large file. The secret flows disk → tool input only;
   the model’s next view is sanitized again.
+- **Never trust the redactor’s map unverified.** The redactor’s map-mode output
+  is validated before any splice: every pair’s placeholder must occupy the view
+  text at its stated offset, and splicing the originals back must reconstruct
+  the file’s cleaned bytes exactly — out-of-range and overlapping pairs are
+  caught too. A map that fails either proof is **denied outright** — for every
+  tool and hint state, stricter than the honest-unmappable arm — and never
+  thrown into the host’s fail-open posture: unlike an engine reporting it
+  cannot map, a validated-wrong map is affirmative evidence the engine is wrong
+  about where this file’s secrets sit, so neither a splice nor a raw
+  pass-through (the R1 hidden-span oracle) can be vetted against it.
+
+MultiEdit is gated, not rehydrated. MultiEdit applies its edits sequentially,
+each against the file state the previous edit produced, so the span-exact
+view↔disk mapping done for a single Edit has no sound equivalent. It passes
+through only when the file’s sanitized view provably equals disk AND no edit
+carries a `[REDACTED…]` placeholder; every other case — a view that diverges via
+redacted secrets or stripped invisible characters, an unmappable or defective
+redactor map, or placeholder text aimed at a pristine file (the
+foreign-placeholder rule) — is **denied**, with guidance to re-issue the changes
+as single Edit calls, which _are_ rehydrated. The previous full pass-through was
+both a silent clobber (the placeholder persisted over the secret) and a
+character-extraction oracle.
 
 File access and the redactor are injected via `io`; the package performs no I/O
 of its own and bundles no secret engine.
@@ -439,6 +468,24 @@ 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.
 
+One carve-out: when the PreToolUse hook itself fails (redactor daemon down,
+package failed to load, a layer threw) and the call is a **write-shaped tool**
+(Write/Edit/MultiEdit/NotebookEdit) whose input carries the `[REDACTED`
+placeholder prefix, the hook **asks** — fail-closed, human in the loop — instead
+of passing through. With the sanitizer down, rehydration cannot run, so the
+placeholder text would be persisted literally over the real secret on disk: a
+destructive clobber, not a missed scan. Holding these calls is safe because a
+placeholder-bearing write is never the benign availability case the open default
+protects — the model can retry once the sanitizer recovers, or ask the user. The
+check is package-free (a literal-string test on the already-parsed payload), so
+it holds even when the failure IS the missing package. Two accepted gaps: a
+launcher-level failure (no `node`, corrupt bundle) never reaches the check — the
+launcher cannot inspect the payload and always warns — and `Bash` is excluded
+even though shell redirection can also persist placeholder text, because command
+strings mention `[REDACTED` benignly far too often for the ask to hold
+precision. All other faults keep the open default, and
+`AGENT_SANITIZER_FAIL_OPEN=0` behavior is unchanged.
+
 **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

package/claude-hooks/lib/env-config.mjs

@@ -213,6 +213,27 @@ export function extraSecretVars(env = process.env) {
   return tokens;
 }
 
+// The one switch for the whole secret layer (Layer 4). Secret redaction is
+// OPT-IN: it spawns a Python daemon, rewrites the model's view of tool output,
+// and gates the write path (rehydration denies, the placeholder-write
+// carve-out) — machinery whose false positives cost real work, so it engages
+// only when an operator asked for it. Every secret-layer call site consults
+// THIS predicate; a second reading of the variable is the drift channel that
+// would let one hook redact while another passes placeholders through.
+export const SECRETS_ENABLED_ENV = "AGENT_SANITIZER_SECRETS_ENABLED";
+
+/**
+ * True when the operator opted into the secret-redaction layer. `=== "1"`
+ * matches the other public knobs (`AGENT_SANITIZER_*_DISABLED`): any other
+ * value — unset, "true", "yes" — keeps the layer off, so a typo can only fail
+ * toward the default (no secret machinery), never silently enable it.
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ * @returns {boolean}
+ */
+export function secretsEnabled(env = process.env) {
+  return env[SECRETS_ENABLED_ENV] === "1";
+}
+
 /**
  * The env-bound redaction set: the UNION of the inference keys, the curated host
  * credentials, any credential-shaped var present in the environment, the

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

@@ -145,11 +145,15 @@ export function faultPolicy(hook) {
  * recording that the guarded content passed through unsanitized. Non-empty
  * matters — an empty stdout is recorded by Claude Code as a CLEAN run rather
  * than a degraded one, so the posture would give up visibility as well as
- * enforcement.
+ * enforcement. Exported so a policy that declares its own `open` arm for a
+ * carve-out can still route its non-carve-out path through THIS rendering
+ * instead of restating it — a hand-copied body would silently drift the day
+ * this one changes, which is the per-hook re-derivation this module exists to
+ * end.
  * @param {FaultContext} ctx
  * @returns {FaultParts}
  */
-function defaultOpen(ctx) {
+export function defaultOpen(ctx) {
   return { fields: { additionalContext: ctx.openContext } };
 }
 

package/claude-hooks/pretooluse-sanitize.mjs

@@ -39,7 +39,11 @@ import {
   HookEvent,
   PermissionDecision,
 } from "./lib/hook-io.mjs";
-import { registerFaultPolicy, hookFaultOutcome } from "./lib/hook-fault.mjs";
+import {
+  registerFaultPolicy,
+  hookFaultOutcome,
+  defaultOpen,
+} from "./lib/hook-fault.mjs";
 import { runLayerPipeline } from "./lib/layer-pipeline.mjs";
 import { controlPlane, runJudgeCli } from "./lib/control-plane.mjs";
 import {
@@ -54,6 +58,7 @@ import {
   authoredContext,
 } from "./lib/authored-content.mjs";
 import { redactViaDaemon } from "./lib/redactor-client.mjs";
+import { secretsEnabled } from "./lib/env-config.mjs";
 import { withSecretDropGuard } from "./lib/secret-drop-guard.mjs";
 import { placeholderNotice } from "./lib/placeholder-grammar.mjs";
 import { bestEffortTrace, trace, TraceEvent } from "./lib/trace.mjs";
@@ -147,11 +152,24 @@ const redactorIo = {
  * (not an inline default-param arrow) so tests can still inject a fake as the
  * second argument to buildPreToolUseResponse.
  */
-const defaultRehydrate = withSecretDropGuard(
+const guardedRehydrate = withSecretDropGuard(
   (tool, toolInput) => rehydrateRedacted(tool, toolInput, redactorIo),
   redactorIo,
 );
 
+/**
+ * The wired default gates the whole rehydration layer on the secret opt-in:
+ * with secrets off the output hook never inserts placeholders, so there is
+ * nothing to re-anchor — and skipping here (rather than inside the layer)
+ * means an Edit on a plain file never touches the file system twice or spawns
+ * the daemon. Consulted per call, not at module load, so a knob set after the
+ * bundle loads still governs the next tool call.
+ * @param {string} tool
+ * @param {any} toolInput
+ */
+const defaultRehydrate = async (tool, toolInput) =>
+  secretsEnabled() ? guardedRehydrate(tool, toolInput) : null;
+
 /**
  * Trace the response on the way out — "noop" (clean pass-through), "deny",
  * "ask", or "modified" (input rewritten and/or context attached) — and return
@@ -312,7 +330,9 @@ export async function buildPreToolUseResponse(
   // cannot tell a write from a read, so it is context-only — never a verdict
   // (see placeholderNotice). Evaluated on the pipeline's FINAL input, matching
   // what the tool will actually receive.
-  const notice = placeholderNotice(tool, current);
+  // Gated on the secret opt-in like the layer itself: with secrets off,
+  // placeholder-shaped text is ordinary prose and the advisory is noise.
+  const notice = secretsEnabled() ? placeholderNotice(tool, current) : null;
   if (notice !== null) contexts.push(notice);
 
   return emitTraced(
@@ -496,12 +516,60 @@ export function failClosedFields(parsedOk, err, opts = {}) {
   };
 }
 
+// The redaction-placeholder prefix, restated as a literal rather than imported:
+// this check belongs to the FAILURE posture and must work exactly when the
+// agent-sanitizer package (which exports it as DEFAULT_HINT) failed to load.
+// Exported so test/claude-hooks-fail-open.test.mjs can pin the two spellings
+// together with exact equality — a prefix-only behavioral check would keep
+// passing if this literal drifted shorter and the carve-out over-triggered.
+export const REDACTION_HINT = "[REDACTED";
+// The file-editing tools whose input fields ARE the bytes persisted to disk.
+// Deliberately NOT exhaustive over every clobber path: Bash can also write a
+// placeholder to disk (`>`, `tee`, `sed -i`, a heredoc), but command strings
+// mention "[REDACTED" benignly far too often — grepping for it, discussing
+// it — for an ask to hold precision there. That is an accepted gap, named in
+// THREAT-MODEL.md's carve-out paragraph, not a completeness claim.
+const WRITE_SHAPED_TOOLS = new Set([
+  "Write",
+  "Edit",
+  "MultiEdit",
+  "NotebookEdit",
+]);
+
+/**
+ * True when a faulting PreToolUse call is the one case the OPEN posture must
+ * still not pass: a write-shaped tool whose input carries the
+ * redaction-placeholder prefix. Such a placeholder stands for a secret the
+ * sanitizer redacted out of the model's view; with the sanitizer down,
+ * rehydration cannot translate it back, so letting the call through would
+ * persist the literal placeholder text over the real secret on disk — a
+ * destructive clobber, not a missed scan. Package-free by construction (a Set
+ * lookup and a substring test on the already-parsed payload), so it holds when
+ * the failure IS the missing package.
+ * @param {unknown} input raw parsed PreToolUse payload (undefined if unparsed)
+ * @returns {boolean}
+ */
+export function hintedWriteFault(input) {
+  const payload =
+    /** @type {{tool_name?: unknown, tool_input?: unknown} | undefined} */ (
+      input
+    );
+  if (!WRITE_SHAPED_TOOLS.has(/** @type {string} */ (payload?.tool_name)))
+    return false;
+  // A parsed-JSON payload can hold no circular reference, so stringify cannot
+  // throw; `?? null` keeps a missing tool_input from stringifying to undefined.
+  return JSON.stringify(payload?.tool_input ?? null).includes(REDACTION_HINT);
+}
+
 /**
  * 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.
+ * AGENT_SANITIZER_FAIL_OPEN=0. The open default has ONE carve-out, declared in
+ * this hook's fault policy below: a write-shaped call whose input carries a
+ * `[REDACTED…]` placeholder asks instead of passing (see
+ * {@link hintedWriteFault}) — pass `input` so the policy can see it.
  *
  * 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
@@ -512,6 +580,7 @@ export function failClosedFields(parsedOk, err, opts = {}) {
  *   messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>,
  *   hint?: string,
  *   env?: NodeJS.ProcessEnv | Record<string, string | undefined>,
+ *   input?: unknown,
  * }} [opts]
  * @returns {Record<string, unknown>}
  */
@@ -522,16 +591,51 @@ export function hookFailureFields(parsedOk, err, opts = {}) {
       env: opts.env,
       messages: opts.messages,
       hint: opts.hint,
+      input: opts.input,
     }).fields
   );
 }
 
 // This hook's entry in the one posture table (lib/hook-fault.mjs). The OPEN arm
-// is the shared default — a warning context and no verdict — so only the CLOSED
-// verdict, which is this hook's own ask/deny split, is stated here.
+// keeps the shared default — a warning context and no verdict — with ONE
+// carve-out: a write-shaped input carrying a [REDACTED… placeholder asks
+// instead. The open posture trades enforcement for availability on the
+// sanitizer's own breakage, and that trade is sound for a missed SCAN; a
+// placeholder-bearing write is not a scan but a guaranteed clobber — the
+// placeholder would be persisted literally over the secret it stands for (see
+// hintedWriteFault). The ask keeps a human in the loop exactly as the closed
+// posture's clean-parse arm does.
 registerFaultPolicy(HOOK_NAME, {
   event: HookEvent.PRE_TOOL_USE,
   guarded: "tool input",
+  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.
+    // The carve-out itself rides the secret opt-in: with secrets off no
+    // sanitized view ever handed the model a placeholder, so hint-shaped text
+    // in a write is literal prose and holding it would be a false positive.
+    if (!secretsEnabled(ctx.env) || !hintedWriteFault(ctx.input))
+      return defaultOpen(ctx);
+    // parsedOk is hardcoded true (the ASK arm): hintedWriteFault(undefined)
+    // is false, so an unparsed input can never reach this line — reaching it
+    // proves the payload parsed.
+    const closed = failClosedFields(true, ctx.err, {
+      messages: ctx.messages,
+      hint: ctx.hint,
+    });
+    return {
+      fields: {
+        ...closed,
+        permissionDecisionReason:
+          `${closed.permissionDecisionReason} This input would write ` +
+          `${REDACTION_HINT}…] placeholder text, which stands for a redacted ` +
+          `secret the unavailable sanitizer cannot translate back; proceeding ` +
+          `would overwrite the real secret with the placeholder, so the call ` +
+          `is held even under the fail-open posture. Retry once the sanitizer ` +
+          `recovers, or ask the user to make this change.`,
+      },
+    };
+  },
   closed: (ctx) => ({
     fields: failClosedFields(ctx.parsedOk, ctx.err, {
       messages: ctx.messages,
@@ -580,6 +684,7 @@ export async function cliMain(opts = {}) {
           hookFailureFields(input !== undefined, err, {
             messages,
             hint: depLoadHint(err, messages.remedy),
+            input,
           }),
         ),
     },

package/claude-hooks/sanitize-output.mjs

@@ -36,6 +36,7 @@ import { registerFaultPolicy, hookFaultOutcome } from "./lib/hook-fault.mjs";
 import { controlPlane, runJudgeCli } from "./lib/control-plane.mjs";
 import { bestEffortTrace, trace, TraceEvent } from "./lib/trace.mjs";
 import { hasEnvBoundSecret } from "./lib/secret-annotate.mjs";
+import { secretsEnabled } from "./lib/env-config.mjs";
 import {
   persistReveal,
   isRevealRead,
@@ -252,32 +253,36 @@ export async function sanitizeText(
     exfilScan: webIngress,
     sgrCarveOut: !webIngress,
     deadline,
-    // 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 {
-        secrets = await redactSecrets(content, webIngress, deadline);
-      } catch (l4err) {
-        process.stderr.write(
-          `sanitize-output: CRITICAL: secret redaction failed (${errMessage(l4err)}). ` +
-            "This output was never vetted for secrets. Fix the redactor installation.\n",
-        );
-        throw l4err;
-      }
-      if (!secrets) return null;
-      // The note is derived from the PRE-redaction text: the caller's reason for
-      // annotating (which variable, which provenance) is exactly what redaction
-      // is about to remove.
-      const note = ext.redactNote?.(content);
-      return note
-        ? { text: secrets.text, found: secrets.found, note }
-        : { text: secrets.text, found: secrets.found };
-    },
+    // Layer 4 — OPT-IN (secretsEnabled): 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 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: !secretsEnabled()
+      ? undefined
+      : async (/** @type {string} */ content) => {
+          let secrets;
+          try {
+            secrets = await redactSecrets(content, webIngress, deadline);
+          } catch (l4err) {
+            process.stderr.write(
+              `sanitize-output: CRITICAL: secret redaction failed (${errMessage(l4err)}). ` +
+                "This output was never vetted for secrets. Fix the redactor installation.\n",
+            );
+            throw l4err;
+          }
+          if (!secrets) return null;
+          // The note is derived from the PRE-redaction text: the caller's reason for
+          // annotating (which variable, which provenance) is exactly what redaction
+          // is about to remove.
+          const note = ext.redactNote?.(content);
+          return note
+            ? { text: secrets.text, found: secrets.found, note }
+            : { text: secrets.text, found: secrets.found };
+        },
   };
   const seamResult =
     /** @type {{ cleaned: string, warnings: string[], notes?: string[], modified: boolean, sgrNote: boolean, reveal?: string }} */ (
@@ -776,7 +781,11 @@ export async function evaluateToolOutput(input, ext = {}) {
   for (const original of reveals) {
     let stored;
     try {
-      const secrets = await redactSecrets(original, true, deadline);
+      // Same opt-in as the main pass: with secrets off nothing was redacted
+      // out of the primary output either, so the sidecar persists verbatim.
+      const secrets = secretsEnabled()
+        ? await redactSecrets(original, true, deadline)
+        : null;
       stored = secrets ? secrets.text : original;
     } catch {
       // The pre-splice text carries the spliced comment bodies, so a secret
@@ -795,7 +804,11 @@ export async function evaluateToolOutput(input, ext = {}) {
   // secret surfaces, while grep/Bash output quoting placeholders is routine.
   // Reveal sidecars are excluded — their bytes are redacted BEFORE persisting,
   // so placeholder text there is this sanitizer's own.
+  // Gated on the secret opt-in: with the layer off this sanitizer never
+  // inserts placeholders, so placeholder-shaped bytes are ordinary text and
+  // the warning would be pure noise on every doc ABOUT redaction.
   if (
+    secretsEnabled() &&
     input.tool_name === "Read" &&
     !revealRead &&
     containsPlaceholder(toolOutput)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.26.3",
+  "version": "2.27.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/src/rehydrate.mjs

@@ -65,6 +65,7 @@ import {
   makeFileView,
   toUtf16View,
   pairDiskSpans,
+  viewMapDefect,
 } from "./view-map.mjs";
 
 // Cheap gate: every redaction placeholder the canonical redactor emits starts
@@ -488,29 +489,32 @@ async function rehydrateWrite(ti, view, io, hint) {
 }
 
 /**
- * The single MultiEdit refusal: covers both a sanitized view that diverges
+ * The single MultiEdit refusal: covers a sanitized view that diverges
  * from disk (redacted secrets, stripped invisible characters, a lone
- * surrogate) and edits that carry placeholder text over a pristine file —
- * either way the sequential edits cannot be re-anchored, so route the model
- * to the per-call verified path.
+ * surrogate), a redactor map that is unmappable or failed validation, and
+ * edits that carry foreign placeholder text over a pristine file — in every
+ * case the sequential edits cannot be re-anchored, so route the model to the
+ * per-call verified path.
  * @param {string} filePath
  */
 function multiEditDeny(filePath) {
   return {
     deny:
       `the sanitized view of ${filePath} differs from its on-disk bytes ` +
-      `(redacted secrets or stripped invisible characters), or the edits carry ` +
-      `[REDACTED…] placeholder text; MultiEdit's sequential edits cannot be ` +
-      `re-anchored onto the real bytes. Use single Edit calls — each is ` +
-      `rehydrated individually — or ask the user to make this change`,
+      `(redacted secrets, stripped invisible characters, or normalized lone ` +
+      `surrogates), or the edits carry [REDACTED…] placeholder text; ` +
+      `MultiEdit's sequential edits cannot be re-anchored onto the real ` +
+      `bytes. Use single Edit calls — each is rehydrated individually — or ` +
+      `ask the user to make this change`,
   };
 }
 
 /**
  * True when this tool call could need re-anchoring against the target file's
  * sanitized view: any well-formed Edit (the view may differ from disk even
- * without placeholders, via stripped invisible characters), or a Write whose
- * content carries a placeholder.
+ * without placeholders, via stripped invisible characters), any well-formed
+ * MultiEdit (gated on the same grounds), or a Write whose content carries a
+ * placeholder.
  * @param {string} tool
  * @param {any} ti
  * @param {string} hint
@@ -521,8 +525,6 @@ function isCandidate(tool, ti, hint) {
     return (
       typeof ti.old_string === "string" && typeof ti.new_string === "string"
     );
-  if (tool === "Write")
-    return typeof ti.content === "string" && ti.content.includes(hint);
   // MultiEdit applies its edits SEQUENTIALLY, each against the result of the
   // previous, so the span machinery below (which maps one old_string against
   // one static view) cannot re-anchor it. It is still a candidate: on a
@@ -541,16 +543,20 @@ function isCandidate(tool, ti, hint) {
           typeof edit?.new_string === "string",
       )
     );
+  if (tool === "Write")
+    return typeof ti.content === "string" && ti.content.includes(hint);
   return false;
 }
 
 /**
  * Re-anchor an Edit/Write input composed from a sanitized file view back onto
- * the on-disk bytes (secrets rehydrated, stripped invisible runs re-attached).
- * Returns the rewritten input plus a model-facing context line, a deny with an
- * instructive reason when the input is unresolvable or would expose a secret,
- * or null when there is nothing to do. Throws only on internal error (the
- * caller fails closed).
+ * the on-disk bytes (secrets rehydrated, stripped invisible runs re-attached),
+ * and gate MultiEdit (pass-through only on a verified view==disk with no
+ * placeholder in any edit; denied otherwise — see the module doc). Returns the
+ * rewritten input plus a model-facing context line, a deny with an instructive
+ * reason when the input is unresolvable or would expose a secret, or null when
+ * there is nothing to do. Throws only on internal error (the caller fails
+ * closed).
  *
  * `io` is the injected I/O (file read + redactor map/plain). `hint` is the
  * redaction-placeholder prefix (defaults to {@link DEFAULT_HINT}); override it
@@ -599,21 +605,25 @@ export async function rehydrateRedacted(
     // promises Node-shaped read failures (a real `readFile`'s throw), so
     // narrow once here rather than re-deriving the cast at every use below.
     const nodeErr = /** @type {NodeJS.ErrnoException} */ (err);
-    // ENOENT (missing target): an Edit fails on its own (nothing to
-    // re-anchor), so pass through. A Write, though, CREATES the file with its
-    // content verbatim — and a Write candidate is always hinted (isCandidate
-    // requires the hint prefix), so its placeholder stands for a secret that
-    // does NOT exist on this new path. R4: persisting "[REDACTED…]" literally
-    // there is the same cross-file/stale-placeholder mistake a same-file Write
-    // is denied for; refuse with the same guidance rather than write the
-    // placeholder text as a real value.
-    // A hinted MultiEdit on a missing path is the same mistake: its first edit
-    // (empty old_string) CREATES the file, so a placeholder in any edit would
-    // be persisted verbatim as the new file's content — deny like the Write.
-    // A hint-free MultiEdit fails on its own (nothing to create placeholder
-    // text from), so it passes through like an Edit.
+    // ENOENT (missing target): a call that cannot CREATE the file fails on
+    // its own (nothing to re-anchor), so pass through — a hint-free call, an
+    // Edit whose old_string is non-empty, or a MultiEdit whose FIRST edit's
+    // old_string is non-empty (only an empty first old_string is the create
+    // form; anything else errors not-found in the real tool). But any call
+    // that WOULD create the file with hinted content — a Write (always
+    // hinted; isCandidate requires the prefix), a hinted Edit-create, or a
+    // hinted MultiEdit-create — persists its placeholder verbatim, standing
+    // for a secret that does NOT exist on this new path. R4: that is the same
+    // cross-file/stale-placeholder mistake a same-file Write is denied for;
+    // refuse with the same guidance rather than write the placeholder text as
+    // a real value.
     if (nodeErr?.code === "ENOENT") {
-      if (tool === "Edit" || (tool === "MultiEdit" && !hinted)) return null;
+      const creates =
+        tool === "Write" ||
+        (tool === "Edit"
+          ? toolInput.old_string === ""
+          : toolInput.edits[0].old_string === "");
+      if (!hinted || !creates) return null;
       return {
         deny:
           `${toolInput.file_path} does not exist, so the ${hint}…] placeholder in the ` +
@@ -680,9 +690,48 @@ export async function rehydrateRedacted(
   // already-converted object and get converted twice, so the same input would
   // yield a different verdict on the second call. The space brand is what makes
   // that second conversion throw rather than silently shift; see toUtf16View.
-  const view = toUtf16View(
-    makeFileView(mapped.text, mapped.pairs, "codePoint"),
-  );
+  //
+  // The map is TRUSTED by every splice below, and it came from the injected
+  // redactor — the one component with a real defect rate. A wrong map
+  // (mis-ordered or out-of-range pairs, a placeholder not at its stated
+  // offset, originals that do not splice back to the file's bytes) would
+  // anchor an edit onto the WRONG disk bytes and corrupt the file. Verify it
+  // before acting: construction re-checks range/ordering (the throws in
+  // assertPairsOrdered and pairsToUtf16), viewMapDefect proves the view
+  // reconstructs `cleaned` exactly. A defective map DENIES for every tool and
+  // hint state, and is deliberately NOT allowed to throw out of this module: a
+  // throw lands in the host's failure posture, whose shipped default is fail
+  // OPEN, i.e. the unsanitized placeholder write this module exists to prevent.
+  let view = null;
+  let mapDefect = null;
+  try {
+    view = toUtf16View(makeFileView(mapped.text, mapped.pairs, "codePoint"));
+  } catch (err) {
+    mapDefect = `the redactor's map violates its contract (${/** @type {Error} */ (err).message})`;
+  }
+  if (view !== null) {
+    const defect = viewMapDefect(cleaned, view);
+    if (defect !== null)
+      mapDefect = `the redactor's map is inconsistent with the file's bytes (${defect})`;
+  }
+  if (view === null || mapDefect !== null) {
+    // STRICTER than the unmappable arm above, on purpose: unmappable is an
+    // engine honestly reporting it cannot map, so an unhinted Edit keeps its
+    // resolver-free pass-through; a map that FAILED VALIDATION is affirmative
+    // evidence the engine is wrong about where this file's secrets sit.
+    // Reaching this line at all means the fast pass-through did not fire — the
+    // file provably holds redacted content or diverges from its view — so an
+    // unhinted pass-through here would hand the real Edit bytes inside spans
+    // nothing can vet (the R1 hidden-span oracle). Deny everything until the
+    // redactor is fixed.
+    if (tool === "MultiEdit") return multiEditDeny(toolInput.file_path);
+    return {
+      deny:
+        `cannot safely edit ${toolInput.file_path}: ${mapDefect}; the file holds ` +
+        `redacted content whose location cannot be trusted, so no edit can be ` +
+        `verified. Retry later, or ask the user to make this change`,
+    };
+  }
   // View identical to disk: any placeholders in an Edit's old_string are
   // literal text, so there is nothing to re-anchor. `cleaned === content` also
   // rules out a lone-surrogate-only divergence (view.pairs/deletions alone
@@ -694,19 +743,33 @@ export async function rehydrateRedacted(
   // rehydrateWrite's cross-file deny; a MultiEdit to the MultiEdit deny below
   // — without this a hinted MultiEdit on a pristine file silently persists
   // the foreign placeholder the byte-identical Write is denied for.
-  if (
-    view.pairs.length === 0 &&
-    deletions.length === 0 &&
-    cleaned === content &&
-    (tool === "Edit" || !hinted)
-  )
+  const viewEqualsDisk =
+    view.pairs.length === 0 && deletions.length === 0 && cleaned === content;
+  // Precision refinement for a hinted MultiEdit on that PRISTINE file: a
+  // hint token that already exists verbatim in the file is LITERAL prose
+  // (this repo's own docs carry "[REDACTED…" text), not a placeholder — the
+  // same whitelist foreignPlaceholders applies for a Write. Only new_string
+  // needs vetting: it is the sole field that persists bytes, while an
+  // old_string that is not literal file text simply fails the real tool's
+  // exact-match and persists nothing. The file holds no secrets here (the
+  // verified-empty map above proves it), so a fully-literal MultiEdit cannot
+  // clobber one; pass it through instead of false-denying documentation
+  // edits.
+  const multiEditLiteralHint =
+    tool === "MultiEdit" &&
+    viewEqualsDisk &&
+    toolInput.edits.every(
+      (/** @type {{new_string: string}} */ edit) =>
+        foreignPlaceholders(edit.new_string, hint, view.text, []).length === 0,
+    );
+  if (viewEqualsDisk && (tool === "Edit" || !hinted || multiEditLiteralHint))
     return null;
 
   // MultiEdit reaches here when the view diverges from disk (redacted
   // secrets, stripped runs, a lone surrogate) or when its edits carry
-  // placeholder text: its sequential edits cannot be re-anchored one-by-one
-  // against a static view, so fail closed with the escape hatch that lands in
-  // the fully-verified path.
+  // foreign placeholder text: its sequential edits cannot be re-anchored
+  // one-by-one against a static view, so fail closed with the escape hatch
+  // that lands in the fully-verified path.
   if (tool === "MultiEdit") return multiEditDeny(toolInput.file_path);
   return tool === "Edit"
     ? rehydrateEdit(

package/src/view-map.mjs

@@ -491,6 +491,41 @@ export function pairDiskSpans(view, deletions) {
   });
 }
 
+/**
+ * Defect in a redactor map relative to the Layer-1-cleaned text it claims to
+ * describe, or null when the map is sound. Two proofs, both required before
+ * any splice may trust the map: every pair's placeholder must actually occupy
+ * `view.text` at its stated offset, and splicing each pair's original back
+ * over its placeholder must reproduce `cleaned` byte-for-byte. The redactor is
+ * an INJECTED engine with a real defect rate, and the offsets it emits anchor
+ * edits onto disk bytes — a map failing either proof would splice at the wrong
+ * position and corrupt the file, so the caller must treat it as unmappable
+ * rather than act on it. Defect messages name placeholders and offsets only,
+ * never an original (secret) byte.
+ * Indexes `view.text` by `pair.start` directly, so it requires the UTF-16
+ * carrier — the same one every splice consumes.
+ * @param {string} cleaned Layer-1-cleaned file text the map was derived from
+ * @param {FileView<"utf16">} view
+ * @returns {string | null}
+ */
+export function viewMapDefect(cleaned, view) {
+  assertFileView(view, "utf16", "viewMapDefect");
+  for (const pair of view.pairs)
+    if (!view.text.startsWith(pair.placeholder, pair.start))
+      return (
+        `the map places placeholder ${JSON.stringify(pair.placeholder)} at view ` +
+        `offset ${pair.start}, but the view text there differs`
+      );
+  const rebuilt = spliceOrdered(
+    view.text,
+    view.pairs.map((pair) => ({ text: pair.placeholder, index: pair.start })),
+    (_match, i) => view.pairs[i].original,
+  ).text;
+  return rebuilt === cleaned
+    ? null
+    : "substituting the mapped secrets back over their placeholders does not reconstruct the file";
+}
+
 /**
  * Substitute the placeholders in a model-authored new_string with the secrets
  * they stand for. Resolution, strictest first: if the new placeholder

package/types/claude-hooks/lib/env-config.d.mts

@@ -58,6 +58,15 @@ export function dynamicSecretVars(env?: Record<string, string | undefined>): str
  * @returns {string[]}
  */
 export function extraSecretVars(env?: Record<string, string | undefined>): string[];
+/**
+ * True when the operator opted into the secret-redaction layer. `=== "1"`
+ * matches the other public knobs (`AGENT_SANITIZER_*_DISABLED`): any other
+ * value — unset, "true", "yes" — keeps the layer off, so a typo can only fail
+ * toward the default (no secret machinery), never silently enable it.
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ * @returns {boolean}
+ */
+export function secretsEnabled(env?: NodeJS.ProcessEnv | Record<string, string | undefined>): boolean;
 /**
  * The env-bound redaction set: the UNION of the inference keys, the curated host
  * credentials, any credential-shaped var present in the environment, the
@@ -69,3 +78,4 @@ export function extraSecretVars(env?: Record<string, string | undefined>): strin
  * @returns {string[]}
  */
 export function envBoundSecretVars(env?: Record<string, string | undefined>): string[];
+export const SECRETS_ENABLED_ENV: "AGENT_SANITIZER_SECRETS_ENABLED";

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

@@ -15,6 +15,20 @@ export function registerFaultPolicy(hook: string, policy: FaultPolicy): void;
  * @returns {FaultPolicy}
  */
 export function faultPolicy(hook: string): FaultPolicy;
+/**
+ * The default OPEN rendering: no verdict, and a non-empty `additionalContext`
+ * recording that the guarded content passed through unsanitized. Non-empty
+ * matters — an empty stdout is recorded by Claude Code as a CLEAN run rather
+ * than a degraded one, so the posture would give up visibility as well as
+ * enforcement. Exported so a policy that declares its own `open` arm for a
+ * carve-out can still route its non-carve-out path through THIS rendering
+ * instead of restating it — a hand-copied body would silently drift the day
+ * this one changes, which is the per-hook re-derivation this module exists to
+ * end.
+ * @param {FaultContext} ctx
+ * @returns {FaultParts}
+ */
+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

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

@@ -88,12 +88,29 @@ export function failClosedFields(parsedOk: boolean, err: unknown, opts?: {
     messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>;
     hint?: string;
 }): Record<string, unknown>;
+/**
+ * True when a faulting PreToolUse call is the one case the OPEN posture must
+ * still not pass: a write-shaped tool whose input carries the
+ * redaction-placeholder prefix. Such a placeholder stands for a secret the
+ * sanitizer redacted out of the model's view; with the sanitizer down,
+ * rehydration cannot translate it back, so letting the call through would
+ * persist the literal placeholder text over the real secret on disk — a
+ * destructive clobber, not a missed scan. Package-free by construction (a Set
+ * lookup and a substring test on the already-parsed payload), so it holds when
+ * the failure IS the missing package.
+ * @param {unknown} input raw parsed PreToolUse payload (undefined if unparsed)
+ * @returns {boolean}
+ */
+export function hintedWriteFault(input: unknown): boolean;
 /**
  * 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.
+ * AGENT_SANITIZER_FAIL_OPEN=0. The open default has ONE carve-out, declared in
+ * this hook's fault policy below: a write-shaped call whose input carries a
+ * `[REDACTED…]` placeholder asks instead of passing (see
+ * {@link hintedWriteFault}) — pass `input` so the policy can see it.
  *
  * 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
@@ -104,6 +121,7 @@ export function failClosedFields(parsedOk: boolean, err: unknown, opts?: {
  *   messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>,
  *   hint?: string,
  *   env?: NodeJS.ProcessEnv | Record<string, string | undefined>,
+ *   input?: unknown,
  * }} [opts]
  * @returns {Record<string, unknown>}
  */
@@ -111,6 +129,7 @@ export function hookFailureFields(parsedOk: boolean, err: unknown, opts?: {
     messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>;
     hint?: string;
     env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+    input?: unknown;
 }): Record<string, unknown>;
 /**
  * The hook's CLI: parse → judge → render, under the caller's failure posture.
@@ -155,6 +174,7 @@ export const PRE_TOOL_USE_MESSAGES: Readonly<{
     unparsable: (cause: string) => string;
     remedy: string;
 }>;
+export const REDACTION_HINT: "[REDACTED";
 /**
  * A host-supplied deny gate: given the PreToolUse input, the reason this call
  * must be blocked, or null to let the pipeline continue. Hosts use these for

package/types/rehydrate.d.mts

@@ -1,10 +1,12 @@
 /**
  * Re-anchor an Edit/Write input composed from a sanitized file view back onto
- * the on-disk bytes (secrets rehydrated, stripped invisible runs re-attached).
- * Returns the rewritten input plus a model-facing context line, a deny with an
- * instructive reason when the input is unresolvable or would expose a secret,
- * or null when there is nothing to do. Throws only on internal error (the
- * caller fails closed).
+ * the on-disk bytes (secrets rehydrated, stripped invisible runs re-attached),
+ * and gate MultiEdit (pass-through only on a verified view==disk with no
+ * placeholder in any edit; denied otherwise — see the module doc). Returns the
+ * rewritten input plus a model-facing context line, a deny with an instructive
+ * reason when the input is unresolvable or would expose a secret, or null when
+ * there is nothing to do. Throws only on internal error (the caller fails
+ * closed).
  *
  * `io` is the injected I/O (file read + redactor map/plain). `hint` is the
  * redaction-placeholder prefix (defaults to {@link DEFAULT_HINT}); override it

package/types/view-map.d.mts

@@ -216,6 +216,24 @@ export function pairDiskSpans(view: FileView<"utf16">, deletions: {
     start: number;
     end: number;
 }[];
+/**
+ * Defect in a redactor map relative to the Layer-1-cleaned text it claims to
+ * describe, or null when the map is sound. Two proofs, both required before
+ * any splice may trust the map: every pair's placeholder must actually occupy
+ * `view.text` at its stated offset, and splicing each pair's original back
+ * over its placeholder must reproduce `cleaned` byte-for-byte. The redactor is
+ * an INJECTED engine with a real defect rate, and the offsets it emits anchor
+ * edits onto disk bytes — a map failing either proof would splice at the wrong
+ * position and corrupt the file, so the caller must treat it as unmappable
+ * rather than act on it. Defect messages name placeholders and offsets only,
+ * never an original (secret) byte.
+ * Indexes `view.text` by `pair.start` directly, so it requires the UTF-16
+ * carrier — the same one every splice consumes.
+ * @param {string} cleaned Layer-1-cleaned file text the map was derived from
+ * @param {FileView<"utf16">} view
+ * @returns {string | null}
+ */
+export function viewMapDefect(cleaned: string, view: FileView<"utf16">): string | null;
 /**
  * Substitute the placeholders in a model-authored new_string with the secrets
  * they stand for. Resolution, strictest first: if the new placeholder