agent-sanitizer 2.23.1 → 2.24.0

package/types/ansi.d.mts

@@ -1,8 +1,32 @@
+/**
+ * True for either orphan kind — the tokens {@link scanAnsi} emits for an
+ * introducer that completes no sequence, which the stripper must leave in place
+ * for the residual sweep rather than splice (see stripAnsiOnce).
+ * @param {string} kind one of {@link TOKEN_KIND}
+ * @returns {boolean}
+ */
+export function isOrphanKind(kind: string): boolean;
+/**
+ * The orphan kind for the introducer character `ch`, given the character `next`
+ * that follows it: a raw C1 byte, an `ESC` that opened an incomplete CSI, or a
+ * lone `ESC`. The one place that split is decided, shared by the tokenizer and
+ * by Layer 1's residual sweep (which sees bare characters, not tokens).
+ *
+ * `[` is the only lookahead that matters. `ESC ]` is an OSC, which the scanner
+ * consumes to the end of input if unterminated (so it never reaches here), and
+ * every other second byte — `ESC (`, `ESC #`, `ESC P` — bounds what a terminal
+ * swallows to a byte or two rather than running until a final byte arrives.
+ * @param {string} ch
+ * @param {string} [next]  the following character, or undefined at end of input
+ * @returns {string}
+ */
+export function orphanKindFor(ch: string, next?: string): string;
 /**
  * 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
+ * Every introducer yields exactly one token — an orphan kind (see
+ * {@link orphanKindFor}) 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.
@@ -39,7 +63,7 @@ export const CONTROL_INTRODUCER_SOURCE: "[\\u001b\\u0080-\\u009f]";
  * and the regex can no longer describe different languages.
  */
 export const SGR_RE: RegExp;
-/** The four things an introducer can turn out to be. */
+/** The six 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";
@@ -47,8 +71,34 @@ export const TOKEN_KIND: Readonly<{
     CSI: "csi";
     /** An OSC string: introducer, body and terminator as one unit. */
     OSC: "osc";
-    /** An introducer that starts no sequence the grammar recognizes. */
+    /**
+     * A 7-bit `ESC` that starts no sequence the grammar recognizes — a truncated
+     * write, a log fragment cut mid-escape, a stray byte living in a file.
+     */
     ORPHAN: "orphan-introducer";
