agent-sanitizer 2.60.0 → 2.60.2

package/types/claude-hooks/lib/reveal.d.mts

@@ -23,9 +23,12 @@ export function sweepStaleReveals(): void;
  * can precompute it and pre-plant a symlink there to redirect this write onto a
  * victim file — writeFileNoFollow refuses that instead of following it.
  * @param {string} content
+ * @param {boolean} [secretsRedacted]  whether the caller redacted `content`
+ *   before this call; only then does the hint claim it (with the secret layer
+ *   off the bytes are stored verbatim)
  * @returns {string | null}
  */
-export function persistReveal(content: string): string | null;
+export function persistReveal(content: string, secretsRedacted?: boolean): string | null;
 /**
  * The store path for one Layer-2 splice's original bytes, keyed by the
  * placeholder key. Throws on a malformed key (fail loud: every caller extracts
@@ -42,7 +45,14 @@ export function spanPath(key: string): string;
  * symlink-refusingly (O_EXCL) because the path is content-addressed — an
  * attacker who chose the page bytes can precompute it and pre-plant a symlink.
  * Content-addressed dedupe: an existing entry (same key = same raw original)
- * is left in place and counts as success. Returns true when the span is on
+ * is left in place and counts as success — EXCEPT when `secretsRedacted` is
+ * set and the entry differs from `content`. The key is minted from the RAW
+ * original, so a span first stored with the secret opt-in off holds the raw
+ * bytes under the very key a later opted-in run computes; keeping it would
+ * restore a raw secret into a write whose notice says secrets were redacted
+ * before storage. The opted-in write therefore replaces a differing entry. The
+ * reverse (opt-in off meeting a redacted entry) keeps the entry: redacted is
+ * the safe direction. Returns true when the span is on
  * disk (written now or already there); false on any failure — non-fatal by
  * contract, exactly like a failed reveal write (the splice already protected
  * the output; a later rehydration of this key fails CLOSED with a deny).
@@ -53,9 +63,11 @@ export function spanPath(key: string): string;
  * NAME, not an integrity check.
  * @param {string} key
  * @param {string} content the splice's original, redacted BEFORE this call
+ * @param {boolean} [secretsRedacted] whether `content` went through the secret
+ * redactor (the run's opt-in); only then may it replace a differing entry
  * @returns {boolean}
  */
-export function persistSpan(key: string, content: string): boolean;
+export function persistSpan(key: string, content: string, secretsRedacted?: boolean): boolean;
 /**
  * The stored original for one Layer-2 placeholder key, or null when no span is
  * stored (or the store is unusable). The open refuses symlinks (O_NOFOLLOW):

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

@@ -30,11 +30,15 @@ export function confirmMarkerPath(fingerprint: string): string;
  */
 export function sweepStaleConfirms(): void;
 /**
- * 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.
+ * Whether git tracks `filePath`, with every probe failure on the skip side the
+ * module doc declares. Exit 0 is tracked and exit 1 untracked. Exit 128 is
+ * either "not a repository" — no git recovery exists, so the guard applies — or
+ * a repository git could not read (a corrupt index, a permission error), which
+ * says nothing about the file; a second probe asks git which, reading its
+ * printed answer (`false` inside a bare repository or a `.git` directory is
+ * also exit 0, and also has no recovery path). A spawn-level
+ * failure (no git binary) or any other status also means we cannot tell —
+ * report tracked so the guard skips rather than denying on broken tooling.
  * @param {string} filePath
  * @param {typeof spawnSync} [spawn]
  * @returns {boolean}

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

@@ -4,11 +4,12 @@
  * removed #<key>]` placeholders (copied from sanitized tool output) has each
  * one restored to the stored original bytes from the reveal store's span files.
  *
- * SECURITY invariant: the stored span content was REDACTED before persistence
- * (sanitize-output runs strict web-ingress redaction on each splice original
- * before persistSpan), so this rehydration can never write a raw secret — the
- * worst it can restore is `[REDACTED…]` placeholder text standing where the
- * secret was, which the on-disk tripwire then flags on later Reads.
+ * SECURITY invariant, with the secret layer on: the stored span content was
+ * REDACTED before persistence (sanitize-output runs strict web-ingress
+ * redaction on each splice original before persistSpan), so this rehydration
+ * can never write a raw secret — the worst it can restore is `[REDACTED…]`
+ * placeholder text, which the on-disk tripwire then flags on later Reads. With
+ * the layer off, spans are stored verbatim and the context claims nothing.
  *
  * Composition with the secret rehydrator: this runs AFTER it (a later terminal
  * layer), and the two grammars are disjoint — a Layer-2 placeholder never
@@ -25,51 +26,62 @@
  * edits / notebook JSON cannot be rehydrated).
  * @param {string} tool
  * @param {any} toolInput
+ * @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}
  */
