agent-sanitizer 2.19.3 → 2.19.4

package/src/layer1.mjs

@@ -13,98 +13,16 @@
  * point where a lone surrogate would otherwise corrupt a match or a parse.
  */
 import { stripInvisibleWithReport, CATEGORY } from "./invisible.mjs";
+import { CONTROL_INTRODUCER_SOURCE, scanAnsi, TOKEN_KIND } from "./ansi.mjs";
 
-// Raw control introducers that must not survive: 7-bit ESC (U+001B) and the
-// entire 8-bit C1 control block (U+0080–U+009F) — which includes CSI (U+009B),
-// the string introducers DCS/SOS/OSC/PM/APC (U+0090/0098/009D/009E/009F), and ST
-// (U+009C). All are category Cc, so the invisible-char pass (which targets Cf /
-// variation / blank fillers) never removes them; this residual sweep is the
-// guarantee that none survives. Sweeping the whole C1 block — not just the
-// introducers the ANSI grammar above names — fails closed: a DCS/SOS/PM/APC
-// string the grammar does not consume still loses its introducer and terminator
-// here, so no terminal can hide-render its body as a control payload.
-// eslint-disable-next-line no-control-regex -- matching the raw introducers is the point
-const CONTROL_INTRODUCER_RE = /[\u001b\u0080-\u009f]/g;
+// The ANSI grammar and the introducer charset live in ./ansi.mjs so this module
+// and invisible.mjs (which owns the public isSgrOnly / SGR_RE and cannot import
+// this one) scan with the SAME tokenizer.
 
