agent-sanitizer 2.67.2 → 2.69.0

package/src/output.mjs

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

package/src/rehydrate.mjs

@@ -823,6 +823,12 @@ function isCandidate(tool, ti) {
  * there is nothing to do. Throws only on internal error (the caller fails
  * closed).
  *
+ * A deny carrying `fault` is not a verdict on the input but this module being
+ * unable to do its job (an unreadable target, a redactor map that fails
+ * validation): `fault` states what proceeding un-rehydrated would write, and the
+ * caller's failure posture decides whether the deny stands. A deny without it
+ * is a verdict and stands in every posture.
+ *
  * `io` is the injected I/O (file read + redactor map/plain). `hint` is the
  * redaction-placeholder prefix (defaults to {@link DEFAULT_HINT}); override it
  * only if the injected redactor emits a different placeholder shape.
@@ -830,7 +836,7 @@ function isCandidate(tool, ti) {
  * @param {any} toolInput
  * @param {RehydrateIo} io
  * @param {{ hint?: string }} [options]
- * @returns {Promise<{updatedInput: any, context: string} | {deny: string} | null>}
+ * @returns {Promise<{updatedInput: any, context: string} | {deny: string, fault?: string} | null>}
  */
 export async function rehydrateRedacted(
   tool,
@@ -911,12 +917,17 @@ export async function rehydrateRedacted(
       if (tool !== "Write") throw err;
       return null;
     }
+    const cause = nodeErr?.code ?? nodeErr?.message;
     return {
       deny:
         `could not read ${toolInput.file_path} to rehydrate its secrets ` +
-        `(${nodeErr?.code ?? nodeErr?.message}); the file likely still exists, so writing ` +
+        `(${cause}); the file likely still exists, so writing ` +
         `the placeholder text as-is risks overwriting a real secret. Retry the read, or ` +
         `ask the user to make this change directly`,
+      fault:
+        `${toolInput.file_path} could not be read (${cause}) to rehydrate its ` +
+        `secrets, so this call is not rehydrated and its ${hint}…] placeholder ` +
+        `text is written to the file literally`,
     };
   }
   const { layer1Cleaned, cleaned } = layer1View(content);
@@ -949,8 +960,14 @@ export async function rehydrateRedacted(
     // reaches its own resolver-backed pass-through.
     if (tool === "MultiEdit") return multiEditDeny(toolInput.file_path);
     if (!hinted) return null;
+    // A verdict, not a fault: the file itself defeats mapping on every call, so
+    // a released re-issue would overwrite the real secret with its placeholder.
+    // The escape is to stop writing the placeholder, which the reason names.
     return {
-      deny: `cannot resolve redaction placeholders in ${toolInput.file_path}: ${mapped.unmappable}`,
+      deny:
+        `cannot resolve redaction placeholders in ${toolInput.file_path}: ` +
+        `${mapped.unmappable}. Leave every ${hint}…] placeholder out of this ` +
+        `call (edit around it), or ask the user to make this change`,
     };
   }
   // The redactor emits code-point offsets; the offset machinery below works in
@@ -970,9 +987,8 @@ export async function rehydrateRedacted(
   // 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.
+  // hint state with a `fault`, never a throw: the deny lets the caller refuse
+  // the call once and name what proceeding writes, which a throw cannot.
   let view = null;
   let mapDefect = null;
   try {
@@ -993,14 +1009,25 @@ export async function rehydrateRedacted(
     // 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.
+    // nothing can vet (the R1 hidden-span oracle). Deny, as a fault: the
+    // engine, not the input, is what is wrong.
     if (tool === "MultiEdit") return multiEditDeny(toolInput.file_path);
+    // A Write replaces the whole file, and the secret-drop guard reads this
+    // same broken map, so the loss it would name has to be named here instead.
+    const dropped =
+      tool === "Write"
+        ? `; it replaces the whole file, so any redacted secret it does not ` +
+          `reproduce is removed, and which secrets those are cannot be checked`
+        : "";
     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`,
+        `verified${dropped}. Retry later, or ask the user to make this change`,
+      fault:
+        `${mapDefect} for ${toolInput.file_path}, so this call is not ` +
+        `rehydrated: any ${hint}…] placeholder text in it is written to the ` +
+        `file literally, and it is applied without the redacted-span checks${dropped}`,
     };
   }
   // View identical to disk: any placeholders in an Edit's old_string are

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

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

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

@@ -286,6 +286,25 @@ export function safeErrMessage(err: unknown, cap?: number): string;
  * @returns {void}
  */
 export function emitHookResponse(hookEventName: string, fields: Record<string, unknown>): void;
+/**
+ * @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: string) => void): EnvelopeBuffer;
 /**
  * The directory the session-lifetime stores live under: the alert markers and
  * findings (invisible-alert.mjs) and the reveal sidecars (reveal.mjs). They must
@@ -522,14 +541,16 @@ export function touchLiveState(path: string): void;
  * 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: string): void;
+export function writeSentinelFile(path: string): boolean;
 /**
  * Write `content` to `path` without following a symlink a co-tenant may have
  * pre-planted there — the content-bearing counterpart to writeSentinelFile. These
@@ -635,6 +656,11 @@ export const STATE_ROOT: string;
  * says it locks may be judged by the lock.
  */
 export const SETUP_LOCK_DECLARATION: "flock";
+export type EnvelopeBuffer = {
+    add: (envelope: Record<string, any>) => void;
+    emit: (hookEventName: string, fields: Record<string, unknown>) => void;
+    flush: () => void;
+};
 /**
  * EVERY process-wide slot these helpers keep — the four a host can observe or
  * steer, so a second instance that adopts this object is steered in all four at

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

@@ -170,10 +170,15 @@ export function startHookTimer(now?: () => number, cpuNow?: () => number): {
  * sanitizer computing, and with `context.redactorMs` too it names the window the
  * time went into ({@link attributeWait}), including `context.hostMs`'s host
  * extensions — a caller that measured the first two but has no extensions to
- * charge reports that window as zero, which is a measurement and not a shrug. Without them the line says that it cannot
- * tell, rather than asserting an attribution nothing measured: a wall-clock
- * overrun on a loaded host is the common case, and blaming it on the sanitizer
- * sends the operator hunting a per-call cost that does not exist.
+ * charge reports that window as zero, which is a measurement and not a shrug.
+ * Such a caller is reported only when `cpuMs + redactorMs + hostMs` (an absent
+ * `hostMs` counting as 0) exceeds `thresholdMs`: a wall-clock overrun whose
+ * owned share is within the budget is the machine's and returns null, so the
+ * operator is never asked to report a cost the owner did not spend. Without the
+ * measurements the line says that it cannot tell, rather than asserting an
+ * attribution nothing measured: a wall-clock overrun on a loaded host is the
+ * common case, and blaming it on the sanitizer sends the operator hunting a
+ * per-call cost that does not exist.
  *
  * A CPU figure alone cannot pick a cause, so with only that the clause names
  * candidates and commits to none. A hook that blocks on a dead socket inside a

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

@@ -193,11 +193,14 @@ export function alertAcknowledged(sessionId?: string): boolean;
 /**
  * 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?: string): void;
+export function acknowledgeAlert(sessionId?: string): boolean;
 /**
  * The blocking ask. The heading states only that the scan did not finish clean:
  * the alert carries injection findings, unreadable targets, or a scanner fault,

package/types/claude-hooks/lib/redactor-client.d.mts

@@ -55,9 +55,9 @@ export function classifySocket(socketPath: string, deps?: {
 /**
  * Open one connection, send `request`, resolve with the parsed response object
  * (or null). Rejects on connect failure, a malformed/oversize/short frame, or an
- * {error} response — every one of which the caller turns into a fail-closed. A
+ * {error} response — every one of which the caller treats as a fault. A
  * socket present but not owned by us, and a request the protocol does not
- * accept, fail closed WITHOUT dialing (the error carries no errno, so
+ * accept, throw WITHOUT dialing (the error carries no errno, so
  * isRespawnable is false): we never dial into a squat, and an oversize request
  * is not mistaken for a dead daemon worth respawning.
  * @param {string} socketPath
@@ -105,7 +105,7 @@ export function waitForSocket(socketPath: string, { deadlineMs, stepMs, abandon
 /**
  * Redact `text` via the daemon. Returns the response object (`{text, found}` for
  * plain, `{text, pairs, found}` / `{unmappable}` for map) or null when nothing was
- * redacted (plain mode). Throws to fail closed when the text cannot be vetted.
+ * redacted (plain mode). Throws when the text cannot be vetted.
  *
  * `connect`/`spawn`/`waitForSocket` are injectable seams (default to the real
  * implementations) so callers can stub the daemon in-process. `deadline` is the

package/types/claude-hooks/lib/secret-annotate.d.mts

@@ -1,26 +1,20 @@
-/**
- * Regex matching `value` tolerating invisible chars spliced between its
- * characters (mirrors the engine's env-value regex). Code-point split so
- * an astral character is escaped whole, not as two surrogate halves — and the
- * `u` flag, which the astral `\u{…}` class members in {@link ENV_INVIS_RUN}
- * require.
- * Memoized per distinct value: {@link ENV_INVIS_RUN} renders ~435 code points
- * as ~4 KB of source and is joined at EVERY interior gap, so a 20-char secret
- * compiles a ~75 KB pattern — and `hasEnvBoundSecret` builds one per configured
- * var on every PostToolUse output. Env values are stable for the process's
- * lifetime, so the cache is bounded by the number of distinct values. Sharing an
- * instance is safe because the regex carries no `g`/`y` flag, hence no
- * `lastIndex` state to leak between calls.
- * @param {string} value
- * @returns {RegExp}
- */
-export function envValueRegex(value: string): RegExp;
 /**
  * True when tool output contains the literal value of a configured env-bound
  * secret. The shape-based secret hint can't match a prefix-less key or a host
  * credential, so the pre-gate must also fire on the value itself — otherwise
  * the engine's env-bound redaction never runs. Invisible-tolerant so a
  * value with spliced Cf chars (which the daemon still redacts) trips it too.
+ *
+ * Both sides are stripped and compared as substrings, which is exactly
+ * equivalent: the value's visible characters appear contiguously in the
+ * stripped text iff they appear in the original separated only by invisibles.
+ * It is linear and independent of the value's length — a regex with an
+ * invisible class at every gap grows ~4 KB per character, and a long secret (a
+ * PEM key) overflows V8's regex size limit and throws on every output.
+ *
+ * Callers pass post-Layer-1 text: terminal escapes are already gone, so a value
+ * split by one is contiguous here. Raw text spliced with an escape is not
+ * matched.
  * @param {string} text
  * @param {NodeJS.ProcessEnv} [env]
  * @returns {boolean}

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

@@ -11,6 +11,28 @@
  * @returns {string}
  */
 export function dropFingerprint(filePath: string, content: string, dropped?: string[]): string;
+/**
+ * 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: string, tool: unknown, toolInput: unknown): string;
+/**
+ * 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: string): boolean;
 /**
  * The confirm sentinel's path for one fingerprint. Predictable and
  * world-visible like the alert markers, hence the markerIsTrusted read.
@@ -50,15 +72,16 @@ export function gitTracked(filePath: string, spawn?: typeof spawnSync): boolean;
  * 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 function secretDropGuard(toolInput: {
     file_path?: unknown;
@@ -66,9 +89,10 @@ export function secretDropGuard(toolInput: {
 }, io: import("agent-sanitizer/rehydrate").RehydrateIo, opts?: {
     isTracked?: (filePath: string) => boolean;
     confirmSeen?: (fingerprint: string) => boolean;
-    recordConfirm?: (fingerprint: string) => void;
+    recordConfirm?: (fingerprint: string) => boolean;
 }): Promise<{
     deny: string;
+    fault?: string;
 } | null>;
 /**
  * Compose a Layer-4 rehydrator with this guard: for a Write the rehydrator
@@ -76,14 +100,41 @@ export function secretDropGuard(toolInput: {
  * 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]
  * @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>;
+/**
+ * True when a trusted, fresh confirm sentinel exists for `fingerprint`,
+ * 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 fingerprinted call the model already
+ * confirmed — and only within the TTL.
+ * @param {string} fingerprint
+ * @returns {boolean}
+ */
+export function consumeConfirm(fingerprint: string): boolean;
+/**
+ * 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: string): boolean;
 /** A confirm sentinel older than this is stale, not a confirmation. */
 export const CONFIRM_TTL_MS: number;
 /**
@@ -92,12 +143,29 @@ export const CONFIRM_TTL_MS: number;
  * 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.
+ * 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.
  */
-export type RehydrateResult = {
+export type RehydrateRewrite = {
     updatedInput: any;
     context: string;
-} | {
+};
+/**
+ * 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. 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.
+ */
+export type RehydrateResult = RehydrateRewrite | {
     deny: string;
+    fault?: string;
+    release?: RehydrateRewrite;
 } | null;
 import { spawnSync } from "node:child_process";