agent-sanitizer 2.30.0 → 2.31.0

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

@@ -1,11 +1,28 @@
 /**
- * Depth-capped walk: does any string in `value` carry placeholder-shaped text?
- * The cap fails OPEN (deeper content is unseen) — every caller feeds a
+ * The Layer-2 placeholder keys in `text`, in document order (duplicates kept —
+ * callers dedupe when they need to). matchAll clones the global regex, so no
+ * lastIndex state leaks between calls.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function layer2Keys(text: string): string[];
+/**
+ * Every distinct Layer-2 placeholder key anywhere in `value` — the deep-walk
+ * twin of {@link layer2Keys}, with the same depth cap (fail OPEN: an advisory
+ * miss costs one line, never a mangled input) as {@link containsPlaceholder}.
+ * @param {unknown} value
+ * @param {number} [depth]
+ * @returns {string[]}
+ */
+export function layer2KeysIn(value: unknown, depth?: number): string[];
+/**
+ * Depth-capped walk: does any string in `value` carry secret-placeholder-shaped
+ * text? The cap fails OPEN (deeper content is unseen) — every caller feeds a
  * context-only advisory, so a miss costs one line, never a mangled input.
  *
  * Kept alongside {@link collectPlaceholders} rather than expressed in terms of
- * it: this one short-circuits on the first hit and ignores the Layer-2 grammar,
- * which is what the PostToolUse on-disk tripwire wants on every Read.
+ * it: this one short-circuits on the first hit and ignores the Layer-2
+ * grammar, which is what the PostToolUse on-disk tripwire wants on every Read.
  * @param {unknown} value
  * @param {number} [depth]
  * @returns {boolean}
@@ -19,8 +36,9 @@ export function containsPlaceholder(value: unknown, depth?: number): boolean;
 /**
  * Depth-capped walk collecting every distinct placeholder token in `value`,
  * split by grammar: `secret` for the redaction grammar (PLACEHOLDER_RE),
- * `layer2` for the splice markers. Same cap and fail-OPEN posture as
- * {@link containsPlaceholder} — the consumer is a context-only advisory.
+ * `layer2` for the keyed splice placeholders plus the un-keyed unparseable
+ * marker. Same cap and fail-OPEN posture as {@link containsPlaceholder} — the
+ * consumers are context-only advisories.
  * @param {unknown} value
  * @returns {{ secret: FoundPlaceholder[], layer2: FoundPlaceholder[] }}
  */
@@ -30,30 +48,44 @@ export function collectPlaceholders(value: unknown): {
 };
 /**
  * Advisory context for a tool call OUTSIDE the rehydrated set (Bash, MCP
- * tools, anything unknown) whose input carries placeholder-shaped text, or
+ * tools, anything unknown) whose input carries SECRET placeholder text, or
  * null. Rehydration only re-anchors Edit/Write; every other write path — a
  * shell heredoc, `sed -i`, an MCP body field — persists the literal
- * placeholder. The advisory names each exact token, the field carrying it,
- * and the recovery path per grammar. It cannot tell a write from a read
- * (`grep` for a placeholder is legitimate), so it is deliberately a NOTE, not
- * a verdict: a false positive costs a few sentences of context, never a
- * blocked call or a mangled input.
+ * placeholder and destroys the secret it stands for. The advisory names each
+ * exact token, the field carrying it, and the recovery path. It cannot tell a
+ * write from a read (`grep` for a placeholder is legitimate), so it is
+ * deliberately a NOTE, not a verdict: a false positive costs a few sentences
+ * of context, never a blocked call or a mangled input.
  *
- * Direct substitution into non-shell tool inputs was evaluated and rejected —
- * this stays an advisory, with no per-tool rehydration allowlist:
- * - Secret placeholders: substituting the real secret into an MCP body field
- *   (a PR body, a comment) would PUBLISH the secret to an external service —
- *   exfiltration by construction — and PreToolUse has no placeholder→secret
- *   map without a named owning file anyway.
- * - Layer-2 markers: the markers are un-keyed, so marker→original is
- *   unrecoverable here (the reveal store is addressed by the hash of the full
- *   pre-splice text), and blind re-insertion would re-publish hidden
- *   untrusted content verbatim.
+ * Direct substitution into non-shell tool inputs was evaluated and rejected:
+ * substituting the real secret into an MCP body field (a PR body, a comment)
+ * would PUBLISH the secret to an external service — exfiltration by
+ * construction — and PreToolUse has no placeholder→secret map without a named
+ * owning file anyway.
  * @param {string} tool
  * @param {unknown} toolInput
  * @returns {string | null}
  */
 export function placeholderNotice(tool: string, toolInput: unknown): string | null;
