agent-sanitizer 2.21.0 → 2.22.0

package/THREAT-MODEL.md

@@ -232,6 +232,56 @@ 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.
 
+`MultiEdit` is a rehydration candidate but never re-anchored: its edits apply
+sequentially, each against the result of the previous, which the span machinery
+(one `old_string` against one static view) cannot model. A MultiEdit against a
+file whose view equals disk passes through untouched (the common case); one
+against a divergent file is **denied** with use-single-Edit guidance — an
+unguarded pass-through there would be both a silent clobber and the same
+extraction oracle the Edit path's hidden-span rule closes.
+
+## Placeholder-clobber guards (hooks layer)
+
+Rehydration re-anchors only Edit/Write, so every other write path — a shell
+heredoc, `sed -i`/`tee`, an MCP file tool — persists a copied `[REDACTED…]`
+placeholder literally, destroying the secret it stands for; and a Write that
+simply **drops** a secret line never carries a placeholder at all. The Claude
+hooks close these around the package's core, favoring precision (a false
+positive costs a sentence of context, never a mangled input):
+
+- **Grammar, not prefix.** Detection matches the exact placeholder language
+  (`claude-hooks/lib/placeholder-grammar.mjs`, mirrored from the Python
+  producer `placeholders.py` and pinned to it by a contract test), never the
+  bare `[REDACTED` prefix — `grep "\[REDACTED"` and `[REDACTED…]` prose are
+  not placeholders. It lives in the hooks layer, not the engine, so the
+  plugin's pinned-engine bundle ships it immediately.
+- **Doctrine at redaction time.** The Layer-4 warning that introduces
+  placeholders into the model's view now states that they rehydrate only via
+  Edit/Write — removing the information asymmetry that made the shell
+  route-around an honest mistake.
+- **Advisory on non-rehydrated tools (context-only, never a verdict).** A
+  Bash/MCP/unknown-tool input carrying a placeholder gets one PreToolUse
+  context line explaining the hazard. It cannot tell a write from a read, so
+  it never blocks.
+- **On-disk tripwire (warning-only).** A `Read` whose RAW bytes — before this
+  session's redaction — already contain placeholder text warns that an earlier
+  write may have clobbered a secret. Detection rides the read, the one choke
+  point every write path (including other agents) eventually crosses; reveal
+  sidecars are excluded, since their bytes are redacted before persisting.
+- **Clobber-by-omission confirm (`lib/secret-drop-guard.mjs`).** A Write to an
+  existing, **git-untracked** file (no git recovery path — `.env` and its kin,
+  or a file outside any repository) whose redacted secrets vanish from the
+  final, post-rehydration content is denied once with the reason; re-issuing
+  the identical Write confirms and passes. The confirmation is the model's
+  deliberate retry — never a human permission prompt — held as a
+  consumed-on-use, TTL-bounded sentinel (keyed to path + content + the dropped
+  values) via the same squat-resistant `$TMPDIR` helpers as the invisible-char
+  gate. Tracked files, secret-free files, failed git probes and unmappable
+  views all skip the guard (fail open). "Tracked" approximates "recoverable":
+  an uncommitted secret line on a tracked file is an accepted gap — the
+  committed content survives, and probing index-vs-worktree state would trade
+  precision for recall.
+
 ## Failure posture (`AGENT_SANITIZER_FAIL_OPEN`)
 
 Installed as Claude Code hooks, these fail **open**: a hook that could not

package/claude-hooks/lib/invisible-alert.mjs