-export function rehydrateLayer2(tool: string, toolInput: any): {
+export function rehydrateLayer2(tool: string, toolInput: any, secretsOn?: boolean): {
     updatedInput: any;
     context: string;
 } | {
     deny: string;
 } | null;
 /**
- * The declared layer chain, layers 2-4. Every entry states the two properties
+ * The declared stage chain after the gate. Every entry states the two properties
  * the driver reasons about — whether it ERASES code points another layer reads,
  * and whether its own decision is SKIP-BASED and therefore invalidated by such
  * an erasure — so the confusable fold's ordering precondition is enforced by the
  * table instead of restated as a comment.
  *
- * Layer 3 is dropped from the table (not merely skipped at run time) when
+ * The authored-content stage is dropped from the table (not merely skipped) when
  * AGENT_SANITIZER_OUTPUT_DISABLED=1, so the driver sees the chain that will
  * actually run: with no erasing layer left after the fold there is no fixed
- * point to reach and no extra pass to pay for.
- * @param {(tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>} rehydrate
+ * point to reach and no extra pass to pay for. A null `rehydrate` drops the
+ * secret rehydrator the same way.
+ * @param {((tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>) | null} rehydrate
  * @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)
  * @returns {import("./lib/layer-pipeline.mjs").Layer[]}
  */
-export function preToolUseLayers(rehydrate: (tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>, env?: NodeJS.ProcessEnv | Record<string, string | undefined>): 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[];
 /**
- * Compose the four protections. Returns the `hookSpecificOutput` fields to
- * emit, or null for a clean no-op. Throws only if a layer's engine throws; the
- * caller fails closed (ask) on any throw. Every exit routes through emitTraced.
+ * 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
+ * then applies this hook's fault posture (open by default — see
+ * hookFailureFields). Every exit routes through emitTraced.
  * @param {any} input parsed PreToolUse event
  * @param {(tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>} [rehydrate]
- * injectable for tests; the default binds the real redactor-daemon io (the
- * layer reads the target file and maps secrets through the daemon)
+ * injectable for tests, and then run whatever the secret opt-in says; the
+ * default binds the real redactor-daemon io (the layer reads the target file
+ * and maps secrets through the daemon) and runs only with the opt-in on
  * @param {import("./lib/trace.mjs").TraceFn} [sink]  where engagement is
  * announced; a host with its own trace channel passes its sink (see lib/trace.mjs)
+ * @param {import("./lib/layer-pipeline.mjs").Layer[]} [layers]  the stage table,
+ * injectable so a test can drive one the shipped stages never produce (an
+ * oscillating stage); defaults to {@link preToolUseLayers} for this call
  * @returns {Promise<Record<string, unknown> | null>}
  */
-export function buildPreToolUseResponse(input: any, rehydrate?: (tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>, sink?: import("./lib/trace.mjs").TraceFn): Promise<Record<string, unknown> | null>;
+export function buildPreToolUseResponse(input: any, rehydrate?: (tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>, sink?: import("./lib/trace.mjs").TraceFn, layers?: import("./lib/layer-pipeline.mjs").Layer[]): Promise<Record<string, unknown> | null>;
 /**
- * Agent-agnostic judge over the four protections: consumes a control-plane
+ * Agent-agnostic judge over the five stages: consumes a control-plane
  * 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
- * failClosedFields — a native response that needs no package — so the
- * fail-closed posture holds even when the adapter never loaded.
+ * hookFailureFields — a native response that needs no package — so the
+ * caller's fault posture holds even when the adapter never loaded.
  * @param {import("agent-control-plane-core").ToolCallEvent} event
  * @param {(tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>} [rehydrate]
  * @param {{
@@ -135,14 +147,15 @@ 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 the
- * redaction-placeholder prefix. Such a placeholder stands for a secret the
- * sanitizer redacted out of the model's view; with the sanitizer down,
- * rehydration cannot translate it back, so letting the call through would
- * persist the literal placeholder text over the real secret on disk — a
- * destructive clobber, not a missed scan. Package-free by construction (a Set
- * lookup and a substring test on the already-parsed payload), so it holds when
- * the failure IS the missing package.
+ * still not pass: 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
+ * letting the call through would persist the literal placeholder text over the
+ * real secret on disk — a destructive clobber, not a missed scan.
+ * Package-free by construction (a Set lookup and a walk of the already-parsed
+ * payload), so it holds when the failure IS the missing package.
  * @param {unknown} input raw parsed PreToolUse payload (undefined if unparsed)
  * @returns {boolean}
  */

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

@@ -7,8 +7,8 @@
  * never WHETHER their result is applied.
  *
  * A callback that throws is not caught here. That is deliberate: the throw lands
- * in the CLI's fail-closed catch and the tool output is suppressed, so a broken
- * extension cannot degrade into showing unvetted output.
+ * in the CLI's catch like any other sanitizer fault, so a broken extension gets
+ * exactly the posture the operator chose (emitHookFailure) and no quieter one.
  *
  * These are NOT the Layer-5 injection-filter seam and do not inherit its
  * delete-only, closed-enum restriction. (Its identifier is deliberately unspoken
@@ -58,11 +58,13 @@
  * @param {{remainingMs: () => number}} [deadline] shared wall-clock budget across
  *   all leaves of one hook run; a direct caller gets a fresh full budget
  * @param {SanitizeExtensions} [ext]
+ * @param {boolean} [secretsOn]  the secret opt-in, decided ONCE per hook run by
+ *   {@link evaluateToolOutput} and threaded down; a direct caller reads the env
  * @returns {Promise<{ cleaned: string, warnings: string[], notes: string[], modified: boolean, sgrNote: boolean, reveal?: string, splices?: Array<{ placeholder: string, original: string }> }>}
  */
 export function sanitizeText(text: string, toolName: string, deadline?: {
     remainingMs: () => number;
-}, ext?: SanitizeExtensions): Promise<{
+}, ext?: SanitizeExtensions, secretsOn?: boolean): Promise<{
     cleaned: string;
     warnings: string[];
     notes: string[];
@@ -104,6 +106,7 @@ export function sanitizeText(text: string, toolName: string, deadline?: {
  *   after `notes` for the same positional-compatibility reason
  * @param {string} [path]  dotted location of `value` within the tool output,
  *   used only to name a key collision's location in its warning
+ * @param {boolean} [secretsOn]  the secret opt-in (see {@link sanitizeText})
  * @returns {Promise<{ value: any, modified: boolean, sgrNote: boolean }>}
  */
 export function sanitizeValue(value: any, toolName: string, warnings: string[], reveals?: string[], deadline?: {
@@ -111,7 +114,7 @@ export function sanitizeValue(value: any, toolName: string, warnings: string[],
 }, ext?: SanitizeExtensions, notes?: string[], splices?: Array<{
     placeholder: string;
     original: string;
-}>, path?: string): Promise<{
+}>, path?: string, secretsOn?: boolean): Promise<{
     value: any;
     modified: boolean;
     sgrNote: boolean;
@@ -235,7 +238,7 @@ export function evaluateToolOutput(input: any, ext?: SanitizeExtensions): Promis
  * {@link evaluateToolOutput} already returns those contract fields (or null),
  * so the judge only stamps the `allow` decision onto them — no native-envelope
  * translation. Throws only if a layer engine throws (or on an UNKNOWN event);
- * the CLI fails closed on any throw.
+ * the CLI applies this hook's fault posture to any throw (emitHookFailure).
  * @param {import("agent-control-plane-core").ToolCallEvent} event
  * @param {SanitizeExtensions} [ext]
  * @returns {Promise<import("agent-control-plane-core").Verdict>}
@@ -247,9 +250,9 @@ export function judgeSanitizeOutput(event: import("agent-control-plane-core").To
  * omits the field is a PostToolUse call by construction. The claude adapter
  * extracts `tool_response` (this hook's actual input) ONLY for a PostToolUse
  * event; without this default a field-less but legitimate payload would parse as
- * UNKNOWN, {@link judgeSanitizeOutput} would throw, and the CLI would fail closed
- * (suppress) on real tool output. A payload carrying a DIFFERENT event name is
- * left untouched, so the judge's UNKNOWN guard still fails closed on a genuinely
+ * UNKNOWN, {@link judgeSanitizeOutput} would throw, and the CLI would take the
+ * fault posture on real tool output. A payload carrying a DIFFERENT event name
+ * is left untouched, so the judge's UNKNOWN guard still fires on a genuinely
  * unrecognized event.
  * @param {unknown} input  the raw stdin payload
  * @returns {unknown}
@@ -285,8 +288,8 @@ export const ON_DISK_PLACEHOLDER_WARNING: string;
  * never WHETHER their result is applied.
  *
  * A callback that throws is not caught here. That is deliberate: the throw lands
- * in the CLI's fail-closed catch and the tool output is suppressed, so a broken
- * extension cannot degrade into showing unvetted output.
+ * in the CLI's catch like any other sanitizer fault, so a broken extension gets
+ * exactly the posture the operator chose (emitHookFailure) and no quieter one.
  *
  * These are NOT the Layer-5 injection-filter seam and do not inherit its
  * delete-only, closed-enum restriction. (Its identifier is deliberately unspoken

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

@@ -2,12 +2,11 @@
  * 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 — this hook is
- * the only defense on user input, so a prompt it cannot classify must block,
- * never pass through.
+ * 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.
  * @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 fail-closed path is testable)
+ *   to the package's stripAnsiFully; injectable so the fault path is testable)
  * @param {Partial<typeof USER_PROMPT_MESSAGES>} [overrides]  reason overrides,
  *   merged over the defaults so a partial table can never leave a field unset
  * @returns {import("agent-control-plane-core").Verdict}
@@ -26,7 +25,7 @@ export function judgeSanitizeUserPrompt(event: import("agent-control-plane-core"
  *   env?: NodeJS.ProcessEnv | Record<string, string | undefined>,
  * }} [opts]
  *   `strip` is the ANSI stripper (defaults to the package's stripAnsiFully;
- *   injectable so the fail-closed path is testable); `overrides` are reason
+ *   injectable so the fault path is testable); `overrides` are reason
  *   overrides, merged over the defaults so a partial table can never leave a field
  *   unset; `trace` is where engagement is announced, for a host with its own trace
  *   channel (see lib/trace.mjs); `env` is the failure-posture source (see

package/types/html.d.mts

@@ -20,19 +20,6 @@ export function isHiddenOpen(htmlValue: string): string | null;
  * @returns {string | null}
  */
 export function closingTagName(htmlValue: string): string | null;
-/**
- * The keyed, content-addressed placeholder for one Layer-2 splice:
- * `[hidden HTML removed #<key>]` / `[HTML comment removed #<key>]`, where
- * `<key>` is the first 12 lowercase-hex chars of sha256 over the UTF-8
- * encoding of the ORIGINAL spliced text. Content-addressed on purpose:
- * identical spliced content yields the identical placeholder, so a rehydrator
- * can match placeholder → original by key alone, and duplicated content never
- * produces conflicting keys.
- * @param {SpliceKind} kind
- * @param {string} original the exact text the splice removed
- * @returns {string}
- */
-export function layer2Placeholder(kind: SpliceKind, original: string): string;
 /**
  * Replace each range of `text` with its kind's keyed placeholder, preserving
  * every byte outside the ranges verbatim. Overlapping/nested ranges are merged
@@ -169,16 +156,8 @@ export function detectConfusableHosts(text: string): Array<{
     description: string;
 }> | null;
 export const REPORTED_TAGS: Set<string>;
-/**
- * The single grammar definition for keyed Layer-2 placeholders — the exact
- * output of {@link layer2Placeholder}, capture group 1 = the key. Global so
- * callers can scan a document for every placeholder; reset `lastIndex` (or
- * use `matchAll`) between uses.
- */
-export const LAYER2_PLACEHOLDER_RE: RegExp;
 export const HIDDEN_PLACEHOLDER: "[hidden HTML removed";
 export const COMMENT_PLACEHOLDER: "[HTML comment removed";
-export const UNPARSEABLE_PLACEHOLDER: "[HTML unparseable \u2014 withheld]";
 export const DATA_URI_LENGTH_THRESHOLD: 4096;
 export type CollectedUrl = {
     url: string;
@@ -213,4 +192,7 @@ import { MD_LINK_HINT } from "./gates.mjs";
 import { SECRET_HINT } from "./gates.mjs";
 import { SECRET_HINT_EXT } from "./gates.mjs";
 import { matchesSecretHint } from "./gates.mjs";
-export { HTML_TAG_PRESENT, MD_LINK_HINT, SECRET_HINT, SECRET_HINT_EXT, matchesSecretHint };
+import { layer2Placeholder } from "./layer2-placeholder.mjs";
+import { LAYER2_PLACEHOLDER_RE } from "./layer2-placeholder.mjs";
+import { UNPARSEABLE_PLACEHOLDER } from "./layer2-placeholder.mjs";
+export { HTML_TAG_PRESENT, MD_LINK_HINT, SECRET_HINT, SECRET_HINT_EXT, matchesSecretHint, layer2Placeholder, LAYER2_PLACEHOLDER_RE, UNPARSEABLE_PLACEHOLDER };

package/types/layer2-placeholder.d.mts

@@ -0,0 +1,21 @@
+/**
+ * The keyed, content-addressed placeholder for one Layer-2 splice:
+ * `[hidden HTML removed #<key>]` / `[HTML comment removed #<key>]`, where
+ * `<key>` is the first 12 lowercase-hex chars of sha256 over the UTF-8
+ * encoding of the ORIGINAL spliced text. Content-addressed on purpose:
+ * identical spliced content yields the identical placeholder, so a rehydrator
+ * can match placeholder → original by key alone, and duplicated content never
+ * produces conflicting keys.
+ * @param {"comment" | "hidden"} kind
+ * @param {string} original the exact text the splice removed
+ * @returns {string}
+ */
+export function layer2Placeholder(kind: "comment" | "hidden", original: string): string;
+/**
+ * The single grammar definition for keyed Layer-2 placeholders — the exact
+ * output of {@link layer2Placeholder}, capture group 1 = the key. Global so
+ * callers can scan a document for every placeholder; reset `lastIndex` (or
+ * use `matchAll`) between uses.
+ */
+export const LAYER2_PLACEHOLDER_RE: RegExp;
+export const UNPARSEABLE_PLACEHOLDER: "[HTML unparseable \u2014 withheld]";

package/types/src/layer2-placeholder.d.mts

@@ -0,0 +1,21 @@
+/**
+ * The keyed, content-addressed placeholder for one Layer-2 splice:
+ * `[hidden HTML removed #<key>]` / `[HTML comment removed #<key>]`, where
+ * `<key>` is the first 12 lowercase-hex chars of sha256 over the UTF-8
+ * encoding of the ORIGINAL spliced text. Content-addressed on purpose:
+ * identical spliced content yields the identical placeholder, so a rehydrator
+ * can match placeholder → original by key alone, and duplicated content never
+ * produces conflicting keys.
+ * @param {"comment" | "hidden"} kind
+ * @param {string} original the exact text the splice removed
+ * @returns {string}
+ */
+export function layer2Placeholder(kind: "comment" | "hidden", original: string): string;
+/**
+ * The single grammar definition for keyed Layer-2 placeholders — the exact
+ * output of {@link layer2Placeholder}, capture group 1 = the key. Global so
+ * callers can scan a document for every placeholder; reset `lastIndex` (or
+ * use `matchAll`) between uses.
+ */
+export const LAYER2_PLACEHOLDER_RE: RegExp;
+export const UNPARSEABLE_PLACEHOLDER: "[HTML unparseable \u2014 withheld]";