+/**
+ * The Layer-2 twin of {@link placeholderNotice}: advisory context for a tool
+ * call OUTSIDE the rehydrated set whose input carries Layer-2 splice
+ * placeholders, or null. Rehydration restores keyed placeholders to the stored
+ * (already-redacted) original only on the Edit/Write path; a shell heredoc,
+ * `sed -i`, or an MCP body field persists the placeholder text literally.
+ * Deliberately a NOTE, not a verdict, for the same cannot-tell-write-from-read
+ * reason as the secret advisory — and it names the span file path(s) where the
+ * original bytes live so the model can Read one instead of guessing.
+ *
+ * Kept separate from {@link placeholderNotice}, rather than folded into it, so
+ * that the call site's secret-opt-in gate (with secrets off, `[REDACTED]`-
+ * shaped text is ordinary prose) cannot also suppress the Layer-2 advisory:
+ * Layer 2 splices regardless of the secret opt-in.
+ * @param {string} tool
+ * @param {unknown} toolInput
+ * @returns {string | null}
+ */
+export function layer2PlaceholderNotice(tool: string, toolInput: unknown): string | null;
 export const PLACEHOLDER_LABEL_CHARS: "A-Za-z0-9 ()._-";
 /**
  * Matches exactly the placeholder text the canonical redactor can emit:
@@ -63,14 +95,28 @@ export const PLACEHOLDER_LABEL_CHARS: "A-Za-z0-9 ()._-";
  */
 export const PLACEHOLDER_RE: RegExp;
 /**
- * The Layer-2 splice markers, mirrored from src/html.mjs
- * (COMMENT_PLACEHOLDER / HIDDEN_PLACEHOLDER / UNPARSEABLE_PLACEHOLDER) for the
- * bundle-pin reason in the module doc. They are fixed, un-keyed strings: the
- * marker itself cannot say WHICH splice it came from — the original text lives
- * in the content-addressed reveal sidecar (lib/reveal.mjs) whose exact path
- * the sanitize-time warning named.
+ * The keyed Layer-2 splice placeholder grammar — `[hidden HTML removed #<key>]`
+ * / `[HTML comment removed #<key>]`, capture group 1 = the 12-lowercase-hex key
+ * (the first 12 hex chars of sha256 over the RAW spliced original). Mirrored
+ * from the single producer in the engine (`src/html.mjs`,
+ * `LAYER2_PLACEHOLDER_RE`) for the same pinned-registry reason as
+ * PLACEHOLDER_RE above.
+ *
+ * Deliberately DISJOINT from the secret-redaction grammar: a Layer-2
+ * placeholder never matches PLACEHOLDER_RE (no `[REDACTED` prefix) and a
+ * secret placeholder never matches this — so the secret rehydrator and the
+ * Layer-2 rehydrator can compose without either touching the other's tokens.
+ */
+export const LAYER2_PLACEHOLDER_RE: RegExp;
+/**
+ * The one Layer-2 marker that carries no key, mirrored from src/html.mjs
+ * (UNPARSEABLE_PLACEHOLDER) for the bundle-pin reason above. The fail-closed
+ * path withholds the WHOLE output, so there is no per-splice original to key:
+ * the pre-splice text lives in the reveal sidecar (lib/reveal.mjs) whose exact
+ * path the sanitize-time warning named. Not round-trippable — the advisory
+ * points at the sidecar instead of a span file.
  */