-// An OSC (Operating System Command) string is `<introducer> … <terminator>`.
-// Introducer: 7-bit `ESC]` or 8-bit C1 OSC (U+009D). Terminator: ST (`ESC\` or
-// 8-bit C1 ST U+009C) OR the legacy BEL (U+0007). The body is everything up to
-// the terminator — a title, a clickable-hyperlink URL, a clipboard write — i.e.
-// attacker-controlled PAYLOAD TEXT. Matching the introducer alone (leaving the
-// body) would let that payload survive into the model's view, so the OSC branch
-// consumes the introducer, the whole body, AND the terminator as one unit.
-//
-// Three alternatives, tried in order:
-//   1. a properly TERMINATED string — a body of bytes that no terminator can
-//      start with (the negated class makes that run unambiguous and
-//      backtrack-free), then a terminator (ST or BEL).
-//   2. an ABORTED string — the body runs up to (but does NOT consume) an
-//      interior bare ESC or a nested C1-OSC introducer (U+009D) that is not
-//      itself part of a valid terminator. Per ECMA-48/xterm, a bare ESC (one
-//      not immediately followed by `\` to form ST) aborts the OSC string in
-//      progress — the terminal drops back to processing that ESC as the start
-//      of a NEW sequence, and everything after it is normal text/escapes, not
-//      part of this OSC's payload. Consuming only up to the lookahead (not
-//      the ESC/U+009D itself) leaves it for the next position in this same
-//      `.replace(ANSI_RE, ...)` scan to match as its own sequence (or, if it
-//      doesn't complete one, for the residual C1 sweep in applyLayer1 to
-//      remove just that one introducer byte) — so an interior ESC can no
-//      longer delete the rest of the document (it used to fall through to
-//      alternative 3 below and consume everything to EOS).
-//   3. anything else from the introducer to END-OF-STRING (`[\s\S]*$`) — the
-//      fail-closed catch-all for a GENUINELY unterminated string: no ST, BEL,
-//      interior ESC, or nested OSC intro anywhere in the remainder, so there
-//      is truly nothing left to hand to a later position. Reached only when
-//      alternatives 1 and 2 both fail to find their respective triggers.
-// All three are linear (bounded lookahead / no nested quantifiers), so the
-// branch stays linear.
-const OSC_INTRO = "(?:\\u001b\\]|\\u009d)";
-const OSC_TERM = "(?:\\u001b\\\\|\\u009c|\\u0007)";
-const OSC_BODY = "[^\\u0007\\u001b\\u009c\\u009d]";
-const OSC_BRANCH = `${OSC_INTRO}(?:${OSC_BODY}*${OSC_TERM}|${OSC_BODY}*(?=[\\u001b\\u009d])|${OSC_BODY}*$)`;
-
-// CSI / two-byte ESC sequences (cursor moves, erase, SGR color, charset/DEC
-// selectors): an introducer, a bounded private-intro run, optional numeric
-// params, and a single final byte. Not an enforcement boundary on its own — any
-// introducer this declines to match is still removed by the residual sweep in
-// applyLayer1 — but matching the whole sequence keeps the common case one clean
-// deletion (and avoids a lone-ESC residual on every styled line).
-//
-// The private-intro class is BOUNDED ({0,12}, not *) on purpose: ; and # live
-// in both this class and the parameter group that follows, so an unbounded *
-// here lets a ;#;#... run be split between the two quantifiers — O(n^2)
-// backtracking on an ESC;#;#... string that never completes a sequence
-// (CodeQL js/polynomial-redos). A constant bound makes the intro a constant
-// factor, so the whole match is linear; a real sequence never carries more than
-// a couple of intro bytes.
-//
-// Params allow BOTH `;` (standard parameter separator) and `:` (ITU T.416
-// colon-separated SGR sub-parameters, e.g. truecolor `ESC[38:2:255:0:0m` as
-// emitted by tmux/kitty/mintty) — legitimate, display-only ANSI that must not
-// leave a colon-parameter residue behind.
-//
-// The final-byte class deliberately excludes `\d`: per ECMA-48, CSI final
-// bytes occupy 0x40–0x7E (letters and a handful of punctuation) while digits
-// are PARAMETER bytes and can never terminate a sequence — an unterminated
-// `ESC[` therefore must not be allowed to eat trailing visible digits (e.g.
-// `ESC[2024 report` is NOT `ESC[` + final-byte `2` + literal `024 report`; it
-// is an incomplete CSI intro that the residual sweep in applyLayer1 cleans up,
-// leaving "2024 report" intact). `=`, `<`, `>` are excluded for the same
-// reason: 0x3C–0x3F (`<=>?`) are private PARAMETER-prefix bytes, not final
-// bytes, per ECMA-48 § 5.4 — `?` already lives in the private-intro class
-// above; `<=>` were never valid finals and including them let a private-marker
-// sequence terminate one byte too early. `~` (0x7E) IS a real final byte (vt220
-// function-key sequences, e.g. `ESC[3~` for Delete) and is kept.
-const CSI_BRANCH =
-  "[\\u001b\\u009b][[()#;?]{0,12}(?:(?:\\d{1,4}(?:[;:]\\d{0,4})*)?[A-PR-TZcf-ntqry~])";
-
-// Full ANSI escape grammar (OSC first so `ESC]` / C1-OSC is consumed as a whole
-// string, not split by the CSI branch), not just SGR: the Layer-1 guarantee is
-// that no control introducer and no OSC payload survives, and a cursor-move or
-// erase sequence is as much a display-spoofing hazard as a color one. Built from
-// `\uXXXX`-escaped string parts via `new RegExp`, so no raw control byte sits in
-// the source (no no-control-regex disable needed).
-const ANSI_RE = new RegExp(`(?:${OSC_BRANCH}|${CSI_BRANCH})`, "gu");
+// The residual sweep: every raw control introducer, whatever the grammar made of
+// it. This — not the sequence matching — is the guarantee that no introducer
+// survives Layer 1.
+const CONTROL_INTRODUCER_RE = new RegExp(CONTROL_INTRODUCER_SOURCE, "g");
 
 // Unpaired UTF-16 surrogates (high not followed by low, or low not preceded by
 // high). Normalized before any HTML parser, which throws on a stray byte —
@@ -114,6 +32,29 @@ export const LONE_SURROGATE_RE =
 
 const MAX_ANSI_PASSES = 3;
 
