agent-sanitizer 2.68.0 → 2.69.0

package/README.md

@@ -138,9 +138,10 @@ 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
+splice, and a write that would persist placeholder text over a real secret is
+refused once, even when the hook's own machinery fails mid-session, and proceeds
+with a warning when re-issued. 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.
@@ -193,9 +194,10 @@ withholds a string-shaped response; the shell arm in `plugin/scripts/safe-launch
 therefore also emits a top-level `decision`/`reason` pair, honored whatever
 shape the response had, telling the model that any output still visible above
 it is unsanitized. 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
+open default, with secrets enabled: a write-shaped call carrying `[REDACTED…]`
+placeholder text is refused once when the hook itself is broken, since letting
+it through would overwrite the real secret with the placeholder; the exact
+re-issue proceeds with a warning. 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

@@ -960,20 +960,28 @@ 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
+placeholder prefix, the hook **refuses it once** instead of passing it 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. The refusal is releasable, never a loop: the exact same call
+re-issued is let through with a warning that the placeholder was written
+literally, and when the hook cannot record that confirmation (an unwritable
+`$TMPDIR`) it lets the call through at once with the warning. The same rule
+covers a write whose placeholder cannot be restored — a Layer-2 span missing
+from the store, an unreadable target, a redactor map that fails validation.
+Releasing an unhinted Edit on a file whose redactor map fails validation reopens
+the hidden-span probing oracle the rehydrator closes, at the price of one refusal
+per distinct probe, for as long as the redactor stays broken. An unhinted Write
+there skips the secret-drop guard, which reads the same broken map, so its
+refusal and warning say instead that any redacted secret it omits is removed. 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, a provisioned hook binary
 that is missing, unexecutable or dies without a verdict) 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
+because command strings mention `[REDACTED` benignly far too often for the
+refusal 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
@@ -1005,13 +1013,13 @@ in `claude-hooks/sanitize-output.mjs` — so a host that wires those directly (a
 `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 posture does NOT reach **detection verdicts**: it speaks only to the hook
+FAILING, and a working sanitizer that found an injection blocks under both
+settings. It does reach an unknown `--hook=` mode — static wiring corruption,
+from a `hooks.json` and bundle out of step: under the open default that hook
+exits non-blocking with a stderr line naming the mode and the fix, so every
+event it fires on reports the gap loudly instead of blocking the session, and
+under `=0` it exits 2.
 
 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,
@@ -1046,8 +1054,13 @@ extracts by walking the TypeScript AST of every shipped `.mjs` (not by matching
 regex source with a regex), and fails on any pattern with super-linear
 backtracking. A `RegExp(…)` built at runtime must be statically resolvable or
 carry a written exemption, so a new dynamic pattern is a red build rather than a
-hole. `tests/secrets/test_redos_static_guard.py` is the twin over the Python
-engine. In `pnpm lint`, `eslint-plugin-redos` (recheck) and
+hole. No construction may read call-time data either — a parameter, tool
+output, `process.env` — because a pattern compiled from it is as large as that
+data, and past V8's size limit it throws on every call; the same walk covers a
+string handed to `.match`/`.matchAll`/`.search`.
+`tests/secrets/test_redos_static_guard.py` is the twin over the Python engine,
+and `tests/secrets/test_regex_size_static_guard.py` holds the Python package to
+the call-time rule. In `pnpm lint`, `eslint-plugin-redos` (recheck) and
 `eslint-plugin-regexp`'s `no-super-linear-backtracking` and
 `no-super-linear-move` read every shipped regex literal — the last of them
 reports the shape that carries no backtracking at all, an **unanchored**

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

@@ -97,8 +97,10 @@ export const FAULT_POLICY_HOOKS = Object.freeze([
 /**
  * A hook's declared posture. There is deliberately no way for a policy to pin
  * the CLOSED arm: AGENT_SANITIZER_FAIL_OPEN alone decides, so no hook fault can
- * withhold a tool output or block a prompt unless the operator set the knob to
- * `0`. A pin turns any bug in the guarded layer into every tool call failing.
+ * withhold a tool output, block a prompt, or hold a tool call for good unless the
+ * operator set the knob to `0` (an open arm may refuse a call once, releasing the
+ * exact re-issue). A pin turns any bug in the guarded layer into every tool call
+ * failing.
  * @typedef {{
  *   event: string | null,
  *   guarded: string,

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

@@ -680,6 +680,77 @@ export function emitHookResponse(hookEventName, fields) {
   );
 }
 
+/**
+ * Fold several hook envelopes into the ONE that may reach stdout: `systemMessage`
+ * and `additionalContext` are joined (a later part is appended, never allowed to
+ * displace an earlier one); any other field takes the last value written.
+ * @param {Array<Record<string, any>>} envelopes  non-empty
+ * @returns {Record<string, any>}
+ */
+function mergeEnvelopes(envelopes) {
+  /** @type {Record<string, any>} */
+  const merged = {};
+  /** @type {Record<string, any>} */
+  const specific = {};
+  /** @type {string[]} */
+  const systemMessages = [];
+  /** @type {string[]} */
+  const contexts = [];
+  for (const { hookSpecificOutput, systemMessage, ...rest } of envelopes) {
+    Object.assign(merged, rest);
+    if (systemMessage) systemMessages.push(systemMessage);
+    if (!hookSpecificOutput) continue;
+    const { additionalContext, ...fields } = hookSpecificOutput;
+    Object.assign(specific, fields);
+    if (additionalContext) contexts.push(additionalContext);
+  }
+  if (systemMessages.length > 0)
+    merged.systemMessage = systemMessages.join("\n");
+  if (contexts.length > 0) specific.additionalContext = contexts.join("\n");
+  if (Object.keys(specific).length > 0) merged.hookSpecificOutput = specific;
+  return merged;
+}
+
+/**
+ * @typedef {{
+ *   add: (envelope: Record<string, any>) => void,
+ *   emit: (hookEventName: string, fields: Record<string, unknown>) => void,
+ *   flush: () => void,
+ * }} EnvelopeBuffer
+ */
+
+/**
+ * Collect everything a hook run wants to say on stdout and write it as exactly
+ * ONE JSON object on `flush`. Claude Code parses a hook's stdout as a single
+ * document, so two envelopes written by two reporters (a fault notice, then the
+ * slow-hook notice from the timing wrapper's `finally`) concatenate into invalid
+ * output and the host DROPS the whole response — the model never sees either
+ * warning. Every reporter in a run therefore adds here instead of writing, and
+ * the entry point flushes once, last.
+ * @param {(chunk: string) => void} [write]  injectable stdout sink, for tests
+ * @returns {EnvelopeBuffer}
+ */
+export function createEnvelopeBuffer(
+  write = (chunk) => process.stdout.write(chunk),
+) {
+  /** @type {Array<Record<string, any>>} */
+  const pending = [];
+  /** @param {Record<string, any>} envelope */
+  const add = (envelope) => {
+    pending.push(envelope);
+  };
+  return {
+    add,
+    emit: (hookEventName, fields) =>
+      add({ hookSpecificOutput: { hookEventName, ...fields } }),
+    flush() {
+      if (pending.length === 0) return;
+      write(JSON.stringify(mergeEnvelopes(pending)));
+      pending.length = 0;
+    },
+  };
+}
+
 /**
  * The project the hooks are guarding. Every per-project $TMPDIR store is keyed to
  * it, so it lives here — beside the other shared identity these hooks agree on —
@@ -799,7 +870,7 @@ export function hookgateMarkerPath(
   // Prefer the per-user, mode-0700 runtime dir when the harness gives an
   // absolute one; else the world-writable /tmp, where markerIsTrusted() — not
   // the path — defends against a squatted marker.
-  const base = runtimeDir && runtimeDir.startsWith("/") ? runtimeDir : "/tmp";
+  const base = runtimeDir && isAbsolute(runtimeDir) ? runtimeDir : "/tmp";
   // The flattened dir is for a human reading `ls /tmp`; the digest of the RAW
   // dir is the identity. Flattening alone is lossy — /work/a-b, /work/a_b and
   // "/work/a b" all collapse to one name — and two such projects on one machine
@@ -811,7 +882,7 @@ export function hookgateMarkerPath(
     .digest("hex")
     .slice(0, 8);
   const flattened = projectDir.replace(/[^A-Za-z0-9]/g, "_");
-  return `${base}/${HOOKGATE_MARKER_STEM}${flattened}-${digest}`;
+  return join(base, `${HOOKGATE_MARKER_STEM}${flattened}-${digest}`);
 }
 
 /**
@@ -1199,26 +1270,30 @@ export function touchLiveState(path) {
  * file the hook's user owns. Unlink any existing entry first (removing a squatted
  * symlink), then create exclusively (O_EXCL) so a symlink re-planted in the race
  * window fails the open rather than being dereferenced. Content is irrelevant —
- * callers test only for existence — so the file is left empty. Best-effort: a
- * missing/read-only $TMPDIR or a lost race just leaves the sentinel absent, and
- * every caller treats "absent" as "not yet done" (a repeated ask, never a crash),
- * so all failures are swallowed.
+ * callers test only for existence — so the file is left empty. Never throws: a
+ * missing/read-only $TMPDIR or a lost race leaves the sentinel absent, and the
+ * return value says so. A caller whose refusal is released only by a later read
+ * of this sentinel must branch on it, because a refusal that records nothing can
+ * never be released.
  * @param {string} path
- * @returns {void}
+ * @returns {boolean}  whether a sentinel this uid owns now exists at `path`
+ *   (the same test {@link markerIsTrusted} applies when a reader looks for it)
  */
 export function writeSentinelFile(path) {
   try {
     unlinkSync(path);
   } catch {
     // No existing entry (the common case), or an unremovable one — either way the
-    // exclusive create below is the real guard, and its own failure is swallowed.
+    // exclusive create below is the real guard, and its own failure is returned.
   }
   try {
     closeSync(openSync(path, "wx"));
   } catch {
     // A symlink re-planted in the unlink→open window, an unwritable dir, or a
-    // leftover entry: skip silently — the caller simply re-asks next time.
+    // leftover entry.
+    return false;
   }
+  return markerIsTrusted(path);
 }
 
 /**

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

@@ -706,14 +706,17 @@ export function alertAcknowledged(sessionId) {
 /**
  * Record that the gate has surfaced its blocking ask, so later tool calls get a
  * passive reminder instead of an ask on every call. Session-keyed, so the next
- * session re-asks once without anything having to clear this.
+ * session re-asks once without anything having to clear this. Returns false
+ * when the ack could not be recorded, so the caller knows the next call will
+ * ask again: under the fail-open posture it surfaces the finding as a warning
+ * rather than asking on every tool call for the rest of the session.
  * @param {string} [sessionId]
- * @returns {void}
+ * @returns {boolean}
  */
 export function acknowledgeAlert(sessionId) {
   // Symlink-safe presence write: the ack sits at a predictable STATE_ROOT path
   // a co-tenant could pre-plant a symlink at (see writeSentinelFile).
-  writeSentinelFile(alertAckFile(sessionId));
+  return writeSentinelFile(alertAckFile(sessionId));
 }
 
 // What the operator can actually DO — one bullet per kind of report the alert

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

@@ -1,5 +1,6 @@
 /**
- * Clobber-by-omission guard for whole-file Writes.
+ * Clobber-by-omission guard for whole-file Writes, and the confirm-by-exact-
+ * re-issue sentinel it shares with every other releasable PreToolUse refusal.
  *
  * Rehydration (agent-sanitizer/rehydrate) only engages when a Write's content
  * carries a placeholder; a Write that REGENERATES a secret-bearing file and
@@ -65,12 +66,62 @@ export const CONFIRM_TTL_MS = 10 * 60_000;
  * @returns {string}
  */
 export function dropFingerprint(filePath, content, dropped = []) {
-  const digest = createHash("sha256").update(filePath).update("\0");
+  const digest = createHash("sha256").update("drop\0").update(filePath);
+  digest.update("\0");
   digest.update(content);
   for (const secret of dropped) digest.update("\0").update(secret);
   return digest.digest("hex").slice(0, 32);
 }
 
+/**
+ * Fingerprint of one refusal of one exact tool call — same refusing site, same
+ * tool, same input — released by re-issuing that call. Keyed on the site too, so
+ * a call refused by two sites in turn needs a confirmation for each and one
+ * re-issue never releases a refusal the model was not shown. The input is
+ * hashed in canonical key order, so a re-issue whose keys arrive reordered is
+ * still the same call. Distinct domain tags keep it disjoint from
+ * {@link dropFingerprint}.
+ * @param {string} site
+ * @param {unknown} tool
+ * @param {unknown} toolInput
+ * @returns {string}
+ */
+export function reissueFingerprint(site, tool, toolInput) {
+  return createHash("sha256")
+    .update("reissue\0")
+    .update(canonicalJson([site, tool ?? null, toolInput ?? null]))
+    .digest("hex")
+    .slice(0, 32);
+}
+
+/**
+ * JSON with every object's keys sorted, so two encodings of one value agree.
+ * @param {unknown} value
+ * @returns {string}
+ */
+function canonicalJson(value) {
+  return JSON.stringify(value, (_key, v) =>
+    v !== null && typeof v === "object" && !Array.isArray(v)
+      ? Object.fromEntries(
+          Object.keys(v)
+            .sort()
+            .map((k) => [k, v[k]]),
+        )
+      : v,
+  );
+}
+
+/**
+ * Record a confirm sentinel for `fingerprint`, so the identical re-issue is
+ * approved by {@link consumeConfirm}. False when it could not be recorded: the
+ * caller then must not refuse, because nothing could ever release the refusal.
+ * @param {string} fingerprint
+ * @returns {boolean}
+ */
+export function recordConfirm(fingerprint) {
+  return writeSentinelFile(confirmMarkerPath(fingerprint));
+}
+
 /**
  * The confirm sentinel's path for one fingerprint. Predictable and
  * world-visible like the alert markers, hence the markerIsTrusted read.
@@ -81,6 +132,9 @@ export function confirmMarkerPath(fingerprint) {
   return join(tmpdir(), `.claude-secret-drop-${PROJECT_HASH}-${fingerprint}`);
 }
 
+/** readdir codes meaning the confirm store's directory cannot be used at all. */
+const UNUSABLE_DIR_CODES = new Set(["ENOENT", "ENOTDIR", "EACCES", "EPERM"]);
+
 /**
  * Delete this project's confirm sentinels older than {@link CONFIRM_TTL_MS}.
  *
@@ -95,7 +149,18 @@ export function sweepStaleConfirms() {
   const dir = tmpdir();
   const prefix = `.claude-secret-drop-${PROJECT_HASH}-`;
   const cutoff = Date.now() - CONFIRM_TTL_MS;
-  for (const name of readdirSync(dir)) {
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch (err) {
+    // An unusable $TMPDIR holds no sentinel to sweep, and recordConfirm already
+    // answers for it on every call; letting it throw here would abort the
+    // SessionStart scan this sweep merely rides along with.
+    const code = /** @type {NodeJS.ErrnoException} */ (err).code;
+    if (UNUSABLE_DIR_CODES.has(String(code))) return;
+    throw err;
+  }
+  for (const name of names) {
     if (!name.startsWith(prefix)) continue;
     const path = join(dir, name);
     try {
@@ -150,14 +215,34 @@ export function gitTracked(filePath, spawn = spawnSync) {
 /**
  * @param {number} count
  * @param {string} filePath
+ * @param {boolean} [confirmable] false when no confirmation could be recorded,
+ *   so the reason must not offer a re-issue that would only be refused again
  * @returns {string}
  */
-function dropDeny(count, filePath) {
-  return (
+function dropDeny(count, filePath, confirmable = true) {
+  const head =
     `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`
+    `file is not tracked by git, so the secrets may be unrecoverable. `;
+  const placeholders = `[REDACTED…] placeholder (or its secret's line) in the new content`;
+  return confirmable
+    ? `${head}If removing them is intended, re-issue this exact Write to confirm; ` +
+        `otherwise keep each ${placeholders}`
+    : `${head}Keep each ${placeholders}, or ask the user to remove them`;
+}
+
+/**
+ * The `fault` a drop deny carries when its confirmation could not be recorded:
+ * the deny could then never be released by a re-issue, so it is a sanitizer
+ * fault rather than a verdict, and the hook's fault posture decides it.
+ * @param {number} count
+ * @param {string} filePath
+ * @returns {string}
+ */
+function dropUnconfirmable(count, filePath) {
+  return (
+    `the secret-drop confirmation could not be recorded under ${tmpdir()}, so ` +
+    `this Write removes ${count} redacted secret value(s) from untracked ` +
+    `${filePath} without a confirmed re-issue`
   );
 }
 
@@ -167,22 +252,22 @@ function dropDeny(count, filePath) {
  * 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).
+ * `confirmSeen`/`recordConfirm` (the sentinel state). A deny whose confirmation
+ * could not be recorded carries `fault` (see {@link dropUnconfirmable}).
  * @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,
+ *   recordConfirm?: (fingerprint: string) => boolean,
  * }} [opts]
- * @returns {Promise<{deny: string} | null>}
+ * @returns {Promise<{deny: string, fault?: string} | null>}
  */
 export async function secretDropGuard(toolInput, io, opts = {}) {
   const {
     isTracked = gitTracked,
     confirmSeen = consumeConfirm,
-    recordConfirm = (fingerprint) =>
-      writeSentinelFile(confirmMarkerPath(fingerprint)),
+    recordConfirm: record = recordConfirm,
   } = opts;
   const { file_path: filePath, content } = toolInput ?? {};
   if (typeof filePath !== "string" || typeof content !== "string") return null;
@@ -225,8 +310,11 @@ export async function secretDropGuard(toolInput, io, opts = {}) {
   // context, or a marker left by an abandoned attempt becomes a standing
   // auto-approval for a Write the user never saw.
   if (confirmSeen(fingerprint)) return null;
-  recordConfirm(fingerprint);
-  return { deny: dropDeny(dropped.length, filePath) };
+  if (record(fingerprint)) return { deny: dropDeny(dropped.length, filePath) };
+  return {
+    deny: dropDeny(dropped.length, filePath, false),
+    fault: dropUnconfirmable(dropped.length, filePath),
+  };
 }
 
 /**
@@ -235,8 +323,12 @@ export async function secretDropGuard(toolInput, io, opts = {}) {
  * 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
+ * deny wins over a pass/rewrite result. A guard FAULT deny carries the
+ * rewrite as `release`: the open posture lets that call proceed, and it must
+ * proceed rehydrated, or every secret the rewrite restored is overwritten by
+ * its placeholder.
+ * @typedef {{updatedInput: any, context: string}} RehydrateRewrite
+ * @typedef {RehydrateRewrite | {deny: string, fault?: string, release?: RehydrateRewrite} | null} RehydrateResult
  * @param {(tool: string, toolInput: any) => Promise<RehydrateResult>} rehydrate
  * @param {import("agent-sanitizer/rehydrate").RehydrateIo} io
  * @param {typeof secretDropGuard} [guard]
@@ -250,33 +342,29 @@ export function withSecretDropGuard(rehydrate, io, guard = secretDropGuard) {
     const finalInput =
       rehydrated === null ? toolInput : rehydrated.updatedInput;
     const drop = await guard(finalInput, io);
-    return drop ?? rehydrated;
+    if (drop === null) return rehydrated;
+    if (drop.fault === undefined || rehydrated === null) return drop;
+    return { ...drop, release: rehydrated };
   };
 }
 
 /**
  * True when a trusted, fresh confirm sentinel exists for `fingerprint`,
- * consuming it so one confirmation approves exactly one Write. A sentinel
+ * consuming it so one confirmation approves exactly one call. 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.
+ * ever re-approves the identical fingerprinted call the model already
+ * confirmed — and only within the TTL.
  * @param {string} fingerprint
  * @returns {boolean}
  */
-function consumeConfirm(fingerprint) {
+export 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;
-  }
+  const fresh = confirmFresh(fingerprint);
   try {
     unlinkSync(marker);
   } catch {
@@ -284,3 +372,22 @@ function consumeConfirm(fingerprint) {
   }
   return fresh;
 }
+
+/**
+ * True when a trusted confirm sentinel younger than {@link CONFIRM_TTL_MS}
+ * exists for `fingerprint`, WITHOUT consuming it — for a caller that learns
+ * only later whether the call it confirms actually proceeds, and consumes it
+ * then.
+ * @param {string} fingerprint
+ * @returns {boolean}
+ */
+export function confirmFresh(fingerprint) {
+  const marker = confirmMarkerPath(fingerprint);
+  if (!markerIsTrusted(marker)) return false;
+  try {
+    return Date.now() - lstatSync(marker).mtimeMs <= CONFIRM_TTL_MS;
+  } catch {
+    // Raced away between the trust check and the stat: no sentinel, no confirm.
+    return false;
+  }
+}

package/claude-hooks/plugin-hooks.mjs

@@ -34,28 +34,31 @@ const HOOK_NAME = "plugin-hooks";
 
 // The dispatcher's entry in the one posture table (lib/hook-fault.mjs). It
 // answers no single event — it is the binder in front of all of them — so it
-// carries no stdout envelope and both arms are process-level.
+// carries no stdout envelope and both arms are process-level. Its one fault is
+// an unknown `--hook` mode: broken hooks.json wiring, so no hook runs for that
+// event until the install is fixed.
 //
-// BOTH ARMS BLOCK, and that is the declaration, not an oversight. The
-// AGENT_SANITIZER_FAIL_OPEN knob covers a hook that RAN and broke; an unknown
-// mode is static wiring corruption, which means no hook runs at all, silently,
-// for the life of the install — there is no run to degrade. Stating it here (and
-// pinning it in plugin/test/plugin-bundle.test.mjs) is the point of the table:
-// the arm that ignores the knob does so on the record, next to the ones that
-// honor it, instead of by hard-exiting past the question.
-//
-// Exit 2 is the one non-zero code Claude Code treats as BLOCKING: it blocks
-// PreToolUse and UserPromptSubmit, surfaces stderr for PostToolUse, and is
-// harmless for SessionStart.
-const unknownMode = (/** @type {{ message: string }} */ ctx) => ({
-  stderr: `${HOOK_NAME}: ${ctx.message}\n`,
-  exitCode: 2,
-});
+// OPEN exits 1, which Claude Code treats as a non-blocking hook error; through
+// plugin/scripts/safe-launch.sh it becomes that event's fail-open warning.
+// CLOSED exits 2, the one non-zero code Claude Code treats as BLOCKING: it
+// blocks PreToolUse and UserPromptSubmit, surfaces stderr for PostToolUse, and
+// is harmless for SessionStart.
+const unknownModeLine = (/** @type {{ message: string }} */ ctx) =>
+  `${HOOK_NAME}: ${ctx.message} — hooks.json names a hook this bundle does ` +
+  `not dispatch (known: ${HOOK_MODES.join(", ")}); reinstall or update the plugin.`;
 registerFaultPolicy(HOOK_NAME, {
   event: null,
   guarded: "hook payload",
-  open: unknownMode,
-  closed: unknownMode,
+  open: (ctx) => ({
+    stderr:
+      `${unknownModeLine(ctx)} This event is UNGUARDED; set ` +
+      "AGENT_SANITIZER_FAIL_OPEN=0 to block it instead.\n",
+    exitCode: 1,
+  }),
+  closed: (ctx) => ({
+    stderr: `${unknownModeLine(ctx)} Blocking (AGENT_SANITIZER_FAIL_OPEN=0).\n`,
+    exitCode: 2,
+  }),
 });
 
 // The packages the hooks lazy-load, each behind a thunk whose import specifier
@@ -199,14 +202,16 @@ export async function main() {
     // some default hook and vet the wrong payload class. WHICH way it fails is
     // the operator's call, taken through the one posture table like every other
     // hook fault.
-    process.exit(
-      writeFaultOutcome(
-        hookFaultOutcome(
-          HOOK_NAME,
-          new Error(`unknown hook mode ${JSON.stringify(mode)}`),
-        ),
+    process.exitCode = writeFaultOutcome(
+      hookFaultOutcome(
+        HOOK_NAME,
+        new Error(`unknown hook mode ${JSON.stringify(mode)}`),
       ),
     );
+    // Drained like the disabled arm below: under the open posture the event
+    // proceeds, and a harness left writing into a closed pipe sees EPIPE.
+    process.stdin.resume();
+    return;
   }
 
   // An empty envelope is a verdict, not a crash: stdout stays non-empty, so the