+    /**
+     * A 7-bit `ESC` that OPENS a CSI (`ESC [`) it never completes. Split from
+     * {@link TOKEN_KIND.ORPHAN} because a terminal's CSI parser is STATEFUL: it
+     * keeps consuming what follows as parameters and intermediates until a final
+     * byte (0x40-0x7E) arrives, so `hello ESC[12 world` renders as `hello orld`
+     * — the ` w` is eaten as the sequence's intermediate and final. That is the
+     * model-sees/human-sees divergence the gate exists for, so consumers that
+     * downgrade an inert strip to a note must keep warning on this one; only a
+     * lone `ESC` that opens nothing is inert.
+     */
+    ORPHAN_CSI: "orphan-csi-introducer";
+    /**
+     * A RAW C1 byte (U+0080-U+009F) that starts no sequence the grammar
+     * recognizes. Split from {@link TOKEN_KIND.ORPHAN} because the two carry very
+     * different weight: a lone `ESC` is ordinary debris in terminal output, while
+     * a raw C1 byte is not something legitimate UTF-8 text produces, and the
+     * block includes the string introducers DCS/SOS/PM/APC (U+0090/0098/009E/
+     * 009F) — which this grammar does not consume, so an unrecognized one here
+     * means a terminal WOULD have swallowed the following text as a control
+     * payload. Consumers that downgrade an inert strip to a note (see
+     * `isBenignAnsiKinds` in ./layer1.mjs) must keep warning on this one.
+     */
+    ORPHAN_C1: "orphan-c1-introducer";
 }>;
 export type AnsiToken = {
     /**

package/types/claude-hooks/lib/control-plane.d.mts

@@ -43,7 +43,12 @@ export function nativeStdout(response: {
  * unparsable stdin, missing package, a judge error — is reported on stderr and
  * routed to `onError(err, input)` (`input` undefined when stdin never parsed),
  * where the hook applies its declared fail posture.
- * @param {string} hookName  prefix for the stderr diagnostic
+ *
+ * It is also where every judge hook is TIMED: the verdict picks up a
+ * performance note when the judge overran the hook budget (see
+ * lib/hook-timing.mjs), so no hook has to remember to measure itself.
+ * @param {string} hookName  prefix for the stderr diagnostic, and the hook name
+ *   a slow-run notice reports
  * @param {(event: import("agent-control-plane-core").ToolCallEvent) =>
  *   import("agent-control-plane-core").Verdict |
  *   Promise<import("agent-control-plane-core").Verdict>} judge

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

@@ -0,0 +1,106 @@
+/**
+ * Run `work`, charging its whole duration to provisioning so no timer running
+ * across it counts that time. Charged in a `finally`, so a provisioning step
+ * that FAILS is still excluded — the wait happened either way, and a hook that
+ * then fails is reported through its fault posture, not as "slow".
+ *
+ * Wrap only genuinely one-time, per-session setup: waiting out a dependency
+ * install, waiting for a cold redactor daemon to bind. Never wrap the hook's
+ * actual work — that is exactly what this measurement is for.
+ * @template T
+ * @param {() => Promise<T>} work
+ * @param {() => number} [now]  injectable clock, for tests
+ * @returns {Promise<T>}
+ */
+export function excludeProvisioning<T>(work: () => Promise<T>, now?: () => number): Promise<T>;
+/**
+ * Start measuring; the returned function reports the milliseconds elapsed so
+ * far MINUS any provisioning charged in the meantime, and may be called more
+ * than once.
+ *
+ * Only provisioning charged since this timer started is subtracted, so an
+ * earlier run's cold start cannot pay down a later run's real cost. A
+ * provisioning window that straddles the timer's start would otherwise be able
+ * to subtract more than the timer has measured, so the result is floored at 0.
+ * @param {() => number} [now]  injectable clock, for tests
+ * @returns {() => number}
+ */
+export function startHookTimer(now?: () => number): () => number;
+/**
+ * The model-facing line for a hook that overran the budget, or null when it did
+ * not. Addressed to the model because the model is the only party that reliably
+ * reads this channel — stderr from a non-blocking hook is easy to miss — and it
+ * is asked to relay the number, since the operator is the one who can file it.
+ * @param {string} hookName
+ * @param {number} elapsedMs
+ * @param {number} [thresholdMs]
+ * @returns {string | null}
+ */
+export function slowHookNotice(hookName: string, elapsedMs: number, thresholdMs?: number): string | null;
+/**
+ * `verdict` with the slow-hook notice folded into its `additional_context`, or
+ * the verdict untouched when the run was within budget. Also writes the notice
+ * to stderr, so the timing survives in the transcript even for a hook whose
+ * verdict carries no context channel to the model.
+ *
+ * Appended, never substituted: the context slot is how a hook reports a REDACTED
+ * secret or a stripped payload, and a timing note must not displace that.
+ * @template {{ additional_context?: string }} V
+ * @param {string} hookName
+ * @param {number} elapsedMs
+ * @param {V} verdict
+ * @param {(chunk: string) => void} [writeErr]  injectable stderr sink, for tests
+ * @returns {V}
+ */
+export function withSlowHookNotice<V extends {
+    additional_context?: string;
+}>(hookName: string, elapsedMs: number, verdict: V, writeErr?: (chunk: string) => void): V;
+/**
+ * Report a slow run for a hook that answers with a bare `hookSpecificOutput`
+ * envelope rather than a control-plane verdict — SessionStart, which has no
+ * verdict channel at all. A within-budget run emits nothing, so the quiet path
+ * stays quiet (and the hook's silent-success contract is unchanged).
+ * @param {string} hookName
+ * @param {number} elapsedMs
+ * @param {string} hookEventName
+ * @param {(event: string, fields: Record<string, unknown>) => void} emit  the
+ *   stdout envelope writer (hook-io's emitHookResponse); passed in rather than
+ *   imported so this module stays dependency-free — see the module doc
+ * @param {(chunk: string) => void} [writeErr]  injectable stderr sink, for tests
+ * @returns {boolean}  whether a notice was emitted
+ */
+export function reportSlowHook(hookName: string, elapsedMs: number, hookEventName: string, emit: (event: string, fields: Record<string, unknown>) => void, writeErr?: (chunk: string) => void): boolean;
+/**
+ * The one place a hook's own wall-clock cost is measured and reported.
+ *
+ * These hooks sit on the critical path of every tool call, every prompt and
+ * every session start: whatever they spend, the user waits. That cost is also
+ * the hardest kind of bug to notice from inside — a hook that got slow looks
+ * exactly like an agent that got slow, so it goes unreported for weeks (one
+ * SessionStart scan blocked startup for 30 SECONDS before anyone traced it back
+ * here). A hook past the budget therefore says so IN BAND, in the model's
+ * context, where it cannot be missed and can be relayed to the operator.
+ *
+ * One threshold, one message, one merge rule, shared by every hook — the
+ * measurement is worthless if each hook words it differently or picks its own
+ * bar for "slow".
+ *
+ * What it deliberately does NOT count is ONE-TIME PROVISIONING (see
+ * {@link excludeProvisioning}). A dependency-install wait or a cold redactor
+ * spawn is wall-clock the user really waits, but it is not a cost this hook
+ * pays per call and it is not a bug worth a report — charging it would make the
+ * FIRST call of every session cry wolf, which is precisely the alert fatigue
+ * this notice exists to avoid.
+ *
+ * Dependency-free on purpose: everything imports this, including hook-io, so a
+ * back-import would close a cycle. The one emitter it needs is passed in.
+ */
+/**
+ * Wall-clock a single hook invocation may spend before it is reported as slow.
+ *
+ * A second is far above anything these hooks do when healthy (Layer 1 is a few
+ * regex passes; the redactor daemon answers in tens of milliseconds once warm)
+ * and far below the point where a human is merely impatient — so crossing it
+ * means something is actually wrong, not that the machine is busy.
+ */
+export const SLOW_HOOK_THRESHOLD_MS: 1000;

package/types/claude-hooks/lib/redactor-client.d.mts

@@ -100,7 +100,7 @@ export function waitForSocket(socketPath: string, { deadlineMs, stepMs }?: {
  * @param {{map?: boolean, webIngress?: boolean, socketPath?: string,
  *   deadline?: {remainingMs: () => number},
  *   connect?: typeof connectAndRequest, spawn?: typeof spawnDaemon,
- *   waitForSocket?: typeof waitForSocket}} [opts]
+ *   waitForSocket?: typeof waitForSocket, now?: () => number}} [opts]
  * @returns {Promise<RedactResponse|null>}
  */
 export function redactViaDaemon(text: string, opts?: {
@@ -113,6 +113,7 @@ export function redactViaDaemon(text: string, opts?: {
     connect?: typeof connectAndRequest;
     spawn?: typeof spawnDaemon;
     waitForSocket?: typeof waitForSocket;
+    now?: () => number;
 }): Promise<RedactResponse | null>;
 export const FRAME_CAP: number;
 export const DEFAULT_SOCKET_PATH: string;

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/invisible.d.mts

@@ -102,5 +102,7 @@ export const CONSECUTIVE_SELECTOR_CAP: 8;
 export const TOTAL_PRESERVED_JOINER_BUDGET: 16;
 export const PRESERVED_JOINER_PER_VISIBLE: 8;
 export const PRESERVE_HARD_CAP: 64;
+export const TOTAL_PRESERVED_BLANK_BUDGET: 16;
+export const PRESERVED_BLANK_PER_ANCHOR: 2;
 export const LINGUISTIC_SCRIPTS: string[];
 export { BRAHMIC_CONSONANT_RANGES } from "./joining-type.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;