-export const LAYER2_PLACEHOLDERS: readonly string[];
+export const UNPARSEABLE_MARKER: "[HTML unparseable \u2014 withheld]";
 /**
  * One found token: the exact placeholder text and the dotted field path of the
  * FIRST input field carrying it (empty for a bare string input).

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

@@ -17,6 +17,45 @@ export function revealDir(): string;
  * @returns {string | null}
  */
 export function persistReveal(content: string): 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
+ * the key from LAYER2_PLACEHOLDER_RE, whose capture group can only yield a
+ * valid key, so a bad one here is a caller bug, not input).
+ * @param {string} key
+ * @returns {string}
+ */
+export function spanPath(key: string): string;
+/**
+ * Persist one Layer-2 splice's (already-redacted) original under its
+ * placeholder key, with the same hardened treatment as {@link persistReveal}:
+ * the dir must be a private uid-owned 0700 directory, and the file is created
+ * 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
+ * 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).
+ *
+ * The KEY is the caller's, extracted from the placeholder — never recomputed
+ * from `content`: the key was minted from the RAW original, and `content` is
+ * the redacted original, so a recomputed hash would not match. The key is a
+ * NAME, not an integrity check.
+ * @param {string} key
+ * @param {string} content the splice's original, redacted BEFORE this call
+ * @returns {boolean}
+ */
+export function persistSpan(key: string, content: string): 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):
+ * the path is precomputable, so a planted symlink must not let this read pull
+ * an arbitrary file's bytes into a rehydrated write.
+ * @param {string} key
+ * @returns {string | null}
+ */
+export function readSpan(key: string): string | null;
 /**
  * True when this PostToolUse event is a Read of a reveal sidecar file, so its
  * output must be marked untrusted even though Read is otherwise a trusted local
@@ -29,5 +68,12 @@ export function persistReveal(content: string): string | null;
  * @returns {boolean}
  */
 export function isRevealRead(toolName: string, toolInput: any): boolean;
+/**
+ * The model-facing line telling it Layer-2 placeholders round-trip: pushed once
+ * per tool output whose splices were persisted, so the model knows to leave the
+ * keyed placeholders byte-for-byte intact when copying text back into a file —
+ * Edit/Write restore each to the stored original automatically.
+ */
+export const SPAN_ROUNDTRIP_NOTICE: string;
 /** Envelope prepended to a reveal-file Read so its bytes are framed as untrusted. */
 export const REVEAL_READ_ENVELOPE: string;

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

