agent-sanitizer 2.19.3 → 2.19.4

package/types/claude-hooks/scan-invisible-chars.d.mts

@@ -1,16 +1,86 @@
+/**
+ * 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}>,
+ * }}
+ */
+export function scanProject(dir?: string): {
+    targets: string[];
+    scanned: number;
+    findings: Array<{
+        file: string;
+        findings: ReturnType<typeof scanFile>;
+    }>;
+    skipped: Array<{
+        file: string;
+        reason: string;
+    }>;
+};
+/**
+ * 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: Array<{
+    file: string;
+    reason: string;
+}>): string;
 /**
  * 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 function cliMain({ trace: sink }?: {
+export function cliMain({ trace: sink, scan: runScan }?: {
     trace?: import("./lib/trace.mjs").TraceFn;
+    scan?: () => ReturnType<typeof scanProject>;
 }): Promise<void>;
+/**
+ * @param {string} filePath
+ * @returns {Array<{ line: number, charCount: number, method: string, decoded: string }>}
+ */
+export function scanFile(filePath: string): Array<{
+    line: number;
+    charCount: number;
+    method: string;
+    decoded: string;
+}>;
 /**
  * @param {string} run
  * @returns {{ method: string, decoded: string }}
@@ -39,16 +109,6 @@ export function findMdFiles(dir: string): string[];
  * @returns {string[]}
  */
 export function findInstructionFiles(dir: string): string[];
-/**
- * @param {string} filePath
- * @returns {Array<{ line: number, charCount: number, method: string, decoded: string }>}
- */
-export function scanFile(filePath: string): Array<{
-    line: number;
-    charCount: number;
-    method: string;
-    decoded: string;
-}>;
 import { ALERT_FILE } from "./lib/invisible-alert.mjs";
 import { ALERT_ACK_FILE } from "./lib/invisible-alert.mjs";
 export let LONG_RUN_RE: RegExp;

package/types/confusables.d.mts

@@ -113,8 +113,12 @@ export function normalizeConfusables(tool: string, toolInput: any, { scan, field
  *
  * 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.

package/types/invisible.d.mts

@@ -1,8 +1,15 @@
 /**
  * True when every ANSI control introducer in `text` belongs to a display-only
- * SGR color sequence (so stripping the ANSI removed only cosmetic styling,
+ * SGR color sequence (so stripping the ANSI removes only cosmetic styling,
  * nothing that could move the cursor, erase, or carry a payload). Recognizes
  * both the 7-bit `ESC[…m` and 8-bit C1 (`U+009B…m`) SGR encodings.
+ *
+ * Answered by the STRIPPER'S OWN tokenizer: scanAnsi emits one token per raw
+ * introducer — 7-bit ESC and the whole C1 block, so a C1 cursor-move
+ * (`U+009B 2J`), a C1-OSC string (`U+009D … BEL`), a C1-DCS/APC payload and a
+ * lone or partial escape each yield a non-SGR token — and the predicate is
+ * "every token is SGR". Because the same scan decides what Layer 1 splices,
+ * this can no longer report "colour only" for bytes the stripper leaves behind.
  * @param {string} text
  * @returns {boolean}
  */
@@ -84,7 +91,7 @@ export const CATEGORY_LABELS: Readonly<Record<string, string>>;
 /** @type {Array<[string, RegExp]>} Each entry pairs a CATEGORY code with its detector. */
 export const CHECKS: Array<[string, RegExp]>;
 export const STRIP: RegExp;
-export const SGR_RE: RegExp;
+export { SGR_RE } from "./ansi.mjs";
 export const LONG_RUN_THRESHOLD: 10;
 /** Total invisible-char count above which a file/prompt is treated as
  * payload-capable even without a long run (threshold-evasion catch). */
@@ -96,3 +103,5 @@ export const TOTAL_PRESERVED_JOINER_BUDGET: 16;
 export const PRESERVED_JOINER_PER_VISIBLE: 8;
 export const PRESERVE_HARD_CAP: 64;
 export const LINGUISTIC_SCRIPTS: string[];
+/** @type {ReadonlyArray<readonly [string, number, number]>} */
+export const BRAHMIC_CONSONANT_RANGES: ReadonlyArray<readonly [string, number, number]>;

package/types/layer1.d.mts

@@ -19,16 +19,25 @@ export function stripAnsiFully(input: string): string;
  * 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[] }}
  */