@@ -31,7 +31,8 @@ const { applyLayer1 } = /** @type {typeof import("agent-sanitizer")} */ (
 /** The project the hooks are guarding; the alert paths are keyed to it. */
 export const PROJECT_DIR = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 
-const PROJECT_HASH = createHash("sha256")
+/** Short project digest keying this project's $TMPDIR marker names. */
+export const PROJECT_HASH = createHash("sha256")
   .update(PROJECT_DIR)
   .digest("hex")
   .slice(0, 8);

package/claude-hooks/lib/placeholder-grammar.mjs

@@ -0,0 +1,85 @@
+/**
+ * The redaction-placeholder grammar, mirrored from the single producer in
+ * python/agent_sanitizer/secrets/placeholders.py (PLACEHOLDER_LABEL_CHARS /
+ * PLACEHOLDER_RE there), plus the advisory for placeholder text in tool inputs
+ * rehydration cannot re-anchor.
+ *
+ * This lives in the HOOKS layer, not the engine (`src/`), deliberately: the
+ * plugin bundle inlines the hook sources from this repo but resolves the
+ * engine from the pinned registry release, so an engine export the pin lacks
+ * is undefined in the shipped bundle. The grammar's consumers (the PreToolUse
+ * advisory, the PostToolUse on-disk tripwire, the drop guard's deny prose) are
+ * all hooks, so defining it here keeps the shipped bundle and the source tree
+ * on one implementation. test/placeholder-guards.test.mjs pins these constants
+ * against the Python source, so an edit to either side that forgets the other
+ * fails CI rather than letting the two parsers drift.
+ */
+
+export const PLACEHOLDER_LABEL_CHARS = "A-Za-z0-9 ()._-";
+const PLACEHOLDER_LABEL_MAX_LEN = 64;
+
+/**
+ * Matches exactly the placeholder text the canonical redactor can emit:
+ * `[REDACTED]` or `[REDACTED: <label>]`. Detection sites use this — never a
+ * bare `[REDACTED` prefix — so hint-prefixed prose (`[REDACTED…]`,
+ * `grep "\[REDACTED"`) is not mistaken for a placeholder.
+ */
+export const PLACEHOLDER_RE = new RegExp(
+  `\\[REDACTED(?:: [${PLACEHOLDER_LABEL_CHARS}]{1,${PLACEHOLDER_LABEL_MAX_LEN}})?\\]`,
+);
+
+// Tools whose inputs the rehydration layer itself resolves (or, for
+// NotebookEdit, refuses with guidance). placeholderNotice stays silent on
+// these: their placeholder handling is a verdict, not a note.
+const REHYDRATED_TOOLS = new Set([
+  "Edit",
+  "Write",
+  "MultiEdit",
+  "NotebookEdit",
+]);
+
+/**
+ * Depth-capped walk: does any string in `value` carry placeholder-shaped text?
+ * The cap fails OPEN (deeper content is unseen) — every caller feeds a
+ * context-only advisory, so a miss costs one line, never a mangled input.
+ * @param {unknown} value
+ * @param {number} [depth]
+ * @returns {boolean}
+ */
+export function containsPlaceholder(value, depth = 0) {
+  if (depth > 32) return false;
+  if (typeof value === "string") return PLACEHOLDER_RE.test(value);
+  if (Array.isArray(value))
+    return value.some((item) => containsPlaceholder(item, depth + 1));
+  if (value !== null && typeof value === "object")
+    return Object.values(value).some((item) =>
+      containsPlaceholder(item, depth + 1),
+    );
+  return false;
+}
+
+/**
+ * Advisory context for a tool call OUTSIDE the rehydrated set (Bash, MCP
+ * tools, anything unknown) whose input carries placeholder-shaped text, or
+ * null. Rehydration only re-anchors Edit/Write; every other write path — a
+ * shell heredoc, `sed -i`, an MCP file tool — persists the literal placeholder
+ * and destroys the secret it stands for. This cannot tell a write from a read
+ * (`grep` for a placeholder is legitimate), so it is deliberately a NOTE, not
+ * a verdict: a false positive costs one sentence of context, never a blocked
+ * call or a mangled input.
+ * @param {string} tool
+ * @param {unknown} toolInput
+ * @returns {string | null}
+ */
+export function placeholderNotice(tool, toolInput) {
+  if (REHYDRATED_TOOLS.has(tool)) return null;
+  if (!containsPlaceholder(toolInput)) return null;
+  return (
+    "This tool call carries [REDACTED…] placeholder text, which stands for a " +
+    "secret hidden from your view. Placeholders are rehydrated to the real " +
+    "secret only for Edit/Write on the file that owns them; any other write " +
+    "path (shell redirection, sed/tee, MCP file tools) persists the literal " +
+    "placeholder and destroys the secret. Use Edit or Write for changes to " +
+    "that file, or ask the user."
+  );
+}

package/claude-hooks/lib/secret-drop-guard.mjs

@@ -0,0 +1,227 @@
+/**
+ * Clobber-by-omission guard for whole-file Writes.
+ *
+ * Rehydration (agent-sanitizer/rehydrate) only engages when a Write's content
+ * carries a placeholder; a Write that REGENERATES a secret-bearing file and
+ * simply drops the secret line (reworded to `API_KEY=<your-key-here>`, or
+ * omitted) never enters that layer, and the real secret is silently destroyed.
+ * "Tracked by git" is used as an approximation of "recoverable": a tracked
+ * file's committed content survives the Write, so the guard stays out of the
+ * way — even though an uncommitted secret line on a tracked file is still
+ * lost (accepted: precision over recall). For an UNTRACKED file — `.env` and
+ * its kin are gitignored precisely because they hold secrets, and files
+ * outside any repository count too — there is no git recovery, so the first
+ * such Write is denied with an instructive reason and the model confirms by
+ * re-issuing the exact same call: a deliberate retry, never a human
+ * permission prompt.
+ *
+ * The confirm state is a presence sentinel keyed to a fingerprint of
+ * (file_path, content, dropped secret values) under $TMPDIR, written and read
+ * with the same squat-resistant helpers the invisible-char gate uses
+ * (markerIsTrusted / writeSentinelFile), consumed on use, and expired after
+ * {@link CONFIRM_TTL_MS}, so one confirmation approves exactly one prompt
+ * Write — never a stale or standing auto-approval.
+ *
+ * Fail-open posture (per the package's precision-over-recall doctrine): a
+ * failed git probe, an unmappable redaction view, or a secret-free file all
+ * skip the guard — a false denial here blocks legitimate work, while a false
+ * pass costs only what today's behavior already allows.
+ */
+import { createHash } from "node:crypto";
+import { lstatSync, unlinkSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { lazyImport, markerIsTrusted, writeSentinelFile } from "./hook-io.mjs";
+import { PROJECT_HASH } from "./invisible-alert.mjs";
+
+// Layer-1 view primitives, bound via lazyImport (see its doc for the fail-OPEN
+// hazard of a bare static npm import): a load failure leaves these undefined,
+// so the guard's use throws into the hook's posture-managed catch.
+const { applyLayer1, LONE_SURROGATE_RE } =
+  /** @type {typeof import("agent-sanitizer")} */ (
+    await lazyImport("agent-sanitizer")
+  );
+
+/** A confirm sentinel older than this is stale, not a confirmation. */
+export const CONFIRM_TTL_MS = 10 * 60_000;
+
+/**
+ * Fingerprint of one exact drop: same path, same new bytes, same set of
+ * secret values being removed. The model confirms by re-issuing the identical
+ * call, so the sentinel must match nothing broader — including the dropped
+ * values themselves: if the file's secrets change between the deny and the
+ * retry, the retry is dropping something the model was never warned about,
+ * and must be re-denied.
+ * @param {string} filePath
+ * @param {string} content
+ * @param {string[]} [dropped] the secret values the Write would remove
+ * @returns {string}
+ */
+export function dropFingerprint(filePath, content, dropped = []) {
+  const digest = createHash("sha256").update(filePath).update("\0");
+  digest.update(content);
+  for (const secret of dropped) digest.update("\0").update(secret);
+  return digest.digest("hex").slice(0, 32);
+}
+
+/**
+ * The confirm sentinel's path for one fingerprint. Predictable and
+ * world-visible like the alert markers, hence the markerIsTrusted read.
+ * @param {string} fingerprint
+ * @returns {string}
+ */
+export function confirmMarkerPath(fingerprint) {
+  return join(tmpdir(), `.claude-secret-drop-${PROJECT_HASH}-${fingerprint}`);
+}
+
+/**
+ * Whether git tracks `filePath`. Exit 0 is tracked; exit 1 (untracked) and 128
+ * (not a repository) both mean "no git recovery exists", which is what the
+ * guard actually cares about. A spawn-level failure (no git binary) means we
+ * cannot tell — report tracked so the guard skips (fail open) rather than
+ * denying on missing tooling.
+ * @param {string} filePath
+ * @param {typeof spawnSync} [spawn]
+ * @returns {boolean}
+ */
+export function gitTracked(filePath, spawn = spawnSync) {
+  const res = spawn("git", ["ls-files", "--error-unmatch", "--", filePath], {
+    cwd: dirname(filePath),
+    stdio: "ignore",
+  });
+  if (res.error) return true;
+  return res.status === 0;
+}
+
+/**
+ * @param {number} count
+ * @param {string} filePath
+ * @returns {string}
+ */
+function dropDeny(count, filePath) {
+  return (
+    `this Write removes ${count} redacted secret value(s) from ${filePath}, and the ` +
+    `file is not tracked by git, so the secrets may be unrecoverable. If removing ` +
+    `them is intended, re-issue this exact Write to confirm; otherwise keep each ` +
+    `[REDACTED…] placeholder (or its secret's line) in the new content`
+  );
+}
+
+/**
+ * Deny a first-time Write that would drop a redacted secret from an untracked
+ * file, or null to let it pass. `toolInput` is the FINAL Write input — after
+ * rehydration substituted any placeholders — so a preserved secret shows up as
+ * its real value in `content`. `io` is the rehydrate-shaped I/O bag (readFile /
+ * redact / redactMap). Injectable seams: `isTracked` (the git probe),
+ * `confirmSeen`/`recordConfirm` (the sentinel state).
+ * @param {{file_path?: unknown, content?: unknown}} toolInput
+ * @param {import("agent-sanitizer/rehydrate").RehydrateIo} io
+ * @param {{
+ *   isTracked?: (filePath: string) => boolean,
+ *   confirmSeen?: (fingerprint: string) => boolean,
+ *   recordConfirm?: (fingerprint: string) => void,
+ * }} [opts]
+ * @returns {Promise<{deny: string} | null>}
+ */
+export async function secretDropGuard(toolInput, io, opts = {}) {
+  const {
+    isTracked = gitTracked,
+    confirmSeen = consumeConfirm,
+    recordConfirm = (fingerprint) =>
+      writeSentinelFile(confirmMarkerPath(fingerprint)),
+  } = opts;
+  const { file_path: filePath, content } = toolInput ?? {};
+  if (typeof filePath !== "string" || typeof content !== "string") return null;
+
+  let disk;
+  try {
+    disk = io.readFile(filePath);
+  } catch (err) {
+    // ENOENT: the Write CREATES the file — nothing on disk to drop, and the
+    // hinted-creation case is already rehydration's deny. Any other read
+    // failure propagates: the Write itself will hit the same error, and this
+    // guard must not convert an unexpected failure into a silent pass.
+    if (/** @type {NodeJS.ErrnoException} */ (err)?.code === "ENOENT")
+      return null;
+    throw err;
+  }
+  if (isTracked(filePath)) return null;
+  const cleaned = applyLayer1(disk).cleaned.replace(
+    LONE_SURROGATE_RE,
+    "\uFFFD",
+  );
+  // Cheap secrets-present probe: null exactly when the file holds no secrets —
+  // the overwhelmingly common case pays one daemon round-trip and no map.
+  if ((await io.redact(cleaned)) === null) return null;
+  const view = await io.redactMap(cleaned);
+  // Unmappable: cannot resolve WHICH values the file holds, so the drop set is
+  // unknowable — skip rather than deny on ambiguity (rehydration already
+  // denies the hinted calls this state actually endangers).
+  if ("unmappable" in view) return null;
+  const dropped = [...new Set(view.pairs.map((pair) => pair.original))].filter(
+    (secret) => !content.includes(secret),
+  );
+  if (dropped.length === 0) return null;
+
+  const fingerprint = dropFingerprint(filePath, content, dropped);
+  if (confirmSeen(fingerprint)) return null;
+  recordConfirm(fingerprint);
+  return { deny: dropDeny(dropped.length, filePath) };
+}
+
+/**
+ * Compose a Layer-4 rehydrator with this guard: for a Write the rehydrator
+ * did not deny, run the guard on the FINAL content — after any placeholder
+ * substitution — so a rehydrated secret counts as preserved and only a
+ * genuinely dropped one can trip it. A rehydrate deny short-circuits (the
+ * guard never runs), non-Write tools skip the guard entirely, and a guard
+ * deny wins over a pass/rewrite result.
+ * @typedef {{updatedInput: any, context: string} | {deny: string} | null} RehydrateResult
+ * @param {(tool: string, toolInput: any) => Promise<RehydrateResult>} rehydrate
+ * @param {import("agent-sanitizer/rehydrate").RehydrateIo} io
+ * @param {typeof secretDropGuard} [guard]
+ * @returns {(tool: string, toolInput: any) => Promise<RehydrateResult>}
+ */
+export function withSecretDropGuard(rehydrate, io, guard = secretDropGuard) {
+  return async (tool, toolInput) => {
+    const rehydrated = await rehydrate(tool, toolInput);
+    if (tool !== "Write" || (rehydrated !== null && "deny" in rehydrated))
+      return rehydrated;
+    const finalInput =
+      rehydrated === null ? toolInput : rehydrated.updatedInput;
+    const drop = await guard(finalInput, io);
+    return drop ?? rehydrated;
+  };
+}
+
+/**
+ * True when a trusted, fresh confirm sentinel exists for `fingerprint`,
+ * consuming it so one confirmation approves exactly one Write. A sentinel
+ * older than {@link CONFIRM_TTL_MS} is stale — an abandoned deny from a
+ * previous session, not a live confirmation — so it is removed and NOT
+ * honored, preventing a leftover marker from acting as a standing
+ * auto-approval. Removal is best-effort: a fresh marker we could not unlink
+ * still counted as consumed for THIS call, and a leftover empty sentinel only
+ * ever re-approves the identical (path, bytes, drop-set) Write the model
+ * already confirmed — and only within the TTL.
+ * @param {string} fingerprint
+ * @returns {boolean}
+ */
+function consumeConfirm(fingerprint) {
+  const marker = confirmMarkerPath(fingerprint);
+  if (!markerIsTrusted(marker)) return false;
+  let fresh;
+  try {
+    fresh = Date.now() - lstatSync(marker).mtimeMs <= CONFIRM_TTL_MS;
+  } catch {
+    // Raced away between the trust check and the stat: no sentinel, no confirm.
+    return false;
+  }
+  try {
+    unlinkSync(marker);
+  } catch {
+    // Best-effort consume — see doc.
+  }
+  return fresh;
+}

package/claude-hooks/pretooluse-sanitize.mjs

@@ -54,6 +54,8 @@ import {
   authoredContext,
 } from "./lib/authored-content.mjs";
 import { redactViaDaemon } from "./lib/redactor-client.mjs";
+import { withSecretDropGuard } from "./lib/secret-drop-guard.mjs";
+import { placeholderNotice } from "./lib/placeholder-grammar.mjs";
 import { bestEffortTrace, trace, TraceEvent } from "./lib/trace.mjs";
 
 const HOOK_NAME = "pretooluse-sanitize";
@@ -140,13 +142,15 @@ const redactorIo = {
 
 /**
  * Default Layer-4 rehydrator: the package's rehydrateRedacted bound to the
- * redactor-daemon io. Hoisted (not an inline default-param arrow) so tests can
- * still inject a fake as the second argument to buildPreToolUseResponse.
- * @param {string} tool
- * @param {any} toolInput
+ * redactor-daemon io, composed (via withSecretDropGuard, where the ordering
+ * logic lives and is unit-tested) with the clobber-by-omission guard. Hoisted
+ * (not an inline default-param arrow) so tests can still inject a fake as the
+ * second argument to buildPreToolUseResponse.
  */
-const defaultRehydrate = (tool, toolInput) =>
-  rehydrateRedacted(tool, toolInput, redactorIo);
+const defaultRehydrate = withSecretDropGuard(
+  (tool, toolInput) => rehydrateRedacted(tool, toolInput, redactorIo),
+  redactorIo,
+);
 
 /**
  * Trace the response on the way out — "noop" (clean pass-through), "deny",
@@ -302,6 +306,15 @@ export async function buildPreToolUseResponse(
     });
   contexts.push(...layerContexts);
 
+  // Placeholder advisory for tools OUTSIDE the rehydrated set (Bash, MCP,
+  // anything unknown): rehydration cannot re-anchor these, so a placeholder in
+  // their input would be persisted literally by any write they perform. It
+  // 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);
+  if (notice !== null) contexts.push(notice);
+
   return emitTraced(
     emitTrace,
     input.tool_name,

package/claude-hooks/sanitize-output.mjs

@@ -41,6 +41,7 @@ import {
   isRevealRead,
   REVEAL_READ_ENVELOPE,
 } from "./lib/reveal.mjs";
+import { containsPlaceholder } from "./lib/placeholder-grammar.mjs";
 
 // Layer-1 primitives and the cheap pre-gates, bound via lazyImport (see its
 // doc for the fail-OPEN hazard of a bare static npm import). A load failure
@@ -454,6 +455,22 @@ async function sanitizeObject(
   return { value: out, modified, sgrNote };
 }
 
+// On-disk placeholder tripwire: warning for a Read whose RAW bytes — before
+// this hook's own redaction ran — already carry placeholder-shaped text. That
+// is the after-the-fact signature of a clobbered secret: some earlier write
+// (a heredoc, sed, an MCP file tool, another agent) copied a placeholder out
+// of a sanitized view and persisted it literally. It can equally be a
+// legitimate fixture or document ABOUT redaction, so this is a warning the
+// model relays, never a verdict — detection rides the read, which is the one
+// choke point every write path eventually passes through.
+// Exported so tests assert the surfaced warning by reference instead of
+// re-typing the prose.
+export const ON_DISK_PLACEHOLDER_WARNING =
+  "this file's raw on-disk bytes already contain literal [REDACTED…] " +
+  "placeholder text (not inserted by this sanitizer). If an earlier write " +
+  "copied a placeholder from a sanitized view, the secret it stood for has " +
+  "been destroyed; verify with the user before trusting or propagating this file";
+
 /**
  * Compose the model-facing additionalContext line for a sanitized/flagged tool
  * output. The seam (composeContextSeam) owns the prefix + warning join; this
@@ -742,6 +759,18 @@ export async function evaluateToolOutput(input, ext = {}) {
     const hint = persistReveal(stored);
     if (hint) warnings.push(hint);
   }
+  // On-disk placeholder tripwire (see ON_DISK_PLACEHOLDER_WARNING). Tested on
+  // the RAW tool_response — post-sanitization text carries placeholders this
+  // hook itself just inserted. Reads only: file bytes are where a clobbered
+  // 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.
+  if (
+    input.tool_name === "Read" &&
+    !revealRead &&
+    containsPlaceholder(toolOutput)
+  )
+    warnings.push(ON_DISK_PLACEHOLDER_WARNING);
   // sgrNote implies modified (the carve-out lives inside the Layer-1 strip), so
   // it never independently survives this guard — `modified` covers it.
   if (!modified && warnings.length === 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.21.0",
+  "version": "2.22.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": {
@@ -53,6 +53,7 @@
     "@stryker-mutator/core": "^9.6.1",
     "@stryker-mutator/tap-runner": "^9.6.1",
     "@types/node": "25.9.1",
+    "acorn": "^8.18.0",
     "c8": "11.0.0",
     "esbuild": "0.28.1",
     "eslint": "10.4.0",
@@ -198,8 +199,8 @@
   ],
   "dependencies": {
     "agent-control-plane-core": "0.2.13",
-    "namespace-guard": "0.20.0",
     "css-tree": "^3.2.1",
+    "namespace-guard": "0.20.0",
     "rehype-parse": "9.0.1",
     "remark-gfm": "4.0.1",
     "remark-parse": "11.0.0",

package/src/output.mjs

@@ -221,10 +221,23 @@ async function runRedact(state, redact) {
   if (!secrets) return;
   applyMutation(state, secrets.text);
   state.warnings.push(
-    `API keys/secrets redacted: ${secrets.found.join(", ")}${secrets.note ?? ""}`,
+    `API keys/secrets redacted: ${secrets.found.join(", ")}${secrets.note ?? ""}${REDACTION_DOCTRINE}`,
   );
 }
 
+/**
+ * The doctrine clause riding every redaction warning — the one moment
+ * placeholders enter the model's view. Without it the model has no way to know
+ * that a placeholder written back through any path but Edit/Write (a heredoc,
+ * sed/tee, an MCP file tool) is persisted literally, destroying the secret —
+ * making that route-around an honest mistake rather than a warned one.
+ * Exported so tests assert the composed warning by reference instead of
+ * re-typing the prose.
+ */
+export const REDACTION_DOCTRINE =
+  " (placeholders rehydrate only via Edit/Write on the owning file; other " +
+  "write paths persist the placeholder text and lose the secret)";
+
 // Layer 2/3 pre-gate and warning prose are shared with the root entry
 // (./index.mjs), which runs the same layers; re-exported here because both were
 // part of this module's public surface before they moved.

package/src/rehydrate.mjs

@@ -45,6 +45,13 @@
  * I/O is INJECTED through `io`: the caller supplies file reads and the secret
  * redactor (its map/plain contract). The package never bundles a redactor —
  * detect-secrets, a daemon, or any other engine is the caller's to wire.
+ *
+ * MultiEdit is a candidate but never re-anchored: its edits apply
+ * sequentially, each against the result of the previous, which this module's
+ * one-old_string-against-one-static-view machinery cannot model. A MultiEdit
+ * on a file whose view equals disk passes through; on a divergent file it is
+ * denied with use-single-Edit guidance (see the dispatch in
+ * {@link rehydrateRedacted}).
  */
 import { applyLayer1, LONE_SURROGATE_RE } from "./layer1.mjs";
 import {
@@ -479,6 +486,25 @@ async function rehydrateWrite(ti, view, io, hint) {
   };
 }
 
+/**
+ * The single MultiEdit refusal: covers both 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.
+ * @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`,
+  };
+}
+
 /**
  * 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
@@ -496,6 +522,24 @@ function isCandidate(tool, ti, hint) {
     );
   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
+  // divergent file an unguarded pass-through is both a silent clobber (a
+  // placeholder in new_string persisted verbatim) and the same char-extraction
+  // oracle R1 closes for Edit (an old_string matching bytes inside a redacted
+  // span). The dispatch at the bottom pass-throughs the clean-file case and
+  // denies the divergent one with use-single-Edit guidance.
+  if (tool === "MultiEdit")
+    return (
+      Array.isArray(ti.edits) &&
+      ti.edits.length > 0 &&
+      ti.edits.every(
+        (/** @type {any} */ edit) =>
+          typeof edit?.old_string === "string" &&
+          typeof edit?.new_string === "string",
+      )
+    );
   return false;
 }
 
