agent-sanitizer 2.23.2 → 2.24.1

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

@@ -67,10 +67,28 @@ export function formatSkipped(skipped: Array<{
  *   untested fault path is how a posture goes missing in the first place.
  * @returns {Promise<void>}
  */
-export function cliMain({ trace: sink, scan: runScan }?: {
+export function cliMain(opts?: {
     trace?: import("./lib/trace.mjs").TraceFn;
     scan?: () => ReturnType<typeof scanProject>;
 }): Promise<void>;
+/**
+ * The `.claude/` subdirectories whose markdown Claude Code loads as model
+ * context. This is a WHITELIST, and that is the point: `.claude/` is also where
+ * tooling parks bulk data that is never loaded as context — `worktrees/`
+ * (entire checked-out copies of the repo), plus caches, transcripts and
+ * snapshots — and globbing `.claude/**` swept all of it in. On a repo with a few
+ * populated worktrees that is thousands of files READ at every session start:
+ * one report put it at 30 seconds of blocked startup, paid for scanning files
+ * that cannot reach the model.
+ *
+ * A whitelist, not a `worktrees` denylist, because the failure modes are not
+ * symmetric: an unlisted context directory costs a scan this hook was never
+ * asked for anyway (the PostToolUse sanitizer still cleans those bytes when a
+ * tool reads them), while an unlisted BULK directory silently costs every future
+ * session its startup. Add an entry here when Claude Code starts loading a new
+ * `.claude/` subdirectory as context.
+ */
+export const CLAUDE_CONTEXT_SUBDIRS: readonly string[];
 /**
  * @param {string} filePath
  * @returns {Array<{ line: number, charCount: number, method: string, decoded: string }>}
@@ -90,21 +108,20 @@ export function decodeRun(run: string): {
     decoded: string;
 };
 /**
- * @param {string} dir
- * @returns {string[]}
- */
-export function findMdFiles(dir: string): string[];
-/**
- * Every subdirectory instruction file (CLAUDE.md, CLAUDE.local.md, AGENTS.md)
- * under `dir`. Claude Code loads these as project instructions on entry to their
- * containing directory — a load path that bypasses the PostToolUse sanitizer — so
- * a payload planted in e.g. `packages/foo/CLAUDE.md` reaches the model uncleaned
- * unless it is scanned here. Skips node_modules.
+ * Every file under `dir` that Claude Code loads as model context: the
+ * subdirectory instruction files (CLAUDE.md, CLAUDE.local.md, AGENTS.md) and the
+ * whitelisted `.claude/` markdown (see {@link CLAUDE_CONTEXT_SUBDIRS}). Claude
+ * Code loads these on entry to their containing directory — a load path that
+ * bypasses the PostToolUse sanitizer — so a payload planted in e.g.
+ * `packages/foo/CLAUDE.md` reaches the model uncleaned unless it is scanned
+ * here. Skips node_modules.
  *
  * `**` does not descend into dot directories, so NESTED `.claude/` trees need
- * their own pattern: the caller scans only the project-root `.claude`, which
- * would leave a directory-scoped skill at `packages/foo/.claude/skills/x/SKILL.md`
- * — model context by the same load path — never scanned.
+ * their own doubled-star-prefixed patterns: without them a directory-scoped skill at
+ * `packages/foo/.claude/skills/x/SKILL.md` — model context by the same load
+ * path — is never scanned. That same rule is why the root `.claude` needs no
+ * separate walk: a leading doubled star matches zero segments, so the nested
+ * patterns cover the root tree too.
  * @param {string} dir
  * @returns {string[]}
  */

package/types/index.d.mts

@@ -37,6 +37,6 @@ export function sanitize(text: string, options?: {
     found: string[];
     warnings: string[];
 }>;
-export { applyLayer1, stripAnsiFully, LONE_SURROGATE_RE } from "./layer1.mjs";
+export { applyLayer1, isBenignAnsi, isBenignAnsiKinds, stripAnsiFully, LONE_SURROGATE_RE } from "./layer1.mjs";
 export { stripInvisible, stripInvisibleWithReport, isSgrOnly, STRIP, SGR_RE, CHECKS, CATEGORY, CATEGORY_LABELS, LINGUISTIC_SCRIPTS, VS, BLANK_NON_CF, LONG_RUN_RE, LONG_RUN_THRESHOLD, SCATTERED_THRESHOLD } from "./invisible.mjs";
 export { HTML_TAG_PRESENT, MD_LINK_HINT, SECRET_HINT, SECRET_HINT_EXT, matchesSecretHint } from "./gates.mjs";

package/types/layer1.d.mts

@@ -11,9 +11,54 @@
  * survives here. Past the bound a reconstituted sequence therefore degrades to
  * VISIBLE text rather than a hidden control, which is the fail-open direction.
  * @param {string} input
+ * @param {Set<string>} [kinds]  see {@link stripAnsiOnce}; accumulates across passes
  * @returns {string}
  */
-export function stripAnsiFully(input: string): string;
+export function stripAnsiFully(input: string, kinds?: Set<string>): string;
+/**
+ * True when the ANSI a Layer-1 strip removed was INERT: every removed sequence
+ * was either a display-only SGR colour token or a LONE 7-bit `ESC` that opened
+ * nothing at all (a stray byte in a file, a truncated write, a log fragment cut
+ * mid-escape).
+ *
+ * The two other orphan kinds are deliberately NOT inert. A raw C1 orphan
+ * (TOKEN_KIND.ORPHAN_C1): legit UTF-8 text does not carry raw C1 bytes, and the
+ * block holds the DCS/SOS/PM/APC string introducers this grammar does not
+ * consume — so an unrecognized one means a terminal would have eaten the
+ * following text as a control payload. An incomplete CSI (TOKEN_KIND.ORPHAN_CSI)
+ * for the same reason at 7 bits: the CSI parser keeps consuming until a final
+ * byte, so `hello ESC[12 world` hides ` w` from the human while the model reads
+ * the whole prompt.
+ *
+ * This draws a severity line, not a presence line: the bytes are stripped
+ * either way, so all that rides on the answer is whether the operator sees a
+ * WARNING or a terse note. An orphan introducer cannot move the cursor, erase
+ * the screen, relabel a window, or open an OSC string — every one of those needs
+ * a COMPLETE token, which {@link scanAnsi} classifies as CSI or OSC and this
+ * rejects. Warning on a lone `ESC` is the false positive that costs the most: one
+ * pre-existing `ESC` in a markdown file, echoed back in an Edit result, raises
+ * the same alarm as a cursor-spoofing payload, and an alarm that fires on inert
+ * bytes is the one operators learn to scroll past.
+ *
+ * It takes the kinds the STRIP recorded, never a fresh scan of the raw text,
+ * and that is the whole point: a scan of the raw text answers about sequences
+ * that have not been reconstituted yet, so `ESC` + `ESC[m` + `[2J` (a bare ESC,
+ * an SGR, then plain text) reads as orphan-only there while the strip's second
+ * pass actually removes a CSI erase. Recording what each pass removed reports
+ * the sequences that really existed at Layer 1's fixed point.
+ * @param {readonly string[] | Set<string>} kinds  {@link TOKEN_KIND} values removed
+ * @returns {boolean}
+ */
+export function isBenignAnsiKinds(kinds: readonly string[] | Set<string>): boolean;
+/**
+ * {@link isBenignAnsiKinds} for callers that hold only the text — it runs the
+ * full Layer-1 composition to get the fixed-point view. Callers that already
+ * ran {@link applyLayer1} must read its `ansiKinds` instead of paying for a
+ * second strip.
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function isBenignAnsi(text: string): boolean;
 /**
  * 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
@@ -38,12 +83,19 @@ export function stripAnsiFully(input: string): string;
  *
  * `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.
+ *
+ * `ansiKinds` is the {@link TOKEN_KIND} of every ANSI sequence the composition
+ * removed, deduped — the severity detail `found`'s single ANSI category cannot
+ * carry (see {@link isBenignAnsiKinds}). It is also what DERIVES that category:
+ * a kind is recorded exactly when bytes were removed, so "we reported ANSI" and
+ * "here is what the ANSI was" can no longer disagree.
  * @param {string} text
- * @returns {{ cleaned: string, deAnsi: string, found: string[] }}
+ * @returns {{ cleaned: string, deAnsi: string, found: string[], ansiKinds: string[] }}
  */
 export function applyLayer1(text: string): {
     cleaned: string;
     deAnsi: string;
     found: string[];
+    ansiKinds: string[];
 };
 export const LONE_SURROGATE_RE: RegExp;