agent-sanitizer 2.30.0 → 2.31.0

package/src/html.mjs

@@ -10,6 +10,16 @@
  * and `data:` URI resources are REPORTED in the result's `warned` counts but
  * never removed, so fetched page source stays inspectable.
  *
+ * Every splice is ROUND-TRIPPABLE: the placeholder carries a content-addressed
+ * key (see {@link layer2Placeholder}) and `sanitizeHtml` returns a `splices`
+ * array pairing each placeholder with the original bytes it replaced, so a
+ * caller that must write the text back (an agent editing a PR body whose
+ * comments were spliced) can rehydrate instead of persisting the loss —
+ * comments are ubiquitous legitimate content (PR templates, tooling markers),
+ * and an earlier lossy splice corrupted real documents (#244). The splice
+ * itself stays: comments hide content from a human reading the rendered page,
+ * which is the exact channel this layer exists to close.
+ *
  * Layer 3 reports data-exfil-shaped URLs (suspicious query params, oversized
  * payloads, embedded credentials) without modifying them; the caller surfaces
  * the report as a warning.
@@ -18,6 +28,7 @@
  * remark/rehype/unified graph costs ~200ms of module-load time, so the main
  * entry `await import()`s this module only when its cheap regex gates match.
  */
+import { createHash } from "node:crypto";
 // @ts-ignore -- css-tree ships no bundled types and @types/css-tree lags the 3.x
 // API (e.g. `ident.decode`); the value AST is walked with local `any` types.
 import * as csstree from "css-tree";
@@ -1284,8 +1295,65 @@ export function closingTagName(htmlValue) {
 
 // ─── Layer 2: splice engine ──────────────────────────────────────────────────
 
-export const COMMENT_PLACEHOLDER = "[HTML comment removed]";
-export const HIDDEN_PLACEHOLDER = "[hidden HTML removed]";
+/**
+ * @typedef {"comment" | "hidden"} SpliceKind
+ * @typedef {{ start: number, end: number, kind: SpliceKind }} SpliceRange
+ * @typedef {{ placeholder: string, original: string, start: number }} SplicePair
+ *   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.
+ */
+
+// The kind-specific prose of a Layer-2 placeholder. The full placeholder is
+// built by {@link layer2Placeholder} and matched by {@link LAYER2_PLACEHOLDER_RE};
+// keep all three in sync — they are ONE grammar shared with the rehydrating
+// hooks and the tests.
+const PLACEHOLDER_LABEL = Object.freeze({
+  hidden: "hidden HTML",
+  comment: "HTML comment",
+});
+
+// How many lowercase-hex chars of the sha256 make the placeholder key. 48 bits
+// is far past accidental-collision range for the handful of splices one
+// document carries, while keeping the placeholder short enough to read.
+const PLACEHOLDER_KEY_LEN = 12;
+
+/**
+ * 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, original) {
+  const key = createHash("sha256")
+    .update(original, "utf8")
+    .digest("hex")
+    .slice(0, PLACEHOLDER_KEY_LEN);
+  return `[${PLACEHOLDER_LABEL[kind]} removed #${key}]`;
+}
+
+/**
+ * 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 =
+  /\[(?:hidden HTML|HTML comment) removed #([0-9a-f]{12})\]/g;
+
+// DEPRECATED un-keyed placeholder PREFIXES, kept exported for callers that
+// match "some Layer-2 placeholder of this kind" without knowing the key. The
+// full placeholder is keyed — build it with {@link layer2Placeholder}, match it
+// with {@link LAYER2_PLACEHOLDER_RE}.
+export const HIDDEN_PLACEHOLDER = "[hidden HTML removed";
+export const COMMENT_PLACEHOLDER = "[HTML comment removed";
 // Shown when the remark/rehype parse itself fails (e.g. pathologically nested
 // markup overflows the recursive tree walk with a RangeError). The top-level
 // `sanitize`/`sanitizeText` contract is "never throws, `cleaned` is always a
@@ -1297,18 +1365,23 @@ export const HIDDEN_PLACEHOLDER = "[hidden HTML removed]";
 export const UNPARSEABLE_PLACEHOLDER = "[HTML unparseable — withheld]";
 
 /**
- * Replace each range of `text` with its kind's placeholder, preserving every
- * byte outside the ranges verbatim. Overlapping/nested ranges are merged
+ * 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, ranges) {
   const sorted = [...ranges].sort(
     (left, right) => left.start - right.start || left.end - right.end,
   );
-  /** @type {typeof ranges} */
+  /** @type {SpliceRange[]} */
   const merged = [];
   for (const range of sorted) {
     const last = merged[merged.length - 1];
@@ -1316,8 +1389,8 @@ export function spliceRanges(text, ranges) {
       if (range.end > last.end) last.end = range.end;
       // A hidden range absorbed into a comment range (the comment sorts first
       // on a tie) must keep the hidden label — hidden content placeholdered as
-      // "[HTML comment removed]" would understate what was stripped. Hidden
-      // dominates: if either side is hidden, the union is hidden.
+      // an "[HTML comment removed …]" would understate what was stripped.
+      // Hidden dominates: if either side is hidden, the union is hidden.
       if (range.kind === "hidden") last.kind = "hidden";
     } else {
       merged.push({ ...range });
@@ -1325,13 +1398,17 @@ export function spliceRanges(text, ranges) {
   }
   let out = "";
   let cursor = 0;
+  /** @type {SplicePair[]} */
+  const pairs = [];
   for (const range of merged) {
-    out +=
-      text.slice(cursor, range.start) +
-      (range.kind === "comment" ? COMMENT_PLACEHOLDER : HIDDEN_PLACEHOLDER);
+    out += text.slice(cursor, range.start);
+    const original = text.slice(range.start, range.end);
+    const placeholder = layer2Placeholder(range.kind, original);
+    pairs.push({ placeholder, original, start: out.length });
+    out += placeholder;
     cursor = range.end;
   }
-  return out + text.slice(cursor);
+  return { text: out + text.slice(cursor), pairs };
 }
 
 /** @returns {{ tags: Record<string, number>, dataSrc: number }} */
@@ -1369,7 +1446,7 @@ function hasWarned(warned) {
  * 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) {
   return scanFragmentTree(html, parseFragment(html));
@@ -1382,10 +1459,10 @@ export function scanHtmlFragment(html) {
  * the ranges are offsets into `html`, read from that tree's positions.
  * @param {string} html
  * @param {any} tree
- * @returns {{ ranges: Array<{start: number, end: number, kind: "comment" | "hidden"}>, warned: ReturnType<typeof newWarned> }}
+ * @returns {{ ranges: SpliceRange[], warned: ReturnType<typeof newWarned> }}
  */
 function scanFragmentTree(html, tree) {
-  /** @type {Array<{start: number, end: number, kind: "comment" | "hidden"}>} */
+  /** @type {SpliceRange[]} */
   const ranges = [];
   const warned = newWarned();
   // @ts-ignore -- visit callback returns EXIT/SKIP only on matches; implicit undefined return is intentional
@@ -1491,7 +1568,7 @@ function commentSpans(value) {
  * @param {string} value
  * @param {number} base absolute offset of the start of `value`
  * @param {number} nodeEnd absolute offset of the end of the containing node
- * @param {Array<{start: number, end: number, kind: "comment" | "hidden"}>} ranges
+ * @param {SpliceRange[]} ranges
  */
 function collectCommentRanges(value, base, nodeEnd, ranges) {
   BOGUS_COMMENT_OPEN_RE.lastIndex = 0;
@@ -1541,7 +1618,7 @@ function collectCommentRanges(value, base, nodeEnd, ranges) {
  * @param {{ tag: string | null, depth: number, regionStart: number }} state
  * @param {string} value
  * @param {number} nodeEnd absolute end offset of this node
- * @param {Array<{start: number, end: number, kind: "comment" | "hidden"}>} ranges
+ * @param {SpliceRange[]} ranges
  */
 function updateHiddenState(state, value, nodeEnd, ranges) {
   if (value.startsWith("</")) {
@@ -1603,7 +1680,7 @@ function hasHtmlLeaf(node) {
  * sibling/nested node the way it does in the flat token stream.
  * @param {any} node
  * @param {string} text the full document source, for raw-slice absorb folding
- * @param {Array<{start: number, end: number, kind: "comment" | "hidden"}>} ranges
+ * @param {SpliceRange[]} ranges
  * @param {ReturnType<typeof newWarned>} warned
  */
 function scanInlineChildren(node, text, ranges, warned) {
@@ -1697,11 +1774,11 @@ const FLOW_HTML_PARENTS = new Set([
 
 /**
  * @param {string} text
- * @returns {{ ranges: Array<{start: number, end: number, kind: "comment" | "hidden"}>, warned: ReturnType<typeof newWarned> }}
+ * @returns {{ ranges: SpliceRange[], warned: ReturnType<typeof newWarned> }}
  */
 function scanMarkdown(text) {
   const tree = mdParser.parse(text);
-  /** @type {Array<{start: number, end: number, kind: "comment" | "hidden"}>} */
+  /** @type {SpliceRange[]} */
   const ranges = [];
   const warned = newWarned();
 
@@ -1812,18 +1889,30 @@ export function looksLikeHtmlSource(text) {
 
 /**
  * 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) {
   if (!HTML_TAG_PRESENT.test(text)) return null;
-  /** @type {{ ranges: Array<{start: number, end: number, kind: "comment" | "hidden"}>, warned: ReturnType<typeof newWarned> }} */
+  /** @type {{ ranges: SpliceRange[], warned: ReturnType<typeof newWarned> }} */
   let scan;
   try {
     // One parse decides the branch AND feeds it, so the source branch does not
@@ -1839,6 +1928,7 @@ export function sanitizeHtml(text) {
       text: UNPARSEABLE_PLACEHOLDER,
       removed: { comments: 0, hidden: 1 },
       warned: newWarned(),
+      splices: [],
       unparseable: true,
     };
   }
@@ -1847,10 +1937,13 @@ export function sanitizeHtml(text) {
   const removed = { comments: 0, hidden: 0 };
   for (const range of ranges)
     removed[range.kind === "comment" ? "comments" : "hidden"]++;
+  const spliced =
+    ranges.length > 0 ? spliceRanges(text, ranges) : { text, pairs: [] };
   return {
-    text: ranges.length > 0 ? spliceRanges(text, ranges) : text,
+    text: spliced.text,
     removed,
     warned,
+    splices: spliced.pairs,
   };
 }
 

package/src/index.mjs

@@ -84,29 +84,43 @@ export {
  *
  * 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 async function sanitize(text, options) {
   if (typeof text !== "string")
     throw new TypeError("sanitize(text, options): text must be a string");
   const { html = false, exfilScan = false } = options ?? {};
-  const { cleaned, found, warnings, notes } = await sanitizeText(text, {
-    html,
-    // `html` implies the scan unconditionally, and `exfilScan` can only ADD it:
-    // an opt-OUT would make `{ html: true, exfilScan: false }` splice Layer 2
-    // while silently dropping Layer 3's report — a fail-open the docs deny.
-    exfilScan: exfilScan || html,
-  });
-  return { cleaned, found, warnings, notes };
+  const { cleaned, found, warnings, notes, splices } = await sanitizeText(
+    text,
+    {
+      html,
+      // `html` implies the scan unconditionally, and `exfilScan` can only ADD it:
+      // an opt-OUT would make `{ html: true, exfilScan: false }` splice Layer 2
+      // while silently dropping Layer 3's report — a fail-open the docs deny.
+      exfilScan: exfilScan || html,
+    },
+  );
+  return {
+    cleaned,
+    found,
+    warnings,
+    notes,
+    ...(splices !== undefined && { splices }),
+  };
 }

package/src/output.mjs

@@ -386,19 +386,25 @@ function processLayer1(text, sgrCarveOut) {
  * folded into `state`. Returns the pre-splice text when Layer 2 removed bytes so
  * the caller can hand it back for later inspection of what the splice hid (the
  * model cannot otherwise tell a benign `<!-- TODO -->` from an injection
- * payload), and `undefined` otherwise. That text is a STAGE VALUE, not a result:
- * it has not been through Layer 4, so {@link sanitizeText} must vet it before it
- * leaves. The transform itself stays pure — the caller owns any persistence.
+ * payload), and `undefined` otherwise — plus Layer 2's `splices`, the
+ * placeholder→original pairs a rehydrator needs (in document order; the
+ * per-splice offsets are dropped here because later layers may mutate the text,
+ * making offsets into this stage's text meaningless). Both are STAGE VALUES,
+ * not results: neither has been through Layer 4, so {@link sanitizeText} must
+ * vet them before they leave. The transform itself stays pure — the caller owns
+ * any persistence.
  * @param {PipelineState} state
  * @param {{ html?: boolean, exfilScan?: boolean }} options
- * @returns {Promise<string | undefined>} pre-splice text, when Layer 2 spliced
+ * @returns {Promise<{ reveal: string | undefined, splices: Array<{ placeholder: string, original: string }> }>}
  */
 async function applyMarkdownPipeline(state, { html, exfilScan }) {
   const inputText = state.text;
   /** @type {string | undefined} */
   let reveal;
+  /** @type {Array<{ placeholder: string, original: string }>} */
+  const splices = [];
   if ((!html && !exfilScan) || !needsMarkdownPipeline(inputText))
-    return undefined;
+    return { reveal: undefined, splices };
   let sanitizeHtml, detectExfil;
   /* c8 ignore start -- a rejected dynamic import of a module that ships in
      this very package (not an optional peer dep) requires corrupting
@@ -417,12 +423,17 @@ async function applyMarkdownPipeline(state, { html, exfilScan }) {
   }
   /* c8 ignore stop */
   // Layer 2 — strips what a rendered page would not show (comments, hidden
-  // elements); scripting/resource tags preserved+reported.
+  // elements); scripting/resource tags preserved+reported. Each cut leaves a
+  // keyed placeholder whose original bytes ride out in `splices`.
   if (html) {
     const layer2 = sanitizeHtml(state.text);
     if (layer2) {
       if (layer2.text !== state.text) {
         reveal = state.text;
+        // Keep only {placeholder, original}: the offsets sanitizeHtml returns
+        // point into THIS stage's text, which Layers 4/5 may still mutate.
+        for (const { placeholder, original } of layer2.splices)
+          splices.push({ placeholder, original });
         applyMutation(state, layer2.text);
         if (layer2.removed.comments > 0)
           state.found.push(CATEGORY.HTML_COMMENTS);
@@ -472,18 +483,19 @@ async function applyMarkdownPipeline(state, { html, exfilScan }) {
       );
     }
   }
-  return reveal;
+  return { reveal, splices };
 }
 
 /**
  * Vet a pipeline STAGE value on its way out of {@link sanitizeText}. Only
  * `cleaned` traverses every layer; anything else a caller is handed (today the
  * Layer-2 `reveal`) is a snapshot from the middle of the pipeline and still
- * carries whatever the layers after it would have removed. `reveal` in
- * particular is the PRE-splice text, so it holds exactly the bytes Layer 2 hid —
- * and Layer 4 only ever saw the POST-splice text, meaning a secret inside a
- * spliced-out HTML comment has never been redacted. The documented use of the
- * field is to persist it, i.e. to write that secret to a log or sidecar.
+ * carries whatever the layers after it would have removed. `reveal` and each
+ * splice's `original` are PRE-splice text, so they hold exactly the bytes
+ * Layer 2 hid — and Layer 4 only ever saw the POST-splice text, meaning a
+ * secret inside a spliced-out HTML comment has never been redacted. The
+ * documented use of these fields is to persist them, i.e. to write that secret
+ * to a log, sidecar, or rehydrated file.
  *
  * Fails CLOSED by WITHHOLDING rather than throwing: a redactor failure here must
  * not discard the already-vetted `cleaned` the caller needs, and dropping the
@@ -542,7 +554,13 @@ async function vetStageValue(text, redact, findings, label) {
  * `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
@@ -562,7 +580,7 @@ async function vetStageValue(text, redact, findings, label) {
  * 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 async function sanitizeText(text, options = {}) {
   const { redact, filterInjection, sgrCarveOut = false } = options;
@@ -579,7 +597,8 @@ export async function sanitizeText(text, options = {}) {
     unreportedChange: false,
   };
 
-  const revealText = await applyMarkdownPipeline(state, options);
+  const { reveal: revealText, splices: stageSplices } =
+    await applyMarkdownPipeline(state, options);
 
   // Layer 4 — fail closed (see runRedact).
   if (redact) await runRedact(state, redact);
@@ -626,6 +645,22 @@ export async function sanitizeText(text, options = {}) {
           state.findings,
           "pre-splice copy of the removed HTML",
         );
+  // Each splice `original` skipped Layer 4 the same way `reveal` did, so it
+  // gets the same exit vetting. A splice whose original cannot be vetted is
+  // WITHHELD — dropped from the array — mirroring the reveal doctrine: better
+  // an unrecoverable splice than an unvetted secret handed out for persistence.
+  /** @type {Array<{ placeholder: string, original: string }>} */
+  const splices = [];
+  for (const splice of stageSplices) {
+    const vetted = await vetStageValue(
+      splice.original,
+      redact,
+      state.findings,
+      "original text of a removed-HTML splice",
+    );
+    if (vetted !== undefined)
+      splices.push({ placeholder: splice.placeholder, original: vetted });
+  }
   const warnings = warningMessages(state.findings);
   const notes = noteMessages(state.findings);
   return {
@@ -642,6 +677,10 @@ export async function sanitizeText(text, options = {}) {
     sgrNote:
       notes.length > 0 && warnings.length === 0 && !state.unreportedChange,
     ...(reveal !== undefined && { reveal }),
+    // Presence-gated like `reveal`: the field exists only when Layer 2 spliced
+    // and at least one original survived vetting, so the common-case result
+    // shape stays minimal.
+    ...(splices.length > 0 && { splices }),
   };
 }
 
@@ -749,6 +788,12 @@ function depthMemo() {
  * 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
@@ -756,6 +801,8 @@ function depthMemo() {
  * @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 async function sanitizeValue(
@@ -764,6 +811,7 @@ export async function sanitizeValue(
   warnings,
   reveals = [],
   notes = [],
+  splices = [],
 ) {
   return sanitizeValueAt(
     value,
@@ -771,6 +819,7 @@ export async function sanitizeValue(
     warnings,
     notes,
     reveals,
+    splices,
     0,
     new WeakSet(),
     depthMemo(),
@@ -788,6 +837,8 @@ export async function sanitizeValue(
  * @param {string[]} warnings
  * @param {string[]} notes  accumulates each string leaf's NOTE-severity findings
  * @param {string[]} reveals  accumulates each string leaf's pre-Layer-2 text
+ * @param {Array<{ placeholder: string, original: string }>} splices  accumulates
+ *   each string leaf's Layer-2 placeholder→original pairs (already vetted)
  * @param {number} depth
  * @param {WeakSet<object>} seen
  * @param {ReturnType<typeof depthMemo<{ value: any, modified: boolean, sgrNote: boolean }>>} memo
@@ -798,8 +849,9 @@ export async function sanitizeValue(
  *   ~25-object diamond measured at 68 s, far under MAX_DEPTH) — since the path-
  *   scoped `seen` set only guards cycles, not repeated work. Because warnings
  *   dedup in composeContext, skipping a cached node's duplicate warnings is
- *   harmless. A cached node's `reveals` are likewise not re-emitted, harmless
- *   for the same reason (the caller dedups reveals by content).
+ *   harmless. A cached node's `reveals` and `splices` are likewise not
+ *   re-emitted, harmless for the same reason (the caller dedups reveals by
+ *   content and splices by their content-addressed key).
  * @returns {Promise<{ value: any, modified: boolean, sgrNote: boolean }>}
  */
 async function sanitizeValueAt(
@@ -808,6 +860,7 @@ async function sanitizeValueAt(
   warnings,
   notes,
   reveals,
+  splices,
   depth,
   seen,
   memo,
@@ -817,6 +870,7 @@ async function sanitizeValueAt(
     warnings.push(...result.warnings);
     notes.push(...result.notes);
     if (result.reveal !== undefined) reveals.push(result.reveal);
+    if (result.splices !== undefined) splices.push(...result.splices);
     return {
       value: result.cleaned,
       modified: result.modified,
@@ -906,6 +960,7 @@ async function sanitizeValueAt(
           warnings,
           notes,
           reveals,
+          splices,
           depth + 1,
           seen,
           memo,
@@ -942,6 +997,7 @@ async function sanitizeValueAt(
         warnings,
         notes,
         reveals,
+        splices,
         depth + 1,
         seen,
         memo,