agent-sanitizer 2.68.0 → 2.69.0

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";

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

@@ -29,13 +29,14 @@
  * @param {boolean} [secretsOn]  the run's secret opt-in (decided once by
  *   buildPreToolUseResponse; a direct caller reads the env); only with it on
  *   does the context claim the restored bytes were redacted
- * @returns {{ updatedInput: any, context: string } | { deny: string } | null}
+ * @returns {{ updatedInput: any, context: string } | { deny: string, fault?: string } | null}
  */
 export function rehydrateLayer2(tool: string, toolInput: any, secretsOn?: boolean): {
     updatedInput: any;
     context: string;
 } | {
     deny: string;
+    fault?: string;
 } | null;
 /**
  * The declared stage chain after the gate. Every entry states the two properties
@@ -53,9 +54,12 @@ export function rehydrateLayer2(tool: string, toolInput: any, secretsOn?: boolea
  * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
  * @param {boolean} [secretsOn]  the run's secret opt-in (see
  *   buildPreToolUseResponse, which decides it once and passes it here)
+ * @param {FaultLedger} [ledger]  where a fault deny the open posture lets
+ *   through leaves its warning; required as soon as a stage reports a fault,
+ *   since a warning with nowhere to go would let the call through silently
  * @returns {import("./lib/layer-pipeline.mjs").Layer[]}
  */