+/**
+ * Splice out every complete ANSI sequence {@link scanAnsi} finds — SGR, other
+ * CSI/two-byte escapes, and whole OSC strings. An ORPHAN introducer (one that
+ * starts no sequence) is deliberately LEFT: deleting it here would drop the
+ * `ESC` out of `ESC`<ZWSP>`[32m` before the invisible pass could reconstitute
+ * the sequence, turning a hidden control into visible `[32m` in the model's
+ * view. Orphans are removed by applyLayer1's residual sweep, once no
+ * reconstitution is possible.
+ * @param {string} text
+ * @returns {string}
+ */
+function stripAnsiOnce(text) {
+  let out = "";
+  let last = 0;
+  for (const token of scanAnsi(text)) {
+    if (token.kind === TOKEN_KIND.ORPHAN) continue;
+    out += text.slice(last, token.start);
+    last = token.end;
+  }
+  if (last === 0) return text;
+  return out + text.slice(last);
+}
+
 /**
  * Strip ANSI escape sequences to a fixed point. Removing one sequence can
  * reconstitute another around it (a lone ESC left of `ESC[32m[0m` gains the
@@ -131,54 +72,98 @@ const MAX_ANSI_PASSES = 3;
  */
 export function stripAnsiFully(input) {
   let prev = input;
-  let out = prev.replace(ANSI_RE, "");
+  let out = stripAnsiOnce(prev);
   for (let pass = 1; pass < MAX_ANSI_PASSES && out !== prev; pass++) {
     prev = out;
-    out = prev.replace(ANSI_RE, "");
+    out = stripAnsiOnce(prev);
   }
   return out;
 }
 