@@ -1,3 +1,38 @@
+/**
+ * Layer-2 placeholder rehydration on the write path: an Edit `new_string` or a
+ * Write `content` carrying `[hidden HTML removed #<key>]` / `[HTML comment
+ * 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.
+ *
+ * Composition with the secret rehydrator: this runs AFTER it (a later terminal
+ * layer), and the two grammars are disjoint — a Layer-2 placeholder never
+ * matches the `[REDACTED…]` grammar and vice versa — so neither can touch the
+ * other's tokens. Running second also means a restored original that contains
+ * `[REDACTED…]` text is never re-fed to the secret resolver (which would deny
+ * it as a foreign placeholder).
+ *
+ * `old_string` is deliberately NOT rehydrated: a Layer-2 placeholder there
+ * exists in the model's view of PRIOR TOOL OUTPUT, not on disk, so unless the
+ * file literally contains the placeholder text, Edit's ordinary no-match
+ * failure is the right outcome — no re-anchoring. MultiEdit/NotebookEdit with a
+ * Layer-2 placeholder are denied (parity with the secret path: sequential
+ * edits / notebook JSON cannot be rehydrated).
+ * @param {string} tool
+ * @param {any} toolInput
+ * @returns {{ updatedInput: any, context: string } | { deny: string } | null}
+ */
+export function rehydrateLayer2(tool: string, toolInput: any): {
+    updatedInput: any;
+    context: string;
+} | {
+    deny: string;
+} | null;
 /**
  * The declared layer chain, layers 2-4. Every entry states the two properties
  * the driver reasons about — whether it ERASES code points another layer reads,

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

@@ -50,13 +50,15 @@
  * the HTML rewrite (Layer 2) and the exfil-URL scan (Layer 3), the injected
  * secret redactor (Layer 4), and the display-only-SGR carve-out. `reveal` carries
  * the seam's pre-Layer-2 text when the HTML splice removed anything, for the
- * orchestrator to persist.
+ * orchestrator to persist; `splices` is its per-placeholder twin (each
+ * `original` already vetted by the seam's exit redaction, withheld entries
+ * dropped there), for the orchestrator's per-key span persistence.
  * @param {string} text
  * @param {string} toolName  gates the SGR carve-out and the untrusted-ingress passes
  * @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]
- * @returns {Promise<{ cleaned: string, warnings: string[], notes: string[], modified: boolean, sgrNote: boolean, reveal?: string }>}
+ * @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;
@@ -67,6 +69,10 @@ export function sanitizeText(text: string, toolName: string, deadline?: {
     modified: boolean;
     sgrNote: boolean;
     reveal?: string;
+    splices?: Array<{
+        placeholder: string;
+        original: string;
+    }>;
 }>;
 /**
  * Sanitize every string leaf of a tool-output value, preserving its shape.
@@ -82,6 +88,9 @@ export function sanitizeText(text: string, toolName: string, deadline?: {
  * `reveals` accumulates each leaf's pre-Layer-2 text (when the HTML splice
  * removed something) for the orchestrator to persist, and `notes` the leaves'
  * NOTE-severity findings — same mutated-accumulator shape as `warnings`.
+ * `splices` accumulates each leaf's Layer-2 placeholder→original pairs (the
+ * per-key twin of `reveals`, already vetted by the seam) for the orchestrator's
+ * span persistence — same mutated-accumulator shape again.
  * @param {any} value
  * @param {string} toolName
  * @param {string[]} warnings
@@ -91,13 +100,18 @@ export function sanitizeText(text: string, toolName: string, deadline?: {
  * @param {SanitizeExtensions} [ext]
  * @param {string[]} [notes]  appended last so an existing caller's positional
  *   arguments keep their meaning
+ * @param {Array<{ placeholder: string, original: string }>} [splices]  appended
+ *   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
  * @returns {Promise<{ value: any, modified: boolean, sgrNote: boolean }>}
  */
 export function sanitizeValue(value: any, toolName: string, warnings: string[], reveals?: string[], deadline?: {
     remainingMs: () => number;
-}, ext?: SanitizeExtensions, notes?: string[], path?: string): Promise<{
+}, ext?: SanitizeExtensions, notes?: string[], splices?: Array<{
+    placeholder: string;
+    original: string;
+}>, path?: string): Promise<{
     value: any;
     modified: boolean;
     sgrNote: boolean;

package/types/gates.d.mts

@@ -31,9 +31,11 @@ export function matchesSecretHint(text: string): boolean;
  * Matches any HTML tag-like construct: opening tags, closing tags (`</`),
  * comments and bogus declarations (`<!`), and processing instructions / bogus
  * comments (`<?…?>`, which the HTML tokenizer hides exactly like a comment).
- * The `<?` arm is what lets a PI-only document reach Layer 2's bogus-comment
- * splice; without it such a document would skip the pipeline entirely. Gate for
- * Layer 2 (HTML sanitization) and the HTML img/a exfil path in Layer 3.
+ * The `<!`/`<?` arms carry a comment-only document into the pipeline at all:
+ * without them it would skip both Layer 2's splice of the comment and Layer 3's
+ * exfil scan over the comment interior.
+ * Gate for Layer 2 (HTML sanitization) and the HTML img/a exfil path in
+ * Layer 3.
  */
 export const HTML_TAG_PRESENT: RegExp;
 /**

package/types/html.d.mts

@@ -21,18 +21,35 @@ export function isHiddenOpen(htmlValue: string): string | null;
  */
 export function closingTagName(htmlValue: string): string | null;
 /**
- * Replace each range of `text` with its kind's placeholder, preserving every
- * byte outside the ranges verbatim. Overlapping/nested ranges are merged
+ * 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
  * (defense-in-depth — the scanners emit disjoint ranges).
+ *
+ * Returns the spliced text plus `pairs`, one per emitted placeholder in output
+ * order, each pairing the placeholder with the ORIGINAL bytes it replaced and
+ * its start offset in the RETURNED text (UTF-16 code-unit string indices, the
+ * same space as `ranges`) — everything a rehydrator needs to undo the splice.
  * @param {string} text
- * @param {Array<{start: number, end: number, kind: "comment" | "hidden"}>} ranges
- * @returns {string}
+ * @param {SpliceRange[]} ranges
+ * @returns {{ text: string, pairs: SplicePair[] }}
  */
-export function spliceRanges(text: string, ranges: Array<{
-    start: number;
-    end: number;
-    kind: "comment" | "hidden";
-}>): string;
+export function spliceRanges(text: string, ranges: SpliceRange[]): {
+    text: string;
+    pairs: SplicePair[];
+};
 /**
  * Scan raw HTML for hidden content to strip and preserved tags to report.
  * Returned ranges are offsets into `html`; comments and hidden elements span
@@ -40,14 +57,10 @@ export function spliceRanges(text: string, ranges: Array<{
  * through matching close, and parse5 extends an unclosed element to the end
  * of the fragment — fail-closed for truncated markup).
  * @param {string} html
- * @returns {{ ranges: Array<{start: number, end: number, kind: "comment" | "hidden"}>, warned: ReturnType<typeof newWarned> }}
+ * @returns {{ ranges: SpliceRange[], warned: ReturnType<typeof newWarned> }}
  */
 export function scanHtmlFragment(html: string): {
-    ranges: Array<{
-        start: number;
-        end: number;
-        kind: "comment" | "hidden";
-    }>;
+    ranges: SpliceRange[];
     warned: ReturnType<typeof newWarned>;
 };
 /**
@@ -59,14 +72,26 @@ export function scanHtmlFragment(html: string): {
 export function looksLikeHtmlSource(text: string): boolean;
 /**
  * Layer 2 over web-ingress text: splice out HTML comments and hidden elements
- * (placeholders mark the cuts; all other bytes are preserved verbatim) and
- * count preserved scripting/resource tags for the caller's warning. Returns
- * null when there is nothing to strip and nothing to report. `unparseable` is
- * set (true) only on the fail-closed path below, where the whole input was
- * withheld behind {@link UNPARSEABLE_PLACEHOLDER} rather than spliced — the
- * caller's warning must describe a whole-output withhold, not a splice.
+ * (keyed placeholders mark the cuts; all other bytes are preserved verbatim)
+ * and count preserved scripting/resource tags for the caller's warning. Returns
+ * null when there is nothing to strip and nothing to report.
+ *
+ * `splices` pairs every emitted placeholder with the original bytes it
+ * replaced (see {@link spliceRanges}), so a caller can rehydrate the text —
+ * nothing is lost, only hidden behind an identity-carrying placeholder.
+ *
+ * `unparseable` is set (true) only on the fail-closed path below, where the
+ * whole input was withheld behind {@link UNPARSEABLE_PLACEHOLDER} rather than
+ * spliced — the caller's warning must describe a whole-output withhold, not a
+ * splice. There `splices` is `[]`: the parser blew up before any span could be
+ * located, so nothing is recoverable per-splice (the caller's pre-splice
+ * `reveal` is the only copy).
+ *
+ * Idempotent over its own output: a keyed placeholder contains no `<`, so a
+ * re-run neither gates on it (HTML_TAG_PRESENT needs a tag) nor reads it as
+ * markup — placeholders already in the text pass through byte-identical.
  * @param {string} text
- * @returns {{ text: string, removed: { comments: number, hidden: number }, warned: { tags: Record<string, number>, dataSrc: number }, unparseable?: true } | null}
+ * @returns {{ text: string, removed: { comments: number, hidden: number }, warned: { tags: Record<string, number>, dataSrc: number }, splices: SplicePair[], unparseable?: true } | null}
  */
 export function sanitizeHtml(text: string): {
     text: string;
@@ -78,6 +103,7 @@ export function sanitizeHtml(text: string): {
         tags: Record<string, number>;
         dataSrc: number;
     };
+    splices: SplicePair[];
     unparseable?: true;
 } | null;
 /**
@@ -112,10 +138,34 @@ export function detectExfil(text: string): Array<{
     target: string;
 }> | null;
 export const REPORTED_TAGS: Set<string>;
-export const COMMENT_PLACEHOLDER: "[HTML comment removed]";
-export const HIDDEN_PLACEHOLDER: "[hidden HTML removed]";
+/**
+ * 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 SpliceKind = "comment" | "hidden";
+export type SpliceRange = {
+    start: number;
+    end: number;
+    kind: SpliceKind;
+};
+/**
+ * One splice: the keyed placeholder now in the output text, the ORIGINAL
+ * bytes it replaced, and the placeholder's start offset in the RETURNED text.
+ * All offsets in this module — unist positions and these — are plain JS
+ * string indices, i.e. UTF-16 code units.
+ */
+export type SplicePair = {
+    placeholder: string;
+    original: string;
+    start: number;
+};
 /** @returns {{ tags: Record<string, number>, dataSrc: number }} */
 declare function newWarned(): {
     tags: Record<string, number>;

package/types/index.d.mts

@@ -21,18 +21,23 @@
  *
  * The layer bodies live in `./output.mjs`; this is a facade over them, not a
  * second implementation (see the module doc). It narrows `sanitizeText`'s result
- * to the four fields this entry promises — `modified`/`sgrNote`
- * describe the tool-output pipeline's banner, and `reveal` is produced only by
- * options this facade does not expose. `html` selects Layers 2 AND 3 together
- * here, which is the surface this entry has always had; `exfilScan` exposes
- * Layer 3's non-destructive detection on its own (unconditionally implied by
- * `html`, which it can add to but never switch off) for
- * callers that must keep the visible bytes intact — e.g. a PR diff where the
- * Layer-2 splice would corrupt legitimate markup — matching the separate
- * flags `sanitizeText` takes for the tool-output pipeline.
+ * to the fields this entry promises — `modified`/`sgrNote` describe the
+ * tool-output pipeline's banner, and `reveal` is produced only by options this
+ * facade does not expose. `splices` IS passed through (present only when Layer 2
+ * spliced): the placeholder→original pairs a caller needs to rehydrate keyed
+ * Layer-2 placeholders — same field, same shape as `sanitizeText`'s, since this
+ * facade wraps the same layers (grammar in `./html.mjs`: `layer2Placeholder` /
+ * `LAYER2_PLACEHOLDER_RE`). `html` selects Layers 2 AND 3 together here, which
+ * is the surface this entry has always had; `exfilScan` exposes Layer 3's
+ * non-destructive detection on its own (unconditionally implied by `html`,
+ * which it can add to but never switch off) for callers that must keep the
+ * visible bytes intact — e.g. a PR diff where the Layer-2 splice would corrupt
+ * legitimate markup — matching the separate flags `sanitizeText` takes for the
+ * tool-output pipeline, which needs Layer 3's detection without Layer 2's
+ * splice.
  * @param {string} text
  * @param {{ html?: boolean, exfilScan?: boolean } | null} [options]
- * @returns {Promise<{ cleaned: string, found: string[], warnings: string[], notes: string[] }>}
+ * @returns {Promise<{ cleaned: string, found: string[], warnings: string[], notes: string[], splices?: Array<{ placeholder: string, original: string }> }>}
  */
 export function sanitize(text: string, options?: {
     html?: boolean;
@@ -42,6 +47,10 @@ export function sanitize(text: string, options?: {
     found: string[];
     warnings: string[];
     notes: string[];
+    splices?: Array<{
+        placeholder: string;
+        original: string;
+    }>;
 }>;
 export { applyLayer1, isBenignAnsi, isBenignAnsiKinds, stripAnsiFully, LONE_SURROGATE_RE } from "./layer1.mjs";
 export { stripInvisible, stripInvisibleWithReport, isSgrOnly, STRIP, SGR_RE, CHECKS, CATEGORY, CATEGORY_LABELS, LINGUISTIC_SCRIPTS, VS, BLANK_NON_CF, LONG_RUN_RE, LONG_RUN_THRESHOLD, SCATTERED_THRESHOLD } from "./invisible.mjs";

package/types/output.d.mts

@@ -43,7 +43,13 @@ export function deleteVerbatimSpans(text: string, spans: string[]): {
  * `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
- * it could not be vetted (see {@link vetStageValue}).
+ * it could not be vetted (see {@link vetStageValue}). `splices` is its
+ * per-placeholder twin — Layer 2's placeholder→original pairs, in document
+ * order, so a hook can rehydrate individual splices (the keyed-placeholder
+ * grammar lives in ./html.mjs: `layer2Placeholder`/`LAYER2_PLACEHOLDER_RE`).
+ * Present only when Layer 2 spliced; each `original` is vetted like `reveal`,
+ * and one that cannot be vetted is WITHHELD (dropped from the array) under the
+ * same doctrine — Layer 4 never saw pre-splice text.
  *
  * Every byte mutation goes through {@link applyMutation} and every Layer-4 call
  * through {@link runRedact}, so a layer cannot re-establish some of the
@@ -63,7 +69,7 @@ export function deleteVerbatimSpans(text: string, spans: string[]): {
  * vocabulary), so they contribute findings only.
  * @param {string} text
  * @param {SanitizeTextOptions} [options]
- * @returns {Promise<{ cleaned: string, found: string[], warnings: string[], notes: string[], modified: boolean, sgrNote: boolean, reveal?: string }>}
+ * @returns {Promise<{ cleaned: string, found: string[], warnings: string[], notes: string[], modified: boolean, sgrNote: boolean, reveal?: string, splices?: Array<{ placeholder: string, original: string }> }>}
  */
 export function sanitizeText(text: string, options?: SanitizeTextOptions): Promise<{
     cleaned: string;
@@ -73,6 +79,10 @@ export function sanitizeText(text: string, options?: SanitizeTextOptions): Promi
     modified: boolean;
     sgrNote: boolean;
     reveal?: string;
+    splices?: Array<{
+        placeholder: string;
+        original: string;
+    }>;
 }>;
 /**
  * True only for arrays and PLAIN objects — the two shapes whose contents are
@@ -105,6 +115,12 @@ export function isWalkableContainer(value: any): boolean;
  * the HTML splice removed bytes) so a caller can persist what was hidden — the
  * structured-output analogue of {@link sanitizeText}'s `reveal`. Same
  * mutated-accumulator contract as `warnings`.
+ *
+ * `splices` accumulates each string leaf's Layer-2 placeholder→original pairs
+ * (each `original` already vetted, withheld entries dropped — see
+ * {@link sanitizeText}) — the per-placeholder twin of `reveals`, so a hook
+ * caller gets them for object-shaped tool output too. Same mutated-accumulator
+ * contract as `reveals`.
  * @param {any} value
  * @param {SanitizeTextOptions} options
  * @param {string[]} warnings
@@ -112,9 +128,14 @@ export function isWalkableContainer(value: any): boolean;
  * @param {string[]} [notes]  the NOTE-severity counterpart of `warnings`;
  *   appended last so an existing positional caller keeps working (it simply
  *   discards the notes, which is exactly as loud as before the split)
+ * @param {Array<{ placeholder: string, original: string }>} [splices]  appended
+ *   after `notes` for the same positional-compatibility reason
  * @returns {Promise<{ value: any, modified: boolean, sgrNote: boolean }>}
  */
-export function sanitizeValue(value: any, options: SanitizeTextOptions, warnings: string[], reveals?: string[], notes?: string[]): Promise<{
+export function sanitizeValue(value: any, options: SanitizeTextOptions, warnings: string[], reveals?: string[], notes?: string[], splices?: Array<{
+    placeholder: string;
+    original: string;
+}>): Promise<{
     value: any;
     modified: boolean;
     sgrNote: boolean;