agent-sanitizer 2.19.2 → 2.19.4

package/claude-hooks/scan-invisible-chars.mjs

@@ -9,13 +9,20 @@ import { readFileSync, globSync, writeFileSync, unlinkSync } from "node:fs";
 import { join, relative } from "node:path";
 import {
   awaitLazyDependency,
+  safeErrMessage,
   hookgateMarkerPath,
+  HookEvent,
   isMain,
   lazyImport,
   markerIsTrusted,
   probeSetupAlive,
   writeFileNoFollow,
 } from "./lib/hook-io.mjs";
+import {
+  registerFaultPolicy,
+  hookFaultOutcome,
+  writeFaultOutcome,
+} from "./lib/hook-fault.mjs";
 import {
   ALERT_FILE,
   ALERT_ACK_FILE,
@@ -77,6 +84,69 @@ async function ensureSanitizerLoaded() {
   /* c8 ignore stop */
 }
 
+const HOOK_NAME = "scan-invisible-chars";
+
+/**
+ * The stderr line both posture arms share: what broke, and what it cost.
+ * @param {{ message: string }} ctx
+ * @returns {string}
+ */
+function faultLine(ctx) {
+  return (
+    `${HOOK_NAME}: ${ctx.message}. Instruction files were NOT fully scanned ` +
+    "for hidden Unicode, so any payload in them reaches the model unvetted."
+  );
+}
+
+// This hook's entry in the one posture table (lib/hook-fault.mjs). It has no
+// stdout verdict channel — SessionStart cannot deny — so BOTH arms are stated
+// explicitly rather than taking the shared additionalContext default: the only
+// enforcement a SessionStart hook can reach is the cross-hook alert, which makes
+// the PreToolUse gate ask once on the next tool call.
+registerFaultPolicy(HOOK_NAME, {
+  event: HookEvent.SESSION_START,
+  guarded: "instruction files",
+  open: (ctx) => ({
+    stderr: `${faultLine(ctx)} Passing through unguarded; set AGENT_SANITIZER_FAIL_OPEN=0 to arm the tool-call gate instead.\n`,
+    exitCode: 1,
+  }),
+  closed: (ctx) => ({
+    stderr: `${faultLine(ctx)} Arming the tool-call gate (AGENT_SANITIZER_FAIL_OPEN=0).\n`,
+    exitCode: 1,
+    armAlert: true,
+  }),
+});
+
+/**
+ * Render this hook's fault under the declared posture, and return the text (if
+ * any) that must ride in the cross-hook alert so a later gate carries the
+ * posture this hook cannot express itself.
+ * @param {unknown} err
+ * @returns {string[]}
+ */
+function reportFault(err) {
+  const outcome = hookFaultOutcome(HOOK_NAME, err);
+  process.exitCode = writeFaultOutcome(outcome);
+  return outcome.armAlert ? [/** @type {string} */ (outcome.stderr)] : [];
+}
+
+/**
+ * Persist the accumulated alert text for the PreToolUse gate, or leave the alert
+ * absent when there is nothing to surface.
+ *
+ * ALERT_FILE sits at a predictable, world-visible $TMPDIR path, so a plain
+ * writeFileSync would follow a co-tenant-planted symlink and overwrite an
+ * arbitrary file this uid owns. Create it symlink-refusingly (see
+ * writeFileNoFollow); the gate treats an absent alert as "nothing to surface",
+ * so a lost race degrades safely rather than to a hijacked write.
+ * @param {string[]} parts
+ * @returns {void}
+ */
+function persistAlert(parts) {
+  if (parts.length === 0) return;
+  writeFileNoFollow(ALERT_FILE, parts.join("\n") + "\n");
+}
+
 // Decoder
 
 /**
@@ -249,50 +319,118 @@ export { formatReport };
 
 // Main (skip when imported for testing)
 
-// Stryker disable all: CLI-entry body. It runs only as a spawned subprocess,
-// which in-process tests can't observe, so every mutant here is unkillable by
-// construction (same boundary as the c8-ignored regions below). The exported
-// scanFile/decodeRun above carry the real, mutation-tested logic.
 /**
- * Scan every instruction file under the project for invisible-char findings.
- * @returns {Array<{file: string, findings: ReturnType<typeof scanFile>}>}
+ * Scan every instruction file under the project, ACCOUNTING for every target
+ * the finder returned: `scanned + skipped.length === targets.length`, always.
+ *
+ * The accounting is the point. This scan is the only thing standing between a
+ * poisoned `CLAUDE.md` and a session that loads it as instructions, and its
+ * caller announces "clean" on the trace channel — the channel that exists so a
+ * MISSING announcement is loud. A per-file failure swallowed into an empty
+ * findings list turns "we could not read this file" into "this file is fine",
+ * which is the one lie this hook must never tell. So a file that cannot be read
+ * is REPORTED as unscanned, not dropped.
+ *
+ * ANY errno is a skip; only a non-filesystem throw propagates. The split is
+ * between "this file could not be read" (report it and keep scanning) and "this
+ * code is broken" (a TypeError from an unloaded binding — nothing here can be
+ * trusted, so it goes to the caller's declared failure posture). Catching only
+ * ENOENT would invert the enforcement: one EACCES target would discard the
+ * result for EVERY other instruction file, leaving them unscanned and
+ * un-auto-cleaned, and under the shipped OPEN posture the hook fault arms
+ * nothing — so the SUSPICIOUS failure would get weaker enforcement than the
+ * benign glob race, which reaches `partial` and arms the gate. Same errno-vs-bug
+ * split {@link autoCleanFindings} uses.
+ * @param {string} [dir]  project root to scan (injectable for tests)
+ * @returns {{
+ *   targets: string[],
+ *   scanned: number,
+ *   findings: Array<{file: string, findings: ReturnType<typeof scanFile>}>,
+ *   skipped: Array<{file: string, reason: string}>,
+ * }}
  */
-function scanProject() {
+export function scanProject(dir = PROJECT_DIR) {
   const targets = [
     ...new Set([
-      ...findInstructionFiles(PROJECT_DIR),
-      ...findMdFiles(join(PROJECT_DIR, ".claude")),
+      ...findInstructionFiles(dir),
+      ...findMdFiles(join(dir, ".claude")),
     ]),
   ];
-  const allFindings = [];
+  const findings = [];
+  const skipped = [];
+  let scanned = 0;
   for (const file of targets) {
+    let fileFindings;
     try {
-      const findings = scanFile(file);
-      if (findings.length > 0) {
-        allFindings.push({ file: relative(PROJECT_DIR, file), findings });
-      }
-    } catch {
-      // File doesn't exist or unreadable
+      fileFindings = scanFile(file);
+    } catch (err) {
+      if (/** @type {NodeJS.ErrnoException} */ (err).code === undefined)
+        throw err;
+      // safeErrMessage, not errMessage: this reason is rendered into stderr and
+      // into ALERT_FILE, and an errno message embeds the absolute path globbed
+      // out of a possibly-hostile repo — a filename carrying ANSI or invisible
+      // bytes would otherwise reach the operator's terminal raw.
+      skipped.push({ file: relative(dir, file), reason: safeErrMessage(err) });
+      continue;
     }
+    scanned++;
+    if (fileFindings.length > 0)
+      findings.push({ file: relative(dir, file), findings: fileFindings });
   }
-  return allFindings;
+  return { targets, scanned, findings, skipped };
 }
 
+/**
+ * The report for targets the scan could not read. Rendered into the alert the
+ * PreToolUse gate surfaces, so an incomplete scan reaches the operator as a
+ * checkpoint rather than as silence.
+ * @param {Array<{file: string, reason: string}>} skipped
+ * @returns {string}
+ */
+export function formatSkipped(skipped) {
+  return [
+    "",
+    "━━━ INSTRUCTION FILES NOT SCANNED ━━━",
+    "",
+    "These files load as project instructions but could NOT be read, so they",
+    "were never checked for hidden Unicode. Treat their content as unvetted.",
+    "",
+    ...skipped.map(({ file, reason }) => `  ${file}: ${reason}`),
+    "",
+  ].join("\n");
+}
+
+// Stryker disable all: CLI-entry body. It runs only as a spawned subprocess,
+// which in-process tests can't observe, so every mutant here is unkillable by
+// construction (same boundary as the c8-ignored regions below). The exported
+// scanFile / decodeRun / scanProject above carry the real, tested logic.
 /**
  * The hook's CLI: scan the instruction files, auto-clean what it can, persist
  * the alert for the PreToolUse gate otherwise. Exported so a bundle entry
  * (which must claim the CLI slot before this module loads) can run the exact
  * same scan instead of duplicating it.
- * @param {{ trace?: import("./lib/trace.mjs").TraceFn }} [opts]  `trace` is where
- *   this scan announces engagement; a host with its own trace channel passes its
- *   sink so the announcement lands where its detector reads (see lib/trace.mjs).
+ * @param {{
+ *   trace?: import("./lib/trace.mjs").TraceFn,
+ *   scan?: () => ReturnType<typeof scanProject>,
+ * }} [opts]  `trace` is where this scan announces engagement; a host with its
+ *   own trace channel passes its sink so the announcement lands where its
+ *   detector reads (see lib/trace.mjs). `scan` is the scanner, injectable so the
+ *   FAULT path below — a scanner that throws something other than an errno, i.e.
+ *   a bug — is drivable end to end; no filesystem state can force it, and an
+ *   untested fault path is how a posture goes missing in the first place.
  * @returns {Promise<void>}
  */
-export async function cliMain({ trace: sink = trace } = {}) {
+export async function cliMain({ trace: sink = trace, scan: runScan } = {}) {
   // Bound best-effort: the announcements below run BEFORE the auto-clean and
   // the alert write, with no catch above them, so a throwing host sink would
   // abort the scan silently (see bestEffortTrace).
   const emitTrace = bestEffortTrace(sink);
+  // Everything the PreToolUse gate must surface this session, written once at
+  // the end: an incomplete scan and an uncleanable file are independent reasons
+  // to arm the gate, and two separate writes would have the second clobber the
+  // first.
+  /** @type {string[]} */
+  const alertParts = [];
   /* c8 ignore start -- fail-closed module-load guard: only reachable when the
      agent-sanitizer import above failed, which can't be simulated in the
      spawned-subprocess CLI run the tests observe. */
@@ -301,11 +439,21 @@ export async function cliMain({ trace: sink = trace } = {}) {
     // the trace channel — a scan that never ran is otherwise invisible, and the
     // downstream PreToolUse sanitize gate then passes cleanly all session.
     emitTrace(TraceEvent.SCAN_INVISIBLE_CHARS_RAN, { outcome: "skipped" });
-    process.stderr.write(
-      "scan-invisible-chars: agent-sanitizer failed to load (node deps not " +
-        "installed and session-setup did not finish in time); instruction " +
-        "files were NOT scanned for hidden Unicode. Run `pnpm install`.\n",
+    // Through the shared posture table, NOT a bare exit(1): this hook took an
+    // advisory posture unconditionally, so an operator who pinned
+    // AGENT_SANITIZER_FAIL_OPEN=0 got only a warning on the one hook guarding
+    // session-start ingress, and the PreToolUse gate then passed cleanly for
+    // the rest of the session. The closed arm arms the cross-hook alert, which
+    // is the only channel a SessionStart hook has to make a later gate ask.
+    alertParts.push(
+      ...reportFault(
+        new Error(
+          "agent-sanitizer failed to load (node deps not installed and " +
+            "session-setup did not finish in time); run `pnpm install`",
+        ),
+      ),
     );
+    persistAlert(alertParts);
     process.exit(1);
   }
   /* c8 ignore stop */
@@ -320,22 +468,61 @@ export async function cliMain({ trace: sink = trace } = {}) {
     }
   }
 
-  const allFindings = scanProject();
+  // Only a non-errno throw reaches here — a bug in the scanner, not a file it
+  // could not read (those are accounted for in `skipped`). It is a fault of THIS
+  // hook, so it renders through the same posture table as every other hook's
+  // fault instead of aborting with no announcement at all.
+  let scan;
+  try {
+    scan = (runScan ?? scanProject)();
+  } catch (err) {
+    emitTrace(TraceEvent.SCAN_INVISIBLE_CHARS_RAN, { outcome: "skipped" });
+    alertParts.push(...reportFault(err));
+    persistAlert(alertParts);
+    return;
+  }
+  const { findings: allFindings, skipped, scanned } = scan;
 
-  if (allFindings.length === 0) {
+  // "clean" is a claim about EVERY target, so it may only be made when every
+  // target was read. A scan that could not read one says "partial" and arms the
+  // gate: an unread instruction file is UNVETTED context, not absent findings.
+  if (skipped.length > 0) {
+    emitTrace(TraceEvent.SCAN_INVISIBLE_CHARS_RAN, {
+      outcome: "partial",
+      scanned,
+      skipped: skipped.length,
+      files: allFindings.length,
+    });
+    const notice = formatSkipped(skipped);
+    process.stderr.write(notice + "\n");
+    alertParts.push(notice);
+  } else if (allFindings.length === 0) {
     emitTrace(TraceEvent.SCAN_INVISIBLE_CHARS_RAN, { outcome: "clean" });
     return;
+  } else {
+    emitTrace(TraceEvent.SCAN_INVISIBLE_CHARS_RAN, {
+      outcome: "found",
+      files: allFindings.length,
+    });
   }
-  emitTrace(TraceEvent.SCAN_INVISIBLE_CHARS_RAN, {
-    outcome: "found",
-    files: allFindings.length,
-  });
 
-  // Auto-clean contaminated files so the session proceeds without blocking
-  // every tool call; the gate hook is the fallback when cleaning fails.
+  if (allFindings.length > 0)
+    alertParts.push(...autoCleanFindings(allFindings, PROJECT_DIR));
+  persistAlert(alertParts);
+}
+
+/**
+ * Auto-clean the contaminated files so the session proceeds without blocking
+ * every tool call, and return the alert text for whatever could not be cleaned
+ * (empty when everything was). The gate hook is the fallback for the rest.
+ * @param {Array<{file: string, findings: ReturnType<typeof scanFile>}>} allFindings
+ * @param {string} dir  the root the finding paths are relative to
+ * @returns {string[]}
+ */
+function autoCleanFindings(allFindings, dir) {
   let cleaned = 0;
   for (const { file } of allFindings) {
-    const absPath = join(PROJECT_DIR, file);
+    const absPath = join(dir, file);
     try {
       const original = readFileSync(absPath, "utf-8");
       const stripped = stripInvisible(original);
@@ -344,15 +531,21 @@ export async function cliMain({ trace: sink = trace } = {}) {
         cleaned++;
       }
       /* c8 ignore start -- only fires on a file this uid cannot rewrite, which the test run cannot create */
-    } catch {
-      // Unreadable or unwritable: the file stays contaminated and falls into the
-      // alert path below, which hands it to the PreToolUse gate.
+    } catch (err) {
+      // Narrowed to filesystem errnos, and the reason is REPORTED rather than
+      // swallowed: an unwritable file legitimately falls through to the alert
+      // path below, but a throw from stripInvisible is a bug in the sanitizer
+      // and must not be laundered into "this file resisted cleaning".
+      if (/** @type {NodeJS.ErrnoException} */ (err).code === undefined)
+        throw err;
+      process.stderr.write(
+        `scan-invisible-chars: could not clean ${file}: ${safeErrMessage(err)}\n`,
+      );
     }
     /* c8 ignore stop */
   }
 
   const report = formatReport(allFindings);
-
   if (cleaned === allFindings.length) {
     process.stderr.write(
       report +
@@ -363,16 +556,11 @@ export async function cliMain({ trace: sink = trace } = {}) {
         "suspicion, and restart the session if in doubt. Future sessions load " +
         "the cleaned files.\n",
     );
-    /* c8 ignore start -- only reachable when the write catch above fires */
-  } else {
-    process.stderr.write(report + "\n");
-    // ALERT_FILE sits at a predictable, world-visible $TMPDIR path, so a plain
-    // writeFileSync would follow a co-tenant-planted symlink and overwrite an
-    // arbitrary file this uid owns. Create it symlink-refusingly (see
-    // writeFileNoFollow); the PreToolUse gate treats an absent alert as "nothing
-    // to surface", so a lost race degrades safely rather than to a hijacked write.
-    writeFileNoFollow(ALERT_FILE, report + "\n");
+    return [];
   }
+  /* c8 ignore start -- only reachable when the write catch above fires */
+  process.stderr.write(report + "\n");
+  return [report];
   /* c8 ignore stop */
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.19.2",
+  "version": "2.19.4",
   "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/ansi.mjs

@@ -0,0 +1,207 @@
+/**
+ * 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.
+ */
+
+// Raw control introducers that must not survive Layer 1: 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). Gating the whole C1 block, not
+// just the introducers the sequence grammar below names, fails closed: a
+// DCS/SOS/PM/APC string the grammar does not consume still loses its introducer
+// and terminator, so no terminal can hide-render its body as a control payload.
+//
+// A SOURCE STRING, not a literal: three call sites need it with different flags
+// (`g` for the Layer-1 sweep, unflagged for the prompt gate, `g` again to drive
+// the scan below), and spelling the class out at each site is how the three
+// copies came to spell the same byte two different ways — which defeats a
+// grep-based drift check as well. Building from `\uXXXX` escapes keeps every
+// raw control byte out of the source (no `no-control-regex` disable needed).
+export const CONTROL_INTRODUCER_SOURCE = "[\\u001b\\u0080-\\u009f]";
+
+// SGR (Select Graphic Rendition): colors, bold, reset. The grammar is closed:
+// params are [0-9;:]* and the final byte is `m`, so a match can only restyle
+// text — never reposition the cursor, erase, or smuggle an OSC string. `:` is
+// included alongside `;` because ITU T.416 colon-separated SGR sub-parameters
+// (truecolor `ESC[38:2:255:0:0m`, as emitted by tmux/kitty/mintty) are pure
+// display-only SGR too. A SGR sequence has TWO encodings: the 7-bit `ESC [ … m`
+// and the 8-bit C1 form where a single U+009B (CSI) replaces `ESC [`; both must
+// be recognized, or a C1-introduced `U+009B 31m … 0m` is pure color yet is
+// misread as a non-SGR payload.
+const SGR_SOURCE = "(?:\\u001b\\[|\\u009b)[0-9;:]*m";
+
+/**
+ * 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 = new RegExp(SGR_SOURCE, "g");
+
+// The same language, anchored — the SGR/CSI discriminator for a token the
+// scanner has already delimited.
+const SGR_ANCHORED_RE = new RegExp(`^${SGR_SOURCE}$`);
+
+// Private parameter-prefix and intermediate bytes that may follow an
+// introducer before the parameters (`ESC[?25h`, `ESC(B`, `ESC#8`). Also covers
+// the 7-bit `ESC [` CSI introducer's bracket itself.
+const CSI_INTRO_RE = /[[()#;?]/;
+
+// ECMA-48 parameter bytes.
+const CSI_PARAM_RE = /[0-9;:]/;
+
+// ECMA-48 final bytes, minus the ones a terminal never accepts here. Digits are
+// PARAMETER bytes and can never terminate a sequence — an unterminated `ESC[`
+// must not eat trailing visible digits (`ESC[2024 report` is NOT `ESC[` +
+// final-byte `2`; it is an incomplete intro whose ESC the residual sweep
+// removes, leaving "2024 report" intact). `<=>?` (0x3C-0x3F) are private
+// PARAMETER-prefix bytes per ECMA-48 § 5.4, not finals — including them let a
+// private-marker sequence terminate one byte too early. `~` (0x7E) IS a real
+// final byte (vt220 function keys, `ESC[3~` for Delete) and is kept.
+const CSI_FINAL_RE = /[A-PR-TZcf-nqrty~]/;
+
+const ESC = 0x1b;
+const CSI_C1 = 0x9b;
+const ST_C1 = 0x9c;
+const OSC_C1 = 0x9d;
+const BEL = 0x07;
+
+/** The four things an introducer can turn out to be. */
+export const TOKEN_KIND = Object.freeze({
+  /** 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",
+});
+
+/**
+ * @typedef {object} AnsiToken
+ * @property {number} start Index of the introducer.
+ * @property {number} end Index one past the last character of the token.
+ * @property {string} kind One of {@link TOKEN_KIND}.
+ */
+
+/**
+ * End index of the OSC string starting at `start`, or -1 if no OSC introducer
+ * is there.
+ *
+ * An OSC (Operating System Command) string is `<introducer> body <terminator>`:
+ * a title, a clickable-hyperlink URL, a clipboard write — i.e. attacker-
+ * controlled PAYLOAD TEXT. Consuming the introducer alone would leave that
+ * payload in the model's view, so the whole string is one token. Three ways it
+ * can end:
+ *   1. a real terminator — ST (`ESC\` or the 8-bit C1 ST U+009C) or the legacy
+ *      BEL — which is consumed with the body.
+ *   2. an ABORT: per ECMA-48/xterm a bare ESC (one not forming ST) drops the
+ *      terminal out of the OSC string, and a nested C1 OSC introducer likewise
+ *      starts something new. The token ends BEFORE that byte so the scan
+ *      re-reads it as its own sequence — without this, an interior ESC deleted
+ *      the rest of the document via case 3.
+ *   3. end of input, for a genuinely unterminated string: fail closed and drop
+ *      everything from the introducer on, so no OSC body survives.
+ * @param {string} text
+ * @param {number} start
+ * @returns {number}
+ */
+function scanOsc(text, start) {
+  const code = text.charCodeAt(start);
+  let i = -1;
+  if (code === OSC_C1) i = start + 1;
+  if (code === ESC && text[start + 1] === "]") i = start + 2;
+  if (i < 0) return -1;
+  for (; i < text.length; i++) {
+    const byte = text.charCodeAt(i);
+    if (byte === BEL || byte === ST_C1) return i + 1;
+    if (byte === ESC) return text[i + 1] === "\\" ? i + 2 : i;
+    if (byte === OSC_C1) return i;
+  }
+  return text.length;
+}
+
+/**
+ * End index of the CSI / two-byte escape sequence starting at `start`, or -1
+ * when the introducer completes no sequence.
+ *
+ * Single-pass and greedy: intro bytes, then parameter bytes, then exactly one
+ * final byte. The previous regex form had to BOUND the intro run ({0,12})
+ * because `;` lives in both the intro and parameter classes, so an unbounded
+ * run let a `;#;#…` string be split between the two quantifiers — quadratic
+ * backtracking (CodeQL js/polynomial-redos). A hand-written scanner never
+ * backtracks, so the bound is gone and the scan is linear by construction.
+ * @param {string} text
+ * @param {number} start
+ * @returns {number}
+ */
+function scanCsi(text, start) {
+  const code = text.charCodeAt(start);
+  if (code !== ESC && code !== CSI_C1) return -1;
+  let i = start + 1;
+  while (i < text.length && CSI_INTRO_RE.test(text[i])) i++;
+  while (i < text.length && CSI_PARAM_RE.test(text[i])) i++;
+  if (i < text.length && CSI_FINAL_RE.test(text[i])) return i + 1;
+  return -1;
+}
+
+// Drives the scan: jumping introducer-to-introducer keeps the common case (text
+// with no escapes at all) a single native regex scan rather than a per-character
+// JS loop.
+const INTRODUCER_SCAN_RE = new RegExp(CONTROL_INTRODUCER_SOURCE, "g");
+
+/**
+ * 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) {
+  /** @type {AnsiToken[]} */
+  const tokens = [];
+  INTRODUCER_SCAN_RE.lastIndex = 0;
+  let match;
+  while ((match = INTRODUCER_SCAN_RE.exec(text)) !== null) {
+    const start = match.index;
+    const oscEnd = scanOsc(text, start);
+    const csiEnd = oscEnd < 0 ? scanCsi(text, start) : -1;
+    let end = start + 1;
+    /** @type {string} */
+    let kind = TOKEN_KIND.ORPHAN;
+    if (oscEnd >= 0) {
+      end = oscEnd;
+      kind = TOKEN_KIND.OSC;
+    } else if (csiEnd >= 0) {
+      end = csiEnd;
+      kind = SGR_ANCHORED_RE.test(text.slice(start, csiEnd))
+        ? TOKEN_KIND.SGR
+        : TOKEN_KIND.CSI;
+    }
+    tokens.push({ start, end, kind });
+    INTRODUCER_SCAN_RE.lastIndex = end;
+  }
+  return tokens;
+}

package/src/confusables.mjs

@@ -38,8 +38,12 @@
  *
  * ORDERING: the soundness argument assumes no later layer erases code points
  * from the same field, which would let an unmapped glyph the gate relied on
- * disappear after the decision. Layer 4 runs before sanitizeAuthoredContent on
- * Bash.command; keep it there.
+ * disappear after the decision — a zero-width run padded into a token suppresses
+ * the fold, and the erasing layer then removes the very evidence for skipping it.
+ * This fold does NOT run last: on Bash.command the invisible-char strip follows
+ * it. A caller that composes the two is therefore responsible for re-running
+ * this fold on the post-erasure text until it reports nothing, which is what the
+ * hook driver in claude-hooks/lib/layer-pipeline.mjs does.
  *
  * Genuine non-confusable non-ASCII (accented Latin, CJK, emoji) is untouched
  * regardless, since a faithful scanner does not flag it.