@@ -538,8 +582,13 @@ export async function rehydrateRedacted(
   if (!isCandidate(tool, toolInput, hint)) return null;
   const hinted =
     tool === "Write" ||
-    toolInput.old_string.includes(hint) ||
-    toolInput.new_string.includes(hint);
+    (tool === "MultiEdit"
+      ? toolInput.edits.some(
+          (/** @type {{old_string: string, new_string: string}} */ edit) =>
+            edit.old_string.includes(hint) || edit.new_string.includes(hint),
+        )
+      : toolInput.old_string.includes(hint) ||
+        toolInput.new_string.includes(hint));
 
   let content;
   try {
@@ -557,8 +606,13 @@ export async function rehydrateRedacted(
     // 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.
     if (nodeErr?.code === "ENOENT") {
-      if (tool !== "Write") return null;
+      if (tool === "Edit" || (tool === "MultiEdit" && !hinted)) return null;
       return {
         deny:
           `${toolInput.file_path} does not exist, so the ${hint}…] placeholder in the ` +
@@ -607,6 +661,11 @@ export async function rehydrateRedacted(
   const deletions = alignDeletions(content, layer1Cleaned);
   const mapped = await io.redactMap(cleaned);
   if ("unmappable" in mapped) {
+    // MultiEdit has no resolver to vet it against an unresolvable map — a
+    // hint-free pass-through here would splice bytes inside spans nothing can
+    // account for, so it gets the MultiEdit deny where a hint-free Edit still
+    // reaches its own resolver-backed pass-through.
+    if (tool === "MultiEdit") return multiEditDeny(toolInput.file_path);
     if (!hinted) return null;
     return {
       deny: `cannot resolve redaction placeholders in ${toolInput.file_path}: ${mapped.unmappable}`,
@@ -623,20 +682,27 @@ export async function rehydrateRedacted(
   // literal text, so there is nothing to re-anchor. `cleaned === content` also
   // rules out a lone-surrogate-only divergence (view.pairs/deletions alone
   // would miss that, since the normalization is neither a redaction pair nor a
-  // Layer-1 deletion). A Write is the exception: its content still carries the
-  // hint prefix (isCandidate guaranteed it), and with no own placeholder to
+  // Layer-1 deletion). HINTED Write and MultiEdit are the exceptions: their
+  // content still carries the hint prefix, and with no own placeholder to
   // resolve that hint is a FOREIGN [REDACTED…] placeholder that would be
-  // persisted verbatim over pristine bytes. Fall through to rehydrateWrite so
-  // it denies with the cross-file guidance — the same verdict a Write onto a
-  // secret-bearing or absent target already gets.
+  // persisted verbatim over pristine bytes. A Write falls through to
+  // 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 === "Write" && toolInput.content.includes(hint))
+    (tool === "Edit" || !hinted)
   )
     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.
+  if (tool === "MultiEdit") return multiEditDeny(toolInput.file_path);
   return tool === "Edit"
     ? rehydrateEdit(
         toolInput,

package/types/claude-hooks/lib/invisible-alert.d.mts

@@ -39,6 +39,8 @@ export function gateAskReason(findings: string): string;
 export function gateReminderContext(): string;
 /** The project the hooks are guarding; the alert paths are keyed to it. */
 export const PROJECT_DIR: string;
+/** Short project digest keying this project's $TMPDIR marker names. */
+export const PROJECT_HASH: string;
 /** Findings the SessionStart scanner could not clean, for the PreToolUse gate. */
 export const ALERT_FILE: string;
 export const ALERT_ACK_FILE: string;

package/types/claude-hooks/lib/placeholder-grammar.d.mts

@@ -0,0 +1,47 @@
+/**
+ * Depth-capped walk: does any string in `value` carry placeholder-shaped text?
+ * The cap fails OPEN (deeper content is unseen) — every caller feeds a
+ * context-only advisory, so a miss costs one line, never a mangled input.
+ * @param {unknown} value
+ * @param {number} [depth]
+ * @returns {boolean}
+ */
+export function containsPlaceholder(value: unknown, depth?: number): boolean;
+/**
+ * Advisory context for a tool call OUTSIDE the rehydrated set (Bash, MCP
+ * tools, anything unknown) whose input carries placeholder-shaped text, or
+ * null. Rehydration only re-anchors Edit/Write; every other write path — a
+ * shell heredoc, `sed -i`, an MCP file tool — persists the literal placeholder
+ * and destroys the secret it stands for. This cannot tell a write from a read
+ * (`grep` for a placeholder is legitimate), so it is deliberately a NOTE, not
+ * a verdict: a false positive costs one sentence of context, never a blocked
+ * call or a mangled input.
+ * @param {string} tool
+ * @param {unknown} toolInput
+ * @returns {string | null}
+ */
+export function placeholderNotice(tool: string, toolInput: unknown): string | null;
+/**
+ * The redaction-placeholder grammar, mirrored from the single producer in
+ * python/agent_sanitizer/secrets/placeholders.py (PLACEHOLDER_LABEL_CHARS /
+ * PLACEHOLDER_RE there), plus the advisory for placeholder text in tool inputs
+ * rehydration cannot re-anchor.
+ *
+ * This lives in the HOOKS layer, not the engine (`src/`), deliberately: the
+ * plugin bundle inlines the hook sources from this repo but resolves the
+ * engine from the pinned registry release, so an engine export the pin lacks
+ * is undefined in the shipped bundle. The grammar's consumers (the PreToolUse
+ * advisory, the PostToolUse on-disk tripwire, the drop guard's deny prose) are
+ * all hooks, so defining it here keeps the shipped bundle and the source tree
+ * on one implementation. test/placeholder-guards.test.mjs pins these constants
+ * against the Python source, so an edit to either side that forgets the other
+ * fails CI rather than letting the two parsers drift.
+ */
+export const PLACEHOLDER_LABEL_CHARS: "A-Za-z0-9 ()._-";
+/**
+ * Matches exactly the placeholder text the canonical redactor can emit:
+ * `[REDACTED]` or `[REDACTED: <label>]`. Detection sites use this — never a
+ * bare `[REDACTED` prefix — so hint-prefixed prose (`[REDACTED…]`,
+ * `grep "\[REDACTED"`) is not mistaken for a placeholder.
+ */
+export const PLACEHOLDER_RE: RegExp;

package/types/claude-hooks/lib/secret-drop-guard.d.mts

@@ -0,0 +1,88 @@
+/**
+ * Fingerprint of one exact drop: same path, same new bytes, same set of
+ * secret values being removed. The model confirms by re-issuing the identical
+ * call, so the sentinel must match nothing broader — including the dropped
+ * values themselves: if the file's secrets change between the deny and the
+ * retry, the retry is dropping something the model was never warned about,
+ * and must be re-denied.
+ * @param {string} filePath
+ * @param {string} content
+ * @param {string[]} [dropped] the secret values the Write would remove
+ * @returns {string}
+ */
+export function dropFingerprint(filePath: string, content: string, dropped?: string[]): string;
+/**
+ * The confirm sentinel's path for one fingerprint. Predictable and
+ * world-visible like the alert markers, hence the markerIsTrusted read.
+ * @param {string} fingerprint
+ * @returns {string}
+ */
+export function confirmMarkerPath(fingerprint: string): string;
+/**
+ * Whether git tracks `filePath`. Exit 0 is tracked; exit 1 (untracked) and 128
+ * (not a repository) both mean "no git recovery exists", which is what the
+ * guard actually cares about. A spawn-level failure (no git binary) means we
+ * cannot tell — report tracked so the guard skips (fail open) rather than
+ * denying on missing tooling.
+ * @param {string} filePath
+ * @param {typeof spawnSync} [spawn]
+ * @returns {boolean}
+ */
+export function gitTracked(filePath: string, spawn?: typeof spawnSync): boolean;
+/**
+ * Deny a first-time Write that would drop a redacted secret from an untracked
+ * file, or null to let it pass. `toolInput` is the FINAL Write input — after
+ * rehydration substituted any placeholders — so a preserved secret shows up as
+ * its real value in `content`. `io` is the rehydrate-shaped I/O bag (readFile /
+ * redact / redactMap). Injectable seams: `isTracked` (the git probe),
+ * `confirmSeen`/`recordConfirm` (the sentinel state).
+ * @param {{file_path?: unknown, content?: unknown}} toolInput
+ * @param {import("agent-sanitizer/rehydrate").RehydrateIo} io
+ * @param {{
+ *   isTracked?: (filePath: string) => boolean,
+ *   confirmSeen?: (fingerprint: string) => boolean,
+ *   recordConfirm?: (fingerprint: string) => void,
+ * }} [opts]
+ * @returns {Promise<{deny: string} | null>}
+ */
+export function secretDropGuard(toolInput: {
+    file_path?: unknown;
+    content?: unknown;
+}, io: import("agent-sanitizer/rehydrate").RehydrateIo, opts?: {
+    isTracked?: (filePath: string) => boolean;
+    confirmSeen?: (fingerprint: string) => boolean;
+    recordConfirm?: (fingerprint: string) => void;
+}): Promise<{
+    deny: string;
+} | null>;
+/**
+ * Compose a Layer-4 rehydrator with this guard: for a Write the rehydrator
+ * did not deny, run the guard on the FINAL content — after any placeholder
+ * substitution — so a rehydrated secret counts as preserved and only a
+ * genuinely dropped one can trip it. A rehydrate deny short-circuits (the
+ * guard never runs), non-Write tools skip the guard entirely, and a guard
+ * deny wins over a pass/rewrite result.
+ * @typedef {{updatedInput: any, context: string} | {deny: string} | null} RehydrateResult
+ * @param {(tool: string, toolInput: any) => Promise<RehydrateResult>} rehydrate
+ * @param {import("agent-sanitizer/rehydrate").RehydrateIo} io
+ * @param {typeof secretDropGuard} [guard]
+ * @returns {(tool: string, toolInput: any) => Promise<RehydrateResult>}
+ */
+export function withSecretDropGuard(rehydrate: (tool: string, toolInput: any) => Promise<RehydrateResult>, io: import("agent-sanitizer/rehydrate").RehydrateIo, guard?: typeof secretDropGuard): (tool: string, toolInput: any) => Promise<RehydrateResult>;
+/** A confirm sentinel older than this is stale, not a confirmation. */
+export const CONFIRM_TTL_MS: number;
+/**
+ * Compose a Layer-4 rehydrator with this guard: for a Write the rehydrator
+ * did not deny, run the guard on the FINAL content — after any placeholder
+ * substitution — so a rehydrated secret counts as preserved and only a
+ * genuinely dropped one can trip it. A rehydrate deny short-circuits (the
+ * guard never runs), non-Write tools skip the guard entirely, and a guard
+ * deny wins over a pass/rewrite result.
+ */
+export type RehydrateResult = {
+    updatedInput: any;
+    context: string;
+} | {
+    deny: string;
+} | null;
+import { spawnSync } from "node:child_process";

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

@@ -247,6 +247,7 @@ export const SECRET_HINT_EXT: RegExp;
 export const describeRemoved: typeof import("agent-sanitizer/output").describeRemoved;
 export const describeWarned: typeof import("agent-sanitizer/output").describeWarned;
 export const suppressToolOutput: typeof import("agent-sanitizer/output").suppressToolOutput;
+export const ON_DISK_PLACEHOLDER_WARNING: string;
 /**
  * Host-supplied extensions to this hook, threaded from {@link cliMain} down to
  * each string leaf. Every field is optional and the bag defaults to `{}`, so a

package/types/output.d.mts

@@ -152,6 +152,16 @@ export const FILTER_WARNING: Readonly<{
     FILTER_FLAGGED: "filter-flagged";
     FILTER_ERROR: "filter-error";
 }>;
+/**
+ * The doctrine clause riding every redaction warning — the one moment
+ * placeholders enter the model's view. Without it the model has no way to know
+ * that a placeholder written back through any path but Edit/Write (a heredoc,
+ * sed/tee, an MCP file tool) is persisted literally, destroying the secret —
+ * making that route-around an honest mistake rather than a warned one.
+ * Exported so tests assert the composed warning by reference instead of
+ * re-typing the prose.
+ */
+export const REDACTION_DOCTRINE: string;
 export { needsMarkdownPipeline };
 /**
  * Maximum container nesting `sanitizeValue` / `suppressToolOutput` will descend