+// How many times the {ANSI strip, invisible strip} composition may re-run before
+// the sweep is forced. Each iteration deletes at least one character, so the
+// loop terminates on its own; the bound is a DoS guard on the same quadratic
+// argument as MAX_ANSI_PASSES (n rounds of O(n) scans on adversarial input).
+// Three rounds is what the deepest REAL reconstitution needs — strip
+// invisibles, remove the ANSI they hid, strip the joiners that ANSI removal
+// made adjacent, confirm — so four leaves a round of margin. Deeper nesting is
+// not reachable through the carve-out: preserving a joiner requires cursive or
+// emoji neighbours on BOTH sides, so a preserved joiner can never sit inside an
+// escape sequence, and every joiner that hides one is therefore stripped by the
+// FIRST invisible pass. Past the bound the composition simply stops early — the
+// final sweep still holds the no-introducer guarantee, and what is left degrades
+// to visible text (the fail-open direction), exactly as with MAX_ANSI_PASSES.
+const MAX_LAYER1_PASSES = 4;
+
 /**
  * Layer 1: ANSI + invisible-char strip with a result guaranteed free of every
  * raw ANSI control introducer (7-bit ESC U+001B and the whole 8-bit C1 control
  * block U+0080–U+009F: CSI, the DCS/SOS/OSC/PM/APC string introducers, and ST).
  *
- * Removing an invisible character can reconstitute an escape its split hid from
- * the ANSI pass (`ESC`<ZWSP>`[32m` → `ESC[32m`), so strip ANSI again after the
- * invisible pass — but only when stripInvisible changed something, since
- * reconstitution is impossible otherwise and the re-strip is a wasted pass on
- * the hot clean path. The ANSI strip still cannot match an *incomplete*
- * reconstituted sequence (a lone `ESC[` left when an inner complete sequence is
- * removed from a nested split), so a final sweep removes every residual raw
- * introducer outright — that sweep, not the regex matching, is the guarantee
- * that no control introducer survives. `deAnsi` is the ANSI strip of the
- * original (invisible runs intact), the scope a LONG_RUN payload check needs.
+ * The two passes FEED each other in both directions, so neither ordering is
+ * enough on its own and the composition is iterated to a fixed point instead:
+ * removing an invisible char reconstitutes an escape its split hid
+ * (`ESC`<ZWSP>`[32m` → `ESC[32m`), and removing an escape makes two invisibles
+ * ADJACENT that were not (`م ZWJ ESC[m ZWJ م` → a joiner run the invisible pass
+ * classifies as a payload channel rather than linguistic). A pipeline with a
+ * fixed number of alternations always leaves one of those unanswered — this used
+ * to re-strip ANSI after the invisible pass and stop, so `applyLayer1` was not
+ * idempotent and the rehydrator's "re-cleaning reproduces the view" assumption
+ * did not hold.
+ *
+ * The residual sweep runs only once the composition is STABLE, because sweeping
+ * an introducer early destroys the sequence a later ANSI pass would have removed
+ * whole, promoting a hidden control to visible text. A final UNCONDITIONAL sweep
+ * follows the loop so the no-raw-introducer guarantee does not depend on the
+ * pass bound.
+ *
+ * `deAnsi` is the ANSI strip of the ORIGINAL text (invisible runs intact), the
+ * scope a LONG_RUN payload check needs — not an intermediate of the loop.
  * @param {string} text
  * @returns {{ cleaned: string, deAnsi: string, found: string[] }}
  */
 export function applyLayer1(text) {
   const deAnsi = stripAnsiFully(text);
-  // stripInvisibleWithReport returns `found` for exactly the categories it
-  // removed — so a ZWNJ/ZWJ the carve-out PRESERVES never registers as a strip,
-  // and the leading-BOM exception is already handled inside it. Pass the ORIGINAL
-  // `text` so a BOM that was interior before the ANSI strip (`ESC[m + interior U+FEFF`, now at
-  // index 0 of `deAnsi`) is treated as interior and stripped, not preserved.
-  const { cleaned: afterInvis, found } = stripInvisibleWithReport(deAnsi, text);
-  let ansiFound = deAnsi.length !== text.length;
+  /** @type {Set<string>} Union of the categories every iteration reported. */
+  const found = new Set();
+  let cleaned = text;
+  let ansiFound = false;
 
-  let cleaned = afterInvis;
-  if (afterInvis !== deAnsi) {
-    const reStripped = stripAnsiFully(afterInvis);
-    if (reStripped.length !== afterInvis.length) ansiFound = true;
-    cleaned = reStripped;
+  for (let pass = 0; pass < MAX_LAYER1_PASSES; pass++) {
+    const afterAnsi = pass === 0 ? deAnsi : stripAnsiFully(cleaned);
+    if (afterAnsi !== cleaned) ansiFound = true;
+    // stripInvisibleWithReport returns `found` for exactly the categories it
+    // removed — so a ZWNJ/ZWJ the carve-out PRESERVES never registers as a
+    // strip. The second argument stays the ORIGINAL `text` on every iteration:
+    // the leading-BOM exception is defined against what the user actually sent,
+    // so a BOM that was interior before an ANSI strip shifted it to index 0 is
+    // treated as interior and stripped, not preserved.
+    const { cleaned: afterInvis, found: passFound } = stripInvisibleWithReport(
+      afterAnsi,
+      text,
+    );
+    for (const category of passFound) found.add(category);
+    if (afterInvis !== cleaned) {
+      cleaned = afterInvis;
+      continue;
+    }
+    // {ANSI, invisible} is stable: nothing left can reconstitute, so the
+    // residual introducers can be swept without hiding a sequence from a later
+    // pass. A sweep that changes the text feeds one more round (removing an
+    // introducer can make invisibles adjacent, exactly as removing a sequence
+    // can); one that changes nothing means the whole composition has converged.
+    const swept = cleaned.replace(CONTROL_INTRODUCER_RE, "");
+    if (swept === cleaned) break;
+    cleaned = swept;
+    ansiFound = true;
   }
+
   const swept = cleaned.replace(CONTROL_INTRODUCER_RE, "");
   if (swept !== cleaned) {
     cleaned = swept;
     ansiFound = true;
   }
 
-  if (ansiFound) found.push(CATEGORY.ANSI);
-  return { cleaned, deAnsi, found };
+  if (ansiFound) found.add(CATEGORY.ANSI);
+  return { cleaned, deAnsi, found: [...found] };
 }

package/src/prompt.mjs

@@ -27,6 +27,7 @@ import {
   isSgrOnly,
 } from "./invisible.mjs";
 import { stripAnsiFully } from "./layer1.mjs";
+import { CONTROL_INTRODUCER_SOURCE } from "./ansi.mjs";
 
 // Every raw ANSI control a prompt can carry: 7-bit ESC (U+001B) and the entire
 // 8-bit C1 block (U+0080-U+009F). Gating on ESC alone -- or on only CSI/OSC --
@@ -34,12 +35,14 @@ import { stripAnsiFully } from "./layer1.mjs";
 // (CSI erase), `U+009D 0;...BEL` (OSC), or the string introducers DCS (U+0090),
 // SOS (U+0098), PM (U+009E), APC (U+009F): Layer 1 strips it, dropping the
 // invisible count to zero, so the prompt reads clean and passes. This gate must
-// match Layer 1's residual sweep (CONTROL_INTRODUCER_RE) exactly -- no raw C1
-// control belongs in a legitimate prompt (the SGR color carve-out is applied
-// separately, after SGR removal), so the whole block is gated, not a hand-picked
-// subset that lets DCS/SOS/PM/APC through.
-// eslint-disable-next-line no-control-regex -- the raw control introducers are exactly what we detect
-const ANSI_INTRODUCER = /[\u001b\u0080-\u009f]/;
+// match Layer 1's residual sweep exactly -- no raw C1 control belongs in a
+// legitimate prompt (the SGR color carve-out is applied separately, after SGR
+// removal), so the whole block is gated, not a hand-picked subset that lets
+// DCS/SOS/PM/APC through. Built from the SHARED charset source instead of a
+// third hand-written copy: keeping the copies in step used to be a prose
+// obligation recorded in this very comment, and two of the three spelled ESC
+// differently, so even a grep-based drift check would have missed a divergence.
+const ANSI_INTRODUCER = new RegExp(CONTROL_INTRODUCER_SOURCE);
 
 /**
  * True when every ANSI introducer in `prompt` belongs to a display-only SGR

package/types/ansi.d.mts

@@ -0,0 +1,66 @@
+/**
+ * Tokenize every raw control introducer in `text`.
+ *
+ * Every introducer yields exactly one token — an ORPHAN when it starts nothing
+ * the grammar recognizes — so "which introducers are in this text" and "which
+ * sequences are in this text" are answered by the same scan. That is what lets
+ * the stripper (splice every non-orphan token, then sweep) and the SGR-only
+ * predicate (every token is SGR) agree by construction.
+ *
+ * Tokens are disjoint and ordered by `start`; each `end` is strictly greater
+ * than its `start`, so the scan always advances.
+ * @param {string} text
+ * @returns {AnsiToken[]}
+ */
+export function scanAnsi(text: string): AnsiToken[];
+/**
+ * The ONE ANSI grammar: the raw control-introducer charset and the tokenizer
+ * every consumer scans with.
+ *
+ * Two modules need this grammar and they cannot import each other —
+ * `layer1.mjs` imports `invisible.mjs`, so `invisible.mjs` (which owns the
+ * public `isSgrOnly` / `SGR_RE`) must not import back. Before this module the
+ * grammar was therefore written out twice with DIFFERENT param rules
+ * (`invisible.mjs`'s SGR regex accepted any digit run, `layer1.mjs`'s CSI
+ * branch capped each parameter at four digits), and the introducer charset
+ * three times. The looser copy suppressed the operator warning for a sequence
+ * the stripper could not match: `ESC[12345m` read as "display-only colour"
+ * while `[12345m` was spliced into the model's view as visible text. One
+ * tokenizer, one charset, consumed by both — the disagreement cannot recur.
+ *
+ * Same precedent (and same reason) as `cf-charset.mjs`: a dependency-free leaf
+ * module both layers read from.
+ */
+export const CONTROL_INTRODUCER_SOURCE: "[\\u001b\\u0080-\\u009f]";
+/**
+ * Public alias kept for compatibility (re-exported by `invisible.mjs` and the
+ * package root). It is now DERIVED: {@link scanAnsi} classifies a token as SGR
+ * by testing the token's own text against this exact source, so the predicate
+ * and the regex can no longer describe different languages.
+ */
+export const SGR_RE: RegExp;
+/** The four things an introducer can turn out to be. */
+export const TOKEN_KIND: Readonly<{
+    /** A display-only `ESC[…m` / `U+009B…m` colour sequence. */
+    SGR: "sgr";
+    /** Any other complete CSI / two-byte escape (cursor move, erase, charset). */
+    CSI: "csi";
+    /** An OSC string: introducer, body and terminator as one unit. */
+    OSC: "osc";
+    /** An introducer that starts no sequence the grammar recognizes. */
+    ORPHAN: "orphan-introducer";
+}>;
+export type AnsiToken = {
+    /**
+     * Index of the introducer.
+     */
+    start: number;
+    /**
+     * Index one past the last character of the token.
+     */
+    end: number;
+    /**
+     * One of {@link TOKEN_KIND}.
+     */
+    kind: string;
+};

package/types/claude-hooks/lib/hook-fault.d.mts

@@ -0,0 +1,104 @@
+/**
+ * Declare a hook's failure posture. Called at module scope by each hook, so
+ * importing the hook is what makes its posture reachable.
+ * @param {string} hook  a member of {@link FAULT_POLICY_HOOKS}
+ * @param {FaultPolicy} policy
+ * @returns {void}
+ */
+export function registerFaultPolicy(hook: string, policy: FaultPolicy): void;
+/**
+ * The registered policy for `hook`. Throws rather than defaulting: a hook whose
+ * posture nobody declared has no defensible default — guessing OPEN would let
+ * the guarded action through on a hook an operator believed was strict, and
+ * guessing CLOSED would block a session on a wiring bug.
+ * @param {string} hook
+ * @returns {FaultPolicy}
+ */
+export function faultPolicy(hook: string): FaultPolicy;
+/**
+ * Resolve `hook`'s response to its own failure under the caller's posture. This
+ * is the ONLY place {@link failOpenEnabled} is consulted on a hook fault, so the
+ * knob cannot be honored in three hooks and skipped in the fourth.
+ * @param {string} hook
+ * @param {unknown} err
+ * @param {Record<string, any> & {
+ *   env?: NodeJS.ProcessEnv | Record<string, string | undefined>,
+ * }} [ctx]  hook-specific inputs threaded to the builders (a message table, the
+ *   parsed input, a remedy). `env` selects the posture; it is threaded to the
+ *   builders along with the rest, though none reads it — the posture is resolved
+ *   here precisely so a builder never has to.
+ * @returns {FaultOutcome}
+ */
+export function hookFaultOutcome(hook: string, err: unknown, ctx?: Record<string, any> & {
+    env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+}): FaultOutcome;
+/**
+ * Render an outcome's stdout/stderr halves and return its exit code. The caller
+ * decides what to do with the code (a hook that must keep running ignores it),
+ * and performs `armAlert` itself — persisting the alert needs the hook's own
+ * report text, which this module has no view of.
+ * @param {FaultOutcome} outcome
+ * @param {(chunk: string) => void} [write]
+ * @param {(chunk: string) => void} [writeErr]
+ * @returns {number}
+ */
+export function writeFaultOutcome(outcome: FaultOutcome, write?: (chunk: string) => void, writeErr?: (chunk: string) => void): number;
+/**
+ * The hook modules that must register a fault policy — every CLI entry point in
+ * `claude-hooks/*.mjs`. Declared here rather than discovered so registering an
+ * unknown name is an error instead of a typo nobody notices.
+ * @type {readonly string[]}
+ */
+export const FAULT_POLICY_HOOKS: readonly string[];
+/**
+ * What a hook's fault renders to. `fields`/`envelope` are the stdout response
+ * (`fields` is the `hookSpecificOutput` body, wrapped with the policy's event;
+ * `envelope` is a hook that answers with a top-level shape instead, like
+ * UserPromptSubmit's `{decision:"block"}`); `stderr` and `exitCode` are the
+ * process-level halves a hook with no stdout channel uses; `armAlert` asks the
+ * caller to persist its cross-hook alert so a LATER gate carries the closed
+ * posture the faulting hook could not express itself.
+ */
+export type FaultOutcome = {
+    posture: "open" | "closed";
+    fields: Record<string, unknown> | null;
+    fallbackFields: Record<string, unknown> | null;
+    envelope: object | null;
+    stderr: string | null;
+    exitCode: number;
+    armAlert: boolean;
+};
+/**
+ * What a policy's `open`/`closed` builder returns: any subset of a
+ * {@link FaultOutcome}'s renderable slots. Everything omitted takes its default
+ * (no output, exit 0, no alert).
+ */
+export type FaultParts = {
+    fields?: Record<string, unknown>;
+    fallbackFields?: Record<string, unknown>;
+    envelope?: object;
+    stderr?: string;
+    exitCode?: number;
+    armAlert?: boolean;
+};
+/**
+ * The context a builder is handed: the caller's own inputs (whatever it passed
+ * to {@link hookFaultOutcome}) plus the three values every hook derived by hand
+ * before — the hook name, the scrubbed error message, and the model-facing
+ * open-posture warning.
+ */
+export type FaultContext = Record<string, any> & {
+    hook: string;
+    err: unknown;
+    message: string;
+    openContext: string;
+};
+/**
+ * A hook's declared posture.
+ */
+export type FaultPolicy = {
+    event: string | null;
+    guarded: string;
+    open?: (ctx: FaultContext) => FaultParts;
+    closed: (ctx: FaultContext) => FaultParts;
+};

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

@@ -0,0 +1,113 @@
+/**
+ * Whether `layers` places an erasing layer after a skip-based one — the ordering
+ * whose soundness needs a fixed point. Exported so the property is assertable
+ * about a table directly, not only through a run.
+ * @param {Layer[]} layers
+ * @returns {boolean}
+ */
+export function needsFixedPoint(layers: Layer[]): boolean;
+/**
+ * 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.
+ * @param {string} tool
+ * @param {any} toolInput
+ * @param {Layer[]} layers
+ * @returns {Promise<{ updatedInput: any, changed: boolean, contexts: string[], deny?: string }>}
+ */
+export function runLayerPipeline(tool: string, toolInput: any, layers: Layer[]): Promise<{
+    updatedInput: any;
+    changed: boolean;
+    contexts: string[];
+    deny?: 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.
+ * @typedef {{ updatedInput: any, context: string } | { deny: string } | null} LayerResult
+ */
+/**
+ * One declared layer.
+ * - `erases` — may REMOVE code points from a field another layer reads. This is
+ *   the property that can invalidate a skip-based decision taken earlier.
+ * - `skipBased` — its decision can be suppressed by code points present at the
+ *   time it ran. Such a layer must be re-run after any erasure.
+ * - `terminal` — runs once after the fixed point and is never re-run.
+ * @typedef {{
+ *   name: string,
+ *   erases: boolean,
+ *   skipBased: boolean,
+ *   terminal?: boolean,
+ *   run: (tool: string, input: any) => LayerResult | Promise<LayerResult>,
+ * }} 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).
+ */
+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.
+ */
+export type LayerResult = {
+    updatedInput: any;
+    context: string;
+} | {
+    deny: string;
+} | null;
+/**
+ * One declared layer.
+ * - `erases` — may REMOVE code points from a field another layer reads. This is
+ *   the property that can invalidate a skip-based decision taken earlier.
+ * - `skipBased` — its decision can be suppressed by code points present at the
+ *   time it ran. Such a layer must be re-run after any erasure.
+ * - `terminal` — runs once after the fixed point and is never re-run.
+ */
+export type Layer = {
+    name: string;
+    erases: boolean;
+    skipBased: boolean;
+    terminal?: boolean;
+    run: (tool: string, input: any) => LayerResult | Promise<LayerResult>;
+};

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

@@ -1,3 +1,19 @@
+/**
+ * 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,
+ * and whether its own decision is SKIP-BASED and therefore invalidated by such
+ * an erasure — so the confusable fold's ordering precondition is enforced by the
+ * table instead of restated as a comment.
+ *
+ * Layer 3 is dropped from the table (not merely skipped at run time) when
+ * AGENT_SANITIZER_OUTPUT_DISABLED=1, so the driver sees the chain that will
+ * actually run: with no erasing layer left after the fold there is no fixed
+ * point to reach and no extra pass to pay for.
+ * @param {(tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>} rehydrate
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ * @returns {import("./lib/layer-pipeline.mjs").Layer[]}
+ */
+export function preToolUseLayers(rehydrate: (tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>, env?: NodeJS.ProcessEnv | Record<string, string | undefined>): import("./lib/layer-pipeline.mjs").Layer[];
 /**
  * Compose the four protections. Returns the `hookSpecificOutput` fields to
  * emit, or null for a clean no-op. Throws only if a layer's engine throws; the