agent-sanitizer 2.60.0 → 2.60.2

package/claude-hooks/sanitize-output.mjs

@@ -67,7 +67,7 @@ import { containsPlaceholder, layer2Keys } from "./lib/placeholder-grammar.mjs";
 // Layer-1 primitives and the cheap pre-gates, bound via lazyImport (see its
 // doc for the fail-OPEN hazard of a bare static npm import). A load failure
 // leaves the bindings undefined and the dependent call throws into the CLI's
-// fail-closed catch, which suppresses the output.
+// catch, which applies this hook's fault posture (emitHookFailure).
 // HTML_TAG_PRESENT (the Layer-2 pre-gate) and the Layer-1 re-exports come from
 // the package ROOT, which exposes them WITHOUT eagerly loading the
 // remark/rehype/unified graph (~120ms of module-load time). Importing `/html`
@@ -194,8 +194,8 @@ async function redactSecrets(text, webIngress, deadline) {
  * 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
@@ -246,6 +246,8 @@ async function redactSecrets(text, webIngress, deadline) {
  * @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 async function sanitizeText(
@@ -253,6 +255,7 @@ export async function sanitizeText(
   toolName,
   deadline = makeDeadline(SANITIZE_BUDGET_MS),
   ext = {},
+  secretsOn = secretsEnabled(),
 ) {
   const webIngress = isUntrustedIngress(toolName);
   // Layer 2 (HTML rewrite) runs on WebFetch/WebSearch always, and on MCP output
@@ -275,7 +278,7 @@ export async function sanitizeText(
     flagDigestValues: digestFlaggingEnabled(),
     sgrCarveOut: !webIngress,
     deadline,
-    // Layer 4 — OPT-IN (secretsEnabled): with the knob unset the seam gets no
+    // Layer 4 — OPT-IN (`secretsOn`): with the knob unset the seam gets no
     // redact callback at all, so plain output never spawns the daemon and no
     // placeholder ever enters the model's view. When it runs, the seam rethrows
     // a redactor throw wrapped, and this hook's fault policy suppresses the
@@ -283,7 +286,7 @@ export async function sanitizeText(
     // operator's terminal here first: the suppression note rides in what only
     // the model sees, so a degraded redactor would otherwise be invisible to
     // the human.
-    redact: !secretsEnabled()
+    redact: !secretsOn
       ? undefined
       : async (/** @type {string} */ content) => {
           let secrets;
@@ -389,6 +392,7 @@ function applyPostText(result, post) {
  *   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 async function sanitizeValue(
@@ -401,9 +405,16 @@ export async function sanitizeValue(
   notes = [],
   splices = [],
   path = "",
+  secretsOn = secretsEnabled(),
 ) {
   if (typeof value === "string") {
-    const result = await sanitizeText(value, toolName, deadline, ext);
+    const result = await sanitizeText(
+      value,
+      toolName,
+      deadline,
+      ext,
+      secretsOn,
+    );
     warnings.push(...result.warnings);
     notes.push(...result.notes);
     if (result.reveal !== undefined) reveals.push(result.reveal);
@@ -429,6 +440,7 @@ export async function sanitizeValue(
         notes,
         splices,
         `${path}[${index}]`,
+        secretsOn,
       );
       out.push(result.value);
       if (result.modified) modified = true;
@@ -447,6 +459,7 @@ export async function sanitizeValue(
       notes,
       splices,
       path,
+      secretsOn,
     );
   return { value, modified: false, sgrNote: false };
 }
@@ -529,7 +542,8 @@ function withheldKeyFor(out, cleaned) {
  * @param {string[]} notes  accumulates the leaves' NOTE-severity findings
  * @param {Array<{ placeholder: string, original: string }>} splices  accumulates
  *   the leaves' Layer-2 placeholder→original pairs
- * @param {string} [path]  dotted location of this object in the tool output
+ * @param {string} path  dotted location of this object in the tool output
+ * @param {boolean} secretsOn  the secret opt-in (see {@link sanitizeText})
  * @returns {Promise<{ value: Record<string, any>, modified: boolean, sgrNote: boolean }>}
  */
 async function sanitizeObject(
@@ -541,7 +555,8 @@ async function sanitizeObject(
   ext,
   notes,
   splices,
-  path = "",
+  path,
+  secretsOn,
 ) {
   /** @type {Record<string, any>} */
   const out = {};
@@ -556,7 +571,13 @@ async function sanitizeObject(
     // callback sees just the string and the tool, so it cannot tell a schema key
     // from content; a rewrite here can collapse two fields into one name, which
     // costs both of them their values below. Extensions run on value leaves.
-    const keyResult = await sanitizeText(key, toolName, deadline);
+    const keyResult = await sanitizeText(
+      key,
+      toolName,
+      deadline,
+      {},
+      secretsOn,
+    );
     warnings.push(...keyResult.warnings);
     notes.push(...keyResult.notes);
     if (keyResult.reveal !== undefined) reveals.push(keyResult.reveal);
@@ -573,6 +594,7 @@ async function sanitizeObject(
       notes,
       splices,
       path === "" ? keyResult.cleaned : `${path}.${keyResult.cleaned}`,
+      secretsOn,
     );
     // Two distinct raw keys can sanitize to the same name (e.g. `token` and a
     // `token` carrying a zero-width space stripped by Layer 1). Overwriting
@@ -908,6 +930,11 @@ export async function evaluateToolOutput(input, ext = {}) {
   const reveals = [];
   /** @type {Array<{ placeholder: string, original: string }>} */
   const splices = [];
+  // THE secret opt-in decision for this run. Every secret-touching path below —
+  // the walk's Layer 4, the reveal and span persistence, the on-disk tripwire,
+  // and the prose that claims redaction — reads this one value, so no path can
+  // dial the daemon or promise "redacted" while another treats the layer as off.
+  const secretsOn = secretsEnabled();
   // One shared wall-clock budget for every blocking daemon call this hook makes —
   // across all leaves of the walk AND the reveal/span-redaction loops below — so
   // their SUM cannot pile up past the hook kill (see SANITIZE_BUDGET_MS).
@@ -925,6 +952,8 @@ export async function evaluateToolOutput(input, ext = {}) {
     ext,
     notes,
     splices,
+    "",
+    secretsOn,
   );
   // Persist each leaf's pre-Layer-2 text (deduped by content) so the model can
   // Read back what the HTML splice removed; a successful write appends a hint
@@ -937,10 +966,10 @@ export async function evaluateToolOutput(input, ext = {}) {
     try {
       // Same opt-in as the main pass: with secrets off nothing was redacted
       // out of the primary output either, so the sidecar persists verbatim.
-      const secrets = secretsEnabled()
+      const redacted = secretsOn
         ? await redactSecrets(original, true, deadline)
         : null;
-      stored = secrets ? secrets.text : original;
+      stored = redacted ? redacted.text : original;
     } catch {
       // The pre-splice text carries the spliced hidden-element content, so a
       // secret hidden only inside such an element reaches the redactor here
@@ -952,16 +981,16 @@ export async function evaluateToolOutput(input, ext = {}) {
       warnings.push(REVEAL_WITHHELD_WARNING);
       continue;
     }
-    const hint = persistReveal(stored);
+    const hint = persistReveal(stored, secretsOn);
     if (hint) warnings.push(hint);
   }
   // Persist each splice's original beside the reveal, keyed by the placeholder's
   // content-addressed key, so the PreToolUse rehydrator can restore a keyed
   // placeholder the model writes back (Edit/Write) to the original bytes. Same
-  // re-redaction treatment as the reveals above — the seam already vetted each
-  // `original` on its way out, but this loop re-runs strict web-ingress
-  // redaction so NOTHING lands on disk that did not pass the same bar as the
-  // reveal sidecar. The key is EXTRACTED from the placeholder, never recomputed
+  // re-redaction treatment as the reveals above, under the same opt-in — the
+  // seam already vetted each `original` on its way out, but this loop re-runs
+  // strict web-ingress redaction so NOTHING lands on disk that did not pass the
+  // same bar as the reveal sidecar. The key is EXTRACTED from the placeholder, never recomputed
   // from the redacted original: it was minted from the RAW original's sha256,
   // so it is a name, not an integrity check — hashing the redacted bytes would
   // mint a key no placeholder carries. Persistence failure is non-fatal (the
@@ -973,14 +1002,16 @@ export async function evaluateToolOutput(input, ext = {}) {
     if (key === undefined) continue;
     let stored;
     try {
-      const secrets = await redactSecrets(original, true, deadline);
-      stored = secrets ? secrets.text : original;
+      const redacted = secretsOn
+        ? await redactSecrets(original, true, deadline)
+        : null;
+      stored = redacted ? redacted.text : original;
     } catch {
       // Same doctrine as the reveal loop: never write unvetted text, never
       // fail the already-safe primary output over a convenience sidecar.
       continue;
     }
-    if (persistSpan(key, stored)) spanStored = true;
+    if (persistSpan(key, stored, secretsOn)) spanStored = true;
   }
   if (spanStored) warnings.push(SPAN_ROUNDTRIP_NOTICE);
   // On-disk placeholder tripwire (see ON_DISK_PLACEHOLDER_WARNING). Tested on
@@ -993,7 +1024,7 @@ export async function evaluateToolOutput(input, ext = {}) {
   // inserts placeholders, so placeholder-shaped bytes are ordinary text and
   // the warning would be pure noise on every doc ABOUT redaction.
   if (
-    secretsEnabled() &&
+    secretsOn &&
     input.tool_name === "Read" &&
     !revealRead &&
     containsPlaceholder(toolOutput)
@@ -1045,17 +1076,18 @@ export async function evaluateToolOutput(input, ext = {}) {
  * {@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>}
  */
 export async function judgeSanitizeOutput(event, ext = {}) {
   const { Decision, EventKind } = controlPlane();
-  // Fail closed on a payload the adapter cannot classify (contract/harness
-  // drift): this hook only ever receives PostToolUse, so an UNKNOWN event is an
-  // anomaly, and abstaining would let its output reach the model UNSANITIZED —
-  // fail OPEN. Throwing lands in the CLI's catch, which suppresses the output.
+  // Throw on a payload the adapter cannot classify (contract/harness drift):
+  // this hook only ever receives PostToolUse, so an UNKNOWN event is an
+  // anomaly, and abstaining would report a CLEAN run on output nobody vetted.
+  // Throwing lands in the CLI's catch, which applies this hook's registered
+  // fault policy (lib/hook-fault.mjs, rendered by emitHookFailure).
   if (event.event === EventKind.UNKNOWN)
     throw new Error(
       "sanitize-output: unrecognized hook payload (not PostToolUse)",
@@ -1108,9 +1140,9 @@ export async function judgeSanitizeOutput(event, ext = {}) {
  * 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}
@@ -1147,15 +1179,9 @@ export async function cliMain(ext = {}) {
     (event) => judgeSanitizeOutput(event, ext),
     {
       transformInput: withPostToolUseDefault,
-      // Fail closed: replace every string leaf of the original output with the
-      // placeholder, preserving shape so the harness honors the suppression
-      // instead of falling back to the raw, unvetted output (runJudgeCli hands
-      // back the parsed `input` even when the control-plane load failed, so the
-      // suppression shape-matches the real tool_response). emitFailClosed itself
-      // falls back to a bare string if that shape-matching replacement or its
-      // serialization throws, so even a pathological input fails closed. Under
-      // the open default with Layer 4 off the caller gets the warning-only
-      // pass-through instead — see emitHookFailure.
+      // The registered fault policy, rendered by emitHookFailure. It needs the
+      // parsed `input`, which runJudgeCli hands back even when the control-plane
+      // load failed, so a suppressing arm can keep the output's shape.
       onError: (err, input) =>
         emitHookFailure(input, err, undefined, ext.remedy),
     },

package/claude-hooks/sanitize-user-prompt.mjs

@@ -38,10 +38,10 @@ import { hookTrace, TraceEvent } from "./lib/trace.mjs";
 // come from the agent-sanitizer package. They are bound by a *caught* dynamic
 // import, never a bare top-level `import … from "…"`: a static npm import
 // resolves before any try/catch, so a missing node_modules would crash this hook
-// at load and let the prompt through UNSANITIZED (fail-open). A failed load
+// at load and let the prompt through UNSANITIZED with no warning. A failed load
 // leaves that binding undefined, which the judge's typeof guards turn into a
-// fail-closed block — one guard each, since the two loads succeed or fail
-// independently.
+// throw that this hook's registered fault policy answers (lib/hook-fault.mjs)
+// — one guard each, since the two loads succeed or fail independently.
 /** @type {typeof import("agent-sanitizer/prompt").classifyPrompt} */
 export let classifyPrompt;
 /** @type {typeof import("agent-sanitizer").stripAnsiFully} */
@@ -101,7 +101,7 @@ registerFaultPolicy(HOOK_NAME, {
 /* c8 ignore start — module-load boundary: the imports resolve in every real
  * run, and their failure (the package absent) can't be simulated in-process, so
  * neither arm is observable to the in-process tests. The judge's typeof guard
- * converts an undefined stripper into a fail-closed block — that guard IS tested. */
+ * converts an undefined stripper into a fault — that guard IS tested. */
 // Stryker disable all
 // lazyImport rather than a bare `await import` in a try/catch: it RECORDS the
 // loader error, which is the only thing that can tell a missing install apart
@@ -109,7 +109,7 @@ registerFaultPolicy(HOOK_NAME, {
 // missingPackageError with nothing to report but a guess.
 // The cast asserts the loaded SHAPE, not that it loaded: lazyImport yields {} on
 // failure, so either binding can still be undefined here — which is exactly what
-// the judge's typeof guard turns into a fail-closed block.
+// the judge's typeof guard turns into a fault (see the posture note above).
 ({ classifyPrompt } = /** @type {typeof import("agent-sanitizer/prompt")} */ (
   await lazyImport("agent-sanitizer/prompt")
 ));
@@ -123,12 +123,11 @@ registerFaultPolicy(HOOK_NAME, {
  * 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}
@@ -199,7 +198,7 @@ export function judgeSanitizeUserPrompt(
  *   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
@@ -221,9 +220,8 @@ export async function main(read, write, opts = {}) {
   // runJudgeCli so this hook doesn't re-implement the control-plane boundary:
   // runJudgeCli reads stdin BEFORE loading the control-plane package, so a
   // load failure fails to this hook's posture (the onError block) instead of
-  // leaving stdin unread. onError writes its envelope by hand — the default
-  // warning-only pass-through, or the block a caller asked for with
-  // AGENT_SANITIZER_FAIL_OPEN=0 — because the adapter that would render it is
+  // leaving stdin unread. onError writes the registered fault policy's envelope
+  // (lib/hook-fault.mjs) by hand, because the adapter that would render it is
   // exactly what may have failed to load. Either way this is the HOOK failing;
   // a prompt the working stripper flagged is still blocked in both postures.
   await runJudgeCli(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.60.0",
+  "version": "2.60.2",
   "description": "Defend an agent against hidden-content injection: strip payload-capable invisible Unicode and ANSI, splice out human-invisible HTML, and flag data-exfil URLs in untrusted text before any model sees it.",
   "type": "module",
   "repository": {

package/src/html.mjs

@@ -28,7 +28,11 @@
  * 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";
+import {
+  layer2Placeholder,
+  LAYER2_PLACEHOLDER_RE,
+  UNPARSEABLE_PLACEHOLDER,
+} from "./layer2-placeholder.mjs";
 // Subpath specifiers, never the `css-tree` root: the root builds the default
 // syntax at module scope, that construction reaches the lexer's `lib/data.js`,
 // and `lib/data.js` pulls the whole `mdn-data` CSS table set in through
@@ -1582,48 +1586,10 @@ export function closingTagName(htmlValue) {
  *   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;
+// The Layer-2 placeholder grammar lives in the dependency-free
+// ./layer2-placeholder.mjs so the hooks can parse placeholders without loading
+// this module's parser graph; it stays part of this subpath's public API.
+export { layer2Placeholder, LAYER2_PLACEHOLDER_RE, UNPARSEABLE_PLACEHOLDER };
 
 // DEPRECATED un-keyed placeholder PREFIXES, kept exported for callers that
 // match "some Layer-2 placeholder of this kind" without knowing the key. The
@@ -1631,15 +1597,6 @@ export const LAYER2_PLACEHOLDER_RE =
 // 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
-// string", and this module is the only seam those callers own — so the HTML
-// layer must fail CLOSED here: withhold the whole unparseable input behind one
-// placeholder rather than let the exception escape and suppress all tool
-// output. Withholding (not passing through) is the safe choice — content we
-// could not inspect for hidden payloads is treated as if it were hidden.
-export const UNPARSEABLE_PLACEHOLDER = "[HTML unparseable — withheld]";
 
 /**
  * `ranges` sorted by start with every overlap unioned — one entry per

package/src/layer2-placeholder.mjs

@@ -0,0 +1,60 @@
+/**
+ * The Layer-2 placeholder grammar: the one producer of keyed splice
+ * placeholders, the regex that parses them, and the un-keyed marker for a
+ * withheld unparseable input. `./html.mjs` re-exports all three as its public
+ * API; the hooks reach them through claude-hooks/lib/placeholder-grammar.mjs.
+ *
+ * Split out of `./html.mjs` because that module loads the remark/rehype/unified
+ * graph (~200ms) at import, and the hooks that only PARSE placeholders — the
+ * PreToolUse rehydrator on every Edit/Write, the PostToolUse span persistence —
+ * must not pay for it. This module imports nothing but `node:crypto`.
+ */
+import { createHash } from "node:crypto";
+
+// 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.
+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 {"comment" | "hidden"} 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;
+
+// Shown when the remark/rehype parse itself fails (e.g. a RangeError from
+// pathologically nested markup). `sanitize` never throws, so the HTML layer
+// fails CLOSED by withholding the whole input behind this one placeholder:
+// content it could not inspect for hidden payloads is treated as hidden.
+export const UNPARSEABLE_PLACEHOLDER = "[HTML unparseable — withheld]";

package/types/claude-hooks/lib/layer-pipeline.d.mts

@@ -6,60 +6,40 @@
  * @returns {boolean}
  */
 export function needsFixedPoint(layers: Layer[]): boolean;
+/**
+ * The `fault` reason for a body that never settled, naming the stages still
+ * rewriting on the last pass so a reader knows which one oscillates.
+ * @param {string[]} stillChanging
+ * @returns {string}
+ */
+export function nonConvergenceReason(stillChanging: string[]): string;
 /**
  * Run a declared layer chain over one tool input.
  *
- * Returns the final input, whether anything changed, and the model-facing notes
- * in the order they were produced (deduplicated: a fixed-point re-run that
- * repeats a layer's note would otherwise say the same thing twice). A layer that
- * denies ends the run immediately, with `deny` set.
+ * Returns the final input, whether any stage really changed it, and the
+ * model-facing notes of those stages, in order and deduplicated (a fixed-point
+ * re-run would otherwise repeat a note). A stage
+ * that denies ends the run immediately, with `deny` set. A body that never
+ * settles sets `fault` (the reason) alongside the last pass's sanitized
+ * `updatedInput`, and still runs the terminal stages, so a call that proceeds
+ * carries the same rehydration a settled one would. The verdict is the
+ * caller's: this driver renders none.
  * @param {string} tool
  * @param {any} toolInput
  * @param {Layer[]} layers
- * @returns {Promise<{ updatedInput: any, changed: boolean, contexts: string[], deny?: string }>}
+ * @returns {Promise<{ updatedInput: any, changed: boolean, contexts: string[], deny?: string, fault?: string }>}
  */
 export function runLayerPipeline(tool: string, toolInput: any, layers: Layer[]): Promise<{
     updatedInput: any;
     changed: boolean;
     contexts: string[];
     deny?: string;
+    fault?: string;
 }>;
-/**
- * The PreToolUse layer chain as a DECLARED pipeline instead of a run of
- * sequential statements.
- *
- * The confusable fold (Layer 2) carries a soundness precondition: it deliberately
- * SKIPS a token that still holds an unmapped non-ASCII glyph, because such a
- * token can never come out byte-equal to an ASCII deny-rule target, so folding it
- * would only mangle real foreign-language text. That argument holds only while no
- * later layer ERASES code points from the same field — if it does, the glyph the
- * fold relied on can disappear after the decision was taken.
- *
- * Layer 3 (authored-content stripping) erases exactly that: payload-capable
- * invisible characters. Running it after the fold made the precondition false,
- * and the gap was reachable: `cat /etc/p<CYRILLIC A><12 x ZWSP>sswd` put the
- * zero-width run inside the token, so the fold skipped it, then the strip removed
- * the padding and emitted `cat /etc/p<CYRILLIC A>sswd` — the homoglyph intact and
- * the evidence for skipping it gone. Zero-width padding suppressed the fold and
- * the next layer erased the reason.
- *
- * The eliminator is structural: layers declare whether they ERASE code points and
- * whether their decision is SKIP-BASED (suppressible by code points another layer
- * erases), and this driver enforces the precondition rather than a comment
- * asking a future reader to preserve it. When the table puts an erasing layer
- * after a skip-based one, the driver re-runs the body to a FIXED POINT, so the
- * emitted value is one every skip-based layer has seen in its final form. A table
- * that needs no fixed point runs exactly once, so the cost is paid only by the
- * ordering that creates the hazard.
- *
- * Layers may be `terminal`: run once, after the fixed point, never re-run. That
- * is Layer 4 (rehydration), whose whole contract is that it sees the FINAL
- * authored text and its restored secrets are not re-stripped by Layer 3. Terminal
- * layers must be a suffix of the table, which the driver checks.
- */
 /**
  * A layer's result: the rewritten input plus the model-facing note, a `deny`
- * verdict that ends the pipeline, or null when the layer changed nothing.
+ * verdict that ends the pipeline, or null when the layer changed nothing. A
+ * rewrite deep-equal to its input counts as null, whatever the layer reports.
  * @typedef {{ updatedInput: any, context: string } | { deny: string } | null} LayerResult
  */
 /**
@@ -79,16 +59,17 @@ export function runLayerPipeline(tool: string, toolInput: any, layers: Layer[]):
  */
 /**
  * Bound on fixed-point passes. Each pass either changes the input or ends the
- * loop, and the layers are contractive in practice (folding and stripping both
- * shrink the space of remaining findings), so a run that is still changing after
- * this many passes is a layer that oscillates — a bug. Throwing hands it to the
- * hook's fail-closed catch, which is the loud outcome; looping forever would be
- * silently killed by the harness and read as a non-blocking pass (fail OPEN).
+ * loop, and the stages are contractive in practice (folding and stripping both
+ * shrink the space of remaining findings), so a body still changing after this
+ * many passes holds a stage that oscillates. That yields a `fault` (see
+ * {@link runLayerPipeline}); looping forever would instead be killed by the
+ * harness, which reads a killed PreToolUse hook as a non-blocking pass.
  */
 export const MAX_PIPELINE_PASSES: 8;
 /**
  * A layer's result: the rewritten input plus the model-facing note, a `deny`
- * verdict that ends the pipeline, or null when the layer changed nothing.
+ * verdict that ends the pipeline, or null when the layer changed nothing. A
+ * rewrite deep-equal to its input counts as null, whatever the layer reports.
  */
 export type LayerResult = {
     updatedInput: any;

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

@@ -94,29 +94,6 @@ export const PLACEHOLDER_LABEL_CHARS: "A-Za-z0-9 ()._-";
  * `grep "\[REDACTED"`) is not mistaken for a placeholder.
  */
 export const PLACEHOLDER_RE: RegExp;
-/**
- * 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 UNPARSEABLE_MARKER: "[HTML unparseable \u2014 withheld]";
 export const REHYDRATED_TOOLS: Set<string>;
 /**
  * One found token: the exact placeholder text and the dotted field path of the
@@ -126,3 +103,6 @@ export type FoundPlaceholder = {
     token: string;
     path: string;
 };
+import { LAYER2_PLACEHOLDER_RE } from "../../src/layer2-placeholder.mjs";
+import { UNPARSEABLE_PLACEHOLDER } from "../../src/layer2-placeholder.mjs";
+export { LAYER2_PLACEHOLDER_RE, UNPARSEABLE_PLACEHOLDER as UNPARSEABLE_MARKER };