-export function preToolUseLayers(rehydrate: ((tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>) | null, env?: NodeJS.ProcessEnv | Record<string, string | undefined>, secretsOn?: boolean): import("./lib/layer-pipeline.mjs").Layer[];
+export function preToolUseLayers(rehydrate: ((tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>) | null, env?: NodeJS.ProcessEnv | Record<string, string | undefined>, secretsOn?: boolean, ledger?: FaultLedger): import("./lib/layer-pipeline.mjs").Layer[];
 /**
  * Compose the five stages. Returns the `hookSpecificOutput` fields to emit, or
  * null for a clean no-op. Throws only if a stage's engine throws; the caller
@@ -79,9 +83,11 @@ export function buildPreToolUseResponse(input: any, rehydrate?: (tool: string, t
  * ToolCallEvent and returns a Verdict, so a non-Claude host can run the same
  * sanitization pipeline through its own adapter. The wired Claude CLI below
  * routes through this judge and renders the Verdict with the Claude adapter; on
- * any throw (a control-plane package-load failure included) it falls back to
- * hookFailureFields — a native response that needs no package — so the
- * caller's fault posture holds even when the adapter never loaded.
+ * any throw (a control-plane package-load failure, or an event the adapter
+ * could not classify) it falls back to hookFailureFields — a native response
+ * that needs no package — so the caller's fault posture holds even when the
+ * adapter never loaded. A host calling this directly renders its throws the
+ * same way.
  * @param {import("agent-control-plane-core").ToolCallEvent} event
  * @param {(tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>} [rehydrate]
  * @param {{
@@ -147,8 +153,8 @@ export function failClosedFields(parsedOk: boolean, err: unknown, opts?: {
 }): Record<string, unknown>;
 /**
  * True when a faulting PreToolUse call is the one case the OPEN posture must
- * still not pass: a write-shaped tool whose input carries a redaction
- * placeholder, matched by the real grammar (containsPlaceholder) so
+ * not pass on the first try: a write-shaped tool whose input carries a
+ * redaction placeholder, matched by the real grammar (containsPlaceholder) so
  * hint-prefixed prose such as `[REDACTED…]` is not mistaken for one. Such a
  * placeholder stands for a secret the sanitizer redacted out of the model's
  * view; with the sanitizer down, rehydration cannot translate it back, so
@@ -159,7 +165,7 @@ export function failClosedFields(parsedOk: boolean, err: unknown, opts?: {
  *
  * Deliberately NOT exhaustive over every clobber path: Bash can also write a
  * placeholder to disk (`>`, `tee`, `sed -i`, a heredoc), but command strings
- * mention "[REDACTED" benignly far too often for an ask to hold precision
+ * mention "[REDACTED" benignly far too often for a refusal to hold precision
  * there. That is an accepted gap, named in THREAT-MODEL.md's carve-out.
  * @param {unknown} input raw parsed PreToolUse payload (undefined if unparsed)
  * @returns {boolean}
@@ -172,8 +178,9 @@ export function hintedWriteFault(input: unknown): boolean;
  * fail-CLOSED verdict of {@link failClosedFields} when the caller set
  * AGENT_SANITIZER_FAIL_OPEN=0. The open default has ONE carve-out, declared in
  * this hook's fault policy below: a write-shaped call whose input carries a
- * `[REDACTED…]` placeholder asks instead of passing (see
- * {@link hintedWriteFault}) — pass `input` so the policy can see it.
+ * `[REDACTED…]` placeholder is refused once, and its exact re-issue proceeds
+ * with a warning (see {@link hintedWriteFault}) — pass `input` so the policy
+ * can see it.
  *
  * The posture covers this hook's own failures, whatever their cause. What it
  * does NOT cover is the verdict of a sanitizer that ran: a payload
@@ -239,6 +246,17 @@ export const PRE_TOOL_USE_MESSAGES: Readonly<{
     remedy: string;
 }>;
 export const REDACTION_HINT: "[REDACTED";
+/**
+ * What the stage table hands back besides the pipeline's own result: the
+ * warnings of fault denies the open posture let through (the pipeline drops a
+ * stage's note when the input is unchanged, and these calls proceed unchanged),
+ * and the re-issue confirmations they rode on, consumed only once the call is
+ * known to proceed.
+ */
+export type FaultLedger = {
+    warnings: string[];
+    released: string[];
+};
 /**
  * A host-supplied deny gate: given the PreToolUse input, the reason this call
  * must be blocked, or null to let the pipeline continue. Hosts use these for

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

@@ -2,8 +2,9 @@
  * Judge a normalized prompt-submit event. Agent-agnostic: consumes the
  * control-plane ToolCallEvent and returns a Verdict, so the same prompt gate
  * renders through any agent adapter, not just Claude's. Throws (into the
- * calling hook's catch) when the sanitizer package never loaded, so a prompt it
- * cannot classify takes the hook's fault posture rather than a silent ALLOW.
+ * calling hook's catch) when the sanitizer package never loaded or the payload
+ * is no recognizable event, so a prompt it cannot classify takes the hook's
+ * fault posture rather than a silent ALLOW.
  * @param {import("agent-control-plane-core").ToolCallEvent} event
  * @param {((s: string) => string) | null} [strip]  the ANSI stripper (defaults
  *   to the package's stripAnsiFully; injectable so the fault path is testable)

package/types/claude-hooks/scan-invisible-chars.d.mts

@@ -28,9 +28,9 @@ export function scanProject(dir?: string): {
     absent: string[];
 };
 /**
- * The report for targets the scan could not read. Rendered into the alert the
- * PreToolUse gate surfaces, so an incomplete scan reaches the operator as a
- * checkpoint rather than as silence.
+ * The report for targets the scan could not read: a SessionStart warning under
+ * the open posture, and the alert the PreToolUse gate surfaces under the closed
+ * one — either way an incomplete scan reaches the operator rather than silence.
  * @param {Array<{file: string, reason: string}>} skipped
  * @returns {string}
  */

package/types/rehydrate.d.mts

@@ -8,6 +8,12 @@
  * 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.
@@ -15,7 +21,7 @@
  * @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 function rehydrateRedacted(tool: string, toolInput: any, io: RehydrateIo, { hint }?: {
     hint?: string;
@@ -24,6 +30,7 @@ export function rehydrateRedacted(tool: string, toolInput: any, io: RehydrateIo,
     context: string;
 } | {
     deny: string;
+    fault?: string;
 } | null>;
 export const DEFAULT_HINT: "[REDACTED";
 /**