agent-sanitizer 2.24.2 → 2.26.0

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

@@ -1,3 +1,17 @@
+/**
+ * Milliseconds as the seconds string every notice below prints.
+ *
+ * Rounds tenths half-UP from an exact integer count of hundredths, rather than
+ * `(ms / 1000).toFixed(1)`: the shell port of this module
+ * (plugin/scripts/lib/hook-timing.sh) has to produce the byte-identical string
+ * with integer arithmetic, and `toFixed` rounds the underlying double — so 1150
+ * would print "1.1" here (1.15 is below its decimal value as a double) and "1.2"
+ * there. `ms / 100` lands exactly on a half only when `ms` ends in 50, and every
+ * such quotient is dyadic, so this rounding is exact for every input.
+ * @param {number} ms
+ * @returns {string}
+ */
+export function formatSeconds(ms: number): string;
 /**
  * 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
@@ -37,6 +51,43 @@ export function startHookTimer(now?: () => number): () => number;
  * @returns {string | null}
  */
 export function slowHookNotice(hookName: string, elapsedMs: number, thresholdMs?: number): string | null;
+/**
+ * The line for a ONE-TIME provisioning step that overran
+ * {@link SLOW_PROVISION_THRESHOLD_MS}, or null when it did not.
+ *
+ * Deliberately NOT {@link slowHookNotice} with a bigger threshold: that message
+ * says "every affected call pays it", which is false here and would send the
+ * reader hunting a per-call cost that does not exist. What is actionable about a
+ * slow install is the installer (uv resolves in a fraction of pip's time) and
+ * the fact that a repeat means the idempotence check is broken — so this asks
+ * for a report only on the repeat, which is the version of this that is a bug.
+ *
+ * The one caller is the shell provisioner, whose port of this module
+ * (plugin/scripts/lib/hook-timing.sh) must emit this exact string; that port and
+ * this definition are pinned to each other by a contract test rather than left
+ * as two independently-worded copies.
+ * @param {string} stepName
+ * @param {number} elapsedMs
+ * @param {number} [thresholdMs]
+ * @returns {string | null}
+ */
+export function slowProvisionNotice(stepName: string, elapsedMs: number, thresholdMs?: number): string | null;
+/**
+ * Write the slow-hook notice to stderr and return it, or return null when the
+ * run was within budget (writing nothing, so the quiet path stays quiet).
+ *
+ * The one place the notice reaches stderr: every reporter below needs the
+ * transcript copy, and a hook whose run ENDED IN AN ERROR has nothing but this —
+ * its verdict is the fail-closed one its `onError` composed, and diluting that
+ * message with a performance aside would bury the fault. A judge that spent
+ * thirty seconds and then threw is exactly the case the timing exists to name,
+ * so the error path measures and reports; it just reports on the human channel.
+ * @param {string} hookName
+ * @param {number} elapsedMs
+ * @param {(chunk: string) => void} [writeErr]  injectable stderr sink, for tests
+ * @returns {string | null}
+ */
+export function writeSlowHookNotice(hookName: string, elapsedMs: number, writeErr?: (chunk: string) => void): 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
@@ -104,3 +155,16 @@ export function reportSlowHook(hookName: string, elapsedMs: number, hookEventNam
  * means something is actually wrong, not that the machine is busy.
  */
 export const SLOW_HOOK_THRESHOLD_MS: 1000;
+/**
+ * Wall-clock a ONE-TIME provisioning step may spend before it is reported.
+ *
+ * Two orders of magnitude above {@link SLOW_HOOK_THRESHOLD_MS}, because it
+ * measures something categorically different: a dependency install that a
+ * session pays once, not a cost every tool call repeats. A cold `uv` install of
+ * the redactor engine is seconds and a cold `pip` one can be tens of them, so a
+ * budget anywhere near a second would report every first session — the alert
+ * fatigue this whole module exists to avoid. Past a minute, something is
+ * actually wrong (a serial pip resolve, a wedged mirror, or an idempotence bug
+ * re-provisioning every session), which is worth saying out loud.
+ */
+export const SLOW_PROVISION_THRESHOLD_MS: 60000;

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

@@ -56,13 +56,14 @@
  * @param {{remainingMs: () => number}} [deadline] shared wall-clock budget across
  *   all leaves of one hook run; a direct caller gets a fresh full budget
  * @param {SanitizeExtensions} [ext]
- * @returns {Promise<{ cleaned: string, warnings: string[], modified: boolean, sgrNote: boolean, reveal?: string }>}
+ * @returns {Promise<{ cleaned: string, warnings: string[], notes: string[], modified: boolean, sgrNote: boolean, reveal?: string }>}
  */
 export function sanitizeText(text: string, toolName: string, deadline?: {
     remainingMs: () => number;
 }, ext?: SanitizeExtensions): Promise<{
     cleaned: string;
     warnings: string[];
+    notes: string[];
     modified: boolean;
     sgrNote: boolean;
     reveal?: string;
@@ -77,10 +78,10 @@ export function sanitizeText(text: string, toolName: string, deadline?: {
  * too (a connector can hide a secret in a field name); non-string leaves
  * (booleans, numbers, null) pass through untouched, and `warnings` accumulates
  * across leaves.
- * `sgrNote` is the OR across leaves: true when some leaf was an SGR-only strip.
+ * `sgrNote` is the OR across leaves: true when some leaf came back note-only.
  * `reveals` accumulates each leaf's pre-Layer-2 text (when the HTML splice
- * removed something) for the orchestrator to persist — same mutated-accumulator
- * shape as `warnings`.
+ * removed something) for the orchestrator to persist, and `notes` the leaves'
+ * NOTE-severity findings — same mutated-accumulator shape as `warnings`.
  * @param {any} value
  * @param {string} toolName
  * @param {string[]} warnings
@@ -88,11 +89,13 @@ export function sanitizeText(text: string, toolName: string, deadline?: {
  * @param {{remainingMs: () => number}} [deadline] shared wall-clock budget across
  *   every leaf of this value (created once by the top-level caller)
  * @param {SanitizeExtensions} [ext]
+ * @param {string[]} [notes]  appended last so an existing caller's positional
+ *   arguments keep their meaning
  * @returns {Promise<{ value: any, modified: boolean, sgrNote: boolean }>}
  */
 export function sanitizeValue(value: any, toolName: string, warnings: string[], reveals?: string[], deadline?: {
     remainingMs: () => number;
-}, ext?: SanitizeExtensions): Promise<{
+}, ext?: SanitizeExtensions, notes?: string[]): Promise<{
     value: any;
     modified: boolean;
     sgrNote: boolean;

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

@@ -71,24 +71,6 @@ 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 }>}
@@ -99,6 +81,8 @@ export function scanFile(filePath: string): Array<{
     method: string;
     decoded: string;
 }>;
+import { CLAUDE_CONTEXT_SUBDIRS } from "../src/claude-context.mjs";
+import { CLAUDE_INSTRUCTION_GLOBS } from "../src/claude-context.mjs";
 /**
  * @param {string} run
  * @returns {{ method: string, decoded: string }}
@@ -109,19 +93,17 @@ export function decodeRun(run: string): {
 };
 /**
  * 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.
+ * per-directory instruction files (CLAUDE.md, CLAUDE.local.md, AGENTS.md) and
+ * the whitelisted `.claude/` markdown. 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.
  *
- * `**` does not descend into dot directories, so NESTED `.claude/` trees need
- * 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.
+ * The scope itself — which globs, and which directories the walk must prune —
+ * is the library's {@link CLAUDE_INSTRUCTION_GLOBS} /
+ * {@link excludeFromContextScan}, so this hook and every other consumer read one
+ * list (see src/claude-context.mjs for why it is imported relatively rather than
+ * through the `agent-sanitizer` specifier the plugin bundle pins).
  * @param {string} dir
  * @returns {string[]}
  */
@@ -147,4 +129,4 @@ export function formatReport(allFindings: Array<{
         decoded: string;
     }>;
 }>): string;
-export { ALERT_FILE, ALERT_ACK_FILE };
+export { CLAUDE_CONTEXT_SUBDIRS, CLAUDE_INSTRUCTION_GLOBS, ALERT_FILE, ALERT_ACK_FILE };

package/types/html.d.mts

@@ -93,11 +93,17 @@ export function urlHost(url: string): string;
  * and HTML attributes (src/href/background/srcset/ping, form action/formaction,
  * meta-refresh). Detection only — the text is never modified; the caller
  * surfaces the threats as a warning.
+ *
+ * `autoFetched` marks a threat that needs no deliberate act to fire — a
+ * rendered image, a stylesheet, a form target, a meta refresh — as opposed to a
+ * link somebody has to follow. Both are reported; the caller uses it to decide
+ * how loudly (see the exfil tier in ./output.mjs).
  * @param {string} text
- * @returns {Array<{ isImage: boolean, reason: string, target: string }> | null}
+ * @returns {Array<{ isImage: boolean, autoFetched: boolean, reason: string, target: string }> | null}
  */
 export function detectExfil(text: string): Array<{
     isImage: boolean;
+    autoFetched: boolean;
     reason: string;
     target: string;
 }> | null;

package/types/index.d.mts

@@ -10,7 +10,8 @@
  * its own removal.
  *
  * `found` names the categories neutralized; `warnings` carries the
- * operator-facing notices. `cleaned` is always a string, and a change only
+ * operator-facing notices and `notes` the quiet tier (see `./severity.mjs`).
+ * `cleaned` is always a string, and a change only
  * ever carries a warning (no silent suppression). `options` is optional and
  * tolerates an explicit `null`/`undefined` (treated the same as omitted) —
  * only a genuinely malformed `text` (not a string) throws, deliberately: a
@@ -20,7 +21,7 @@
  *
  * The layer bodies live in `./output.mjs`; this is a facade over them, not a
  * second implementation (see the module doc). It narrows `sanitizeText`'s result
- * to the three fields this entry has always promised — `modified`/`sgrNote`
+ * to the four fields this entry promises — `modified`/`sgrNote`
  * describe the tool-output pipeline's banner, and `reveal` is produced only by
  * options this facade does not expose. `html` selects Layers 2 AND 3 together
  * here, which is the surface this entry has always had; `sanitizeText` takes
@@ -28,7 +29,7 @@
  * detection without Layer 2's splice.
  * @param {string} text
  * @param {{ html?: boolean } | null} [options]
- * @returns {Promise<{ cleaned: string, found: string[], warnings: string[] }>}
+ * @returns {Promise<{ cleaned: string, found: string[], warnings: string[], notes: string[] }>}
  */
 export function sanitize(text: string, options?: {
     html?: boolean;
@@ -36,6 +37,7 @@ export function sanitize(text: string, options?: {
     cleaned: string;
     found: string[];
     warnings: string[];
+    notes: string[];
 }>;
 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";

package/types/instructions.d.mts

@@ -40,23 +40,32 @@ export function scanText(content: string): Array<{
  * cannot be resolved (a dangling symlink or unreadable entry inside the
  * tree), is SKIPPED, so one bad symlink never aborts scanning the rest of the
  * project.
+ *
+ * `exclude` prunes the WALK, which is where a wide glob's cost actually is —
+ * a pattern that merely fails to match a bulk directory still pays to read it.
+ * It is composed with, never replaces, the unconditional `node_modules` prune:
+ * a caller narrowing the scan must not be able to widen it into a dependency
+ * tree. Pass {@link excludeFromContextScan} to take Claude Code's own scope.
  * @param {string[]} globs
- * @param {{ cwd?: string }} [options]
+ * @param {{ cwd?: string, exclude?: (entry: string) => boolean }} [options]
  * @returns {string[]}
  */
-export function findInstructionFiles(globs: string[], { cwd }?: {
+export function findInstructionFiles(globs: string[], { cwd, exclude }?: {
     cwd?: string;
+    exclude?: (entry: string) => boolean;
 }): string[];
 /**
  * Scan every instruction file matched by `globs` and return only those with
  * findings, each path reported relative to `cwd`. Unreadable/missing files are
  * skipped. Pure scan — no mutation; pair with {@link cleanFile} to strip.
  * @param {string[]} globs
- * @param {{ cwd?: string }} [options]
+ * @param {{ cwd?: string, exclude?: (entry: string) => boolean }} [options]
+ *   `exclude` is forwarded to {@link findInstructionFiles}
  * @returns {Array<{ file: string, findings: ReturnType<typeof scanText> }>}
  */
-export function scanInstructionFiles(globs: string[], { cwd }?: {
+export function scanInstructionFiles(globs: string[], { cwd, exclude }?: {
     cwd?: string;
+    exclude?: (entry: string) => boolean;
 }): Array<{
     file: string;
     findings: ReturnType<typeof scanText>;
@@ -135,3 +144,4 @@ export function atomicReplaceFile(absPath: string, data: string, mode: number, t
  * @returns {boolean}
  */
 export function cleanFile(absPath: string, lstat?: (path: string) => import("node:fs").Stats): boolean;
+export { CLAUDE_CONTEXT_SUBDIRS, CLAUDE_INSTRUCTION_GLOBS, excludeFromContextScan } from "./claude-context.mjs";

package/types/invisible.d.mts

@@ -46,6 +46,72 @@ export function countPayloadInvisible(text: string): number;
  * @returns {string}
  */
 export function payloadInvisibleView(text: string): string;
+/**
+ * The first payload-invisible LONG RUN in `text`, or null when there is none.
+ *
+ * THE definition of "this text carries a hidden run", shared by every consumer
+ * that has an opinion about one: the strip's `[LONG RUN — possible injection
+ * payload]` marker, the prompt gate's block decision, and the tool-output
+ * severity tier. They used to spell it twice, and differently — the marker
+ * probed the PAYLOAD view while the prompt gate probed the raw text, so a
+ * legitimate ten-emoji flag sequence (carve-out-preserved, never stripped) was
+ * quietly enough to BLOCK a prompt while the strip that saw the same text
+ * declined to even flag it. Masking the preserved invisibles is the right half
+ * of that disagreement: a run the carve-out keeps is rendering work, not a
+ * channel, and the joiners it does NOT keep are counted as payload anyway (see
+ * {@link countEffectiveInvisible}).
+ *
+ * Because the view replaces only PRESERVED invisibles (and visible characters)
+ * with spaces, a match consists solely of payload code points and is therefore
+ * byte-identical to the corresponding span of `text` — so a caller may report
+ * the sample verbatim.
+ * @param {string} text
+ * @returns {string | null}
+ */
+export function payloadLongRunSample(text: string): string | null;
+/**
+ * How many invisible code points in `text` the strip layer treats as PAYLOAD:
+ * the ones {@link countPayloadInvisible} counts, plus the joiners that sit in a
+ * genuine linguistic context but exceed the carve-out's preservation budget.
+ *
+ * The surplus term closes the preserved-joiner covert channel (O3):
+ * `countPayloadInvisible` excludes every ZWNJ/ZWJ doing real rendering work, so
+ * an attacker who alternates `letter joiner letter joiner …` — every joiner
+ * legitimately between two cursive letters — counts as ZERO there. The strip
+ * layer already refuses that (it preserves joiners only up to
+ * TOTAL_PRESERVED_JOINER_BUDGET / CONSECUTIVE_JOINER_CAP and strips the rest),
+ * so the surplus is read back OFF the strip — the SSOT — rather than by
+ * re-deriving the budget here, which is what would drift.
+ *
+ * A leading BOM is preserved by the strip but counted by
+ * {@link countPayloadInvisible}, so the difference can go slightly negative;
+ * hence the clamp.
+ * @param {string} text  ANSI-stripped text (an escape sequence can hide invisibles)
+ * @returns {number}
+ */
+export function countEffectiveInvisible(text: string): number;
+/**
+ * True when the invisible characters in `text` are INCIDENTAL: no hidden run,
+ * and too few of them in total to carry an instruction.
+ *
+ * This is a severity line, not a strip line — the bytes are removed either way
+ * (see ../src/severity.mjs). It exists because a single soft hyphen in a
+ * pasted paragraph, or one variation selector a font demanded, raised the exact
+ * `WARNING: Tool output sanitized` an encoded payload does, and a warning that
+ * fires on a stray character in ordinary prose is one operators learn to skip.
+ *
+ * The bar is {@link LONG_RUN_THRESHOLD} — the count this module already calls
+ * "payload length" — applied to the WHOLE text rather than to one run, so it is
+ * strictly stronger than the run probe: fewer than ten payload-invisible code
+ * points, however they are distributed, cannot spell a smuggled instruction (ten
+ * tag characters are ten ASCII letters). Deliberately NOT the far looser
+ * {@link SCATTERED_THRESHOLD} of 30, which is the prompt gate's BLOCK bar: 29
+ * tag characters is a short sentence, and staying quiet about a short sentence
+ * hidden in a tool result is not a trade worth making.
+ * @param {string} text  ANSI-stripped text, invisible runs intact
+ * @returns {boolean}
+ */
+export function isIncidentalInvisible(text: string): boolean;
 /**
  * Strip payload-capable invisible chars and report which categories were
  * removed. A single leading U+FEFF (BOM) is preserved as a legitimate marker;

package/types/layer1.d.mts

@@ -99,3 +99,15 @@ export function applyLayer1(text: string): {
     ansiKinds: string[];
 };
 export const LONE_SURROGATE_RE: RegExp;
+/**
+ * What a reader is told when the ONLY thing a strip removed was inert ANSI (see
+ * {@link isBenignAnsiKinds}).
+ *
+ * It lives here, beside the predicate that decides it, because every entry point
+ * that can reach that verdict must say the same thing: the tool-output pipeline,
+ * the prompt gate's pass-with-note, and any host wiring its own. The wording is
+ * deliberately not `describeStripped`'s — "Stripped: ANSI escapes" names a
+ * category that reads like an attack, when the honest report is "these were
+ * colour codes, and here is how to look at the raw bytes".
+ */
+export const INERT_ANSI_NOTE: string;

package/types/output.d.mts

@@ -50,18 +50,26 @@ export function deleteVerbatimSpans(text: string, spans: string[]): {
  * post-mutation invariants and forget the rest, and every string in the returned
  * object has traversed Layer 4.
  *
- * `found` is the machine-readable twin of `warnings` — the {@link CATEGORY}
- * codes for what Layers 1-3 neutralized or flagged, in the order the layers ran.
- * Layers 4 and 5 have no category codes (their findings are the injected seam's
- * own vocabulary), so they contribute warnings only.
+ * Findings come back SPLIT BY SEVERITY (see ./severity.mjs): `warnings` holds
+ * everything injection-shaped — the banner a caller must show — and `notes`
+ * holds what happened but is not alarming. `warnings` therefore keeps exactly
+ * the meaning it always had, and a caller that ignores `notes` is no louder
+ * than before, just quieter about incidental bytes.
+ *
+ * `found` is the machine-readable twin, and the severity split does NOT reach
+ * it — the {@link CATEGORY} codes for what Layers 1-3 neutralized or flagged,
+ * in the order the layers ran, whichever tier described them. Layers 4 and 5
+ * have no category codes (their findings are the injected seam's own
+ * vocabulary), so they contribute findings only.
  * @param {string} text
  * @param {SanitizeTextOptions} [options]
- * @returns {Promise<{ cleaned: string, found: string[], warnings: string[], modified: boolean, sgrNote: boolean, reveal?: string }>}
+ * @returns {Promise<{ cleaned: string, found: string[], warnings: string[], notes: string[], modified: boolean, sgrNote: boolean, reveal?: string }>}
  */
 export function sanitizeText(text: string, options?: SanitizeTextOptions): Promise<{
     cleaned: string;
     found: string[];
     warnings: string[];
+    notes: string[];
     modified: boolean;
     sgrNote: boolean;
     reveal?: string;
@@ -82,8 +90,10 @@ export function isWalkableContainer(value: any): boolean;
 /**
  * Sanitize every string leaf of a tool-output value, preserving its shape (a
  * structured tool output whose shape changes would be ignored by a harness,
- * leaking the raw value). Non-string leaves pass through; `warnings`
- * accumulates across leaves. `sgrNote` is the OR across leaves.
+ * leaking the raw value). Non-string leaves pass through; `warnings` and
+ * `notes` accumulate across leaves, split by severity (see ./severity.mjs).
+ * `sgrNote` is the OR across leaves — true when SOME leaf was note-only — so a
+ * caller can still pick the quiet banner when no leaf raised a warning.
  *
  * Fails CLOSED on two hostile shapes that would otherwise throw a `RangeError`
  * as an unhandled async rejection (a DoS that leaves the output un-sanitized):
@@ -99,9 +109,12 @@ export function isWalkableContainer(value: any): boolean;
  * @param {SanitizeTextOptions} options
  * @param {string[]} warnings
  * @param {string[]} [reveals]
+ * @param {string[]} [notes]  the NOTE-severity counterpart of `warnings`;
+ *   appended last so an existing positional caller keeps working (it simply
+ *   discards the notes, which is exactly as loud as before the split)
  * @returns {Promise<{ value: any, modified: boolean, sgrNote: boolean }>}
  */
-export function sanitizeValue(value: any, options: SanitizeTextOptions, warnings: string[], reveals?: string[]): Promise<{
+export function sanitizeValue(value: any, options: SanitizeTextOptions, warnings: string[], reveals?: string[], notes?: string[]): Promise<{
     value: any;
     modified: boolean;
     sgrNote: boolean;
@@ -199,16 +212,18 @@ export type Layer5Result = {
 };
 /**
  * The running state of one {@link sanitizeText} call. Layers read `text` and
- * mutate it ONLY through {@link applyMutation}. `found` is the machine-readable
- * twin of `warnings`: the {@link CATEGORY} codes for whatever Layers 1-3
- * neutralized or flagged.
+ * mutate it ONLY through {@link applyMutation}. Findings carry their own
+ * severity (see ./severity.mjs) and are split into `warnings`/`notes` at the
+ * single exit, so no layer can push into the wrong list. `found` is the
+ * machine-readable twin, unaffected by the split: the {@link CATEGORY} codes
+ * for whatever Layers 1-3 neutralized or flagged.
  */
 export type PipelineState = {
     text: string;
     found: string[];
-    warnings: string[];
+    findings: import("./severity.mjs").Finding[];
     modified: boolean;
-    sgrNote: boolean;
+    unreportedChange: boolean;
 };
 export type SanitizeTextOptions = {
     html?: boolean;
@@ -218,4 +233,4 @@ export type SanitizeTextOptions = {
     sgrCarveOut?: boolean;
 };
 import { needsMarkdownPipeline } from "./gates.mjs";
-export { describeRemoved, describeWarned } from "./warnings.mjs";
+export { describeExfil, describeRemoved, describeWarned } from "./warnings.mjs";

package/types/severity.d.mts

@@ -0,0 +1,83 @@
+/**
+ * @typedef {{ severity: string, message: string }} Finding
+ *   A single reportable outcome and how loudly to report it.
+ */
+/**
+ * A WARNING-severity finding: injection-shaped, worth the banner.
+ * @param {string} message
+ * @returns {Finding}
+ */
+export function warning(message: string): Finding;
+/**
+ * A NOTE-severity finding: reported, not alarming.
+ * @param {string} message
+ * @returns {Finding}
+ */
+export function note(message: string): Finding;
+/**
+ * A finding at `severity` — the constructor for a caller that has already
+ * computed the tier as a boolean and would otherwise write the ternary itself.
+ * @param {boolean} isWarning
+ * @param {string} message
+ * @returns {Finding}
+ */
+export function finding(isWarning: boolean, message: string): Finding;
+/**
+ * The messages of every WARNING-severity finding, in order.
+ * @param {readonly Finding[]} findings
+ * @returns {string[]}
+ */
+export function warningMessages(findings: readonly Finding[]): string[];
+/**
+ * The messages of every NOTE-severity finding, in order.
+ * @param {readonly Finding[]} findings
+ * @returns {string[]}
+ */
+export function noteMessages(findings: readonly Finding[]): string[];
+/**
+ * The one place a finding's LOUDNESS is decided, and the vocabulary every layer
+ * reports in.
+ *
+ * Every layer of this pipeline used to have exactly one volume. A cursor-spoofing
+ * ANSI payload and a single stray escape byte in a README produced the same
+ * `WARNING: Tool output sanitized` banner; so did one soft hyphen, and so did
+ * the `<script>` tag that every fetched web page carries. That is the failure
+ * mode a detector dies of: a banner that fires on every ordinary page teaches its
+ * reader to skip the banner, and then the one that mattered scrolls past too.
+ *
+ * So a finding carries a SEVERITY, and the two tiers mean specific things:
+ *
+ *   WARNING — this text is injection-shaped. Something was hidden from a human
+ *             reader, something was removed that a payload would have used, or a
+ *             secret was redacted. Worth interrupting the reader for.
+ *   NOTE    — this happened, and here is how to look at it, but nothing about it
+ *             is attack-shaped. Incidental bytes, or content that was PRESERVED
+ *             and merely described.
+ *
+ * The tier never changes what the pipeline DOES: the same bytes are stripped,
+ * spliced and redacted either way, and a note is still reported. All that rides
+ * on it is which banner the operator sees, which is why a note is the right
+ * answer whenever the evidence is thin — an under-loud true finding is still
+ * delivered, while an over-loud false one costs the channel its credibility.
+ *
+ * Mechanism only, deliberately: WHICH findings qualify is each layer's own
+ * judgement, made where that layer's evidence lives (see isBenignAnsiKinds in
+ * ./layer1.mjs, isIncidentalInvisible in ./invisible.mjs, and the exfil/HTML
+ * tiers in ./output.mjs and ./index.mjs). This module owns the enum, the constructors and the
+ * queries so nobody spells `severity === "warning"` by hand.
+ */
+/**
+ * The closed severity vocabulary. Stable, machine-readable values: branch on
+ * these, not on the prose.
+ */
+export const SEVERITY: Readonly<{
+    NOTE: "note";
+    WARNING: "warning";
+}>;
+/**
+ * A single reportable outcome and how loudly to report it.
+ */
+export type Finding = {
+    severity: string;
+    message: string;
+};

package/types/src/claude-context.d.mts

@@ -0,0 +1,88 @@
+/**
+ * The one directory no instruction-file walk ever descends into. Its own
+ * function so the name is spelled once, and so the two predicates that need it
+ * (a plain glob walk, and {@link excludeFromContextScan}) cannot disagree.
+ * @param {string} entry  a bare entry name or a path relative to the scan root
+ * @returns {boolean}
+ */
+export function excludeNodeModules(entry: string): boolean;
+/**
+ * Entries a context scan must not descend into or return: `node_modules`, and
+ * every child of a `.claude` directory that is not whitelisted context.
+ *
+ * The globs alone would already refuse to MATCH those files, but a glob walker
+ * calls this on directories as it walks and prunes the ones it rejects — which
+ * is where the cost actually is. Without the prune, a `.claude/worktrees/`
+ * holding a few repo checkouts is walked in full on every session start (and,
+ * because a doubled-star segment does cross into a dot directory when the
+ * pattern names one, a `.claude` NESTED inside a worktree was matched and
+ * scanned as if it were this session's context).
+ *
+ * A walker calls this with both bare names and root-relative paths, so it must
+ * answer for either; a bare name carries no `.claude` context and is judged only
+ * against `node_modules`.
+ * @param {string} entry  a bare entry name or a path relative to the scan root
+ * @returns {boolean}
+ */
+export function excludeFromContextScan(entry: string): boolean;
+/**
+ * WHICH files an agent loads as model context, as data: the glob set and the
+ * walk-pruning predicate that together define "everything Claude Code reads as
+ * instructions, and nothing else".
+ *
+ * This is the SINGLE SOURCE for that scope. It used to live inside
+ * `claude-hooks/scan-invisible-chars.mjs`, which meant the SessionStart hook
+ * knew the answer and nobody else did: `src/instructions.mjs` takes
+ * caller-supplied globs by design (no agent's convention is baked into the
+ * engine), so the CLI, the Python port and every downstream fork spelled their
+ * own approximation of this list — and an approximation that drifts either
+ * scans bulk data that can never reach the model (the 30-second session start
+ * this whitelist exists to fix) or MISSES a context directory entirely, which
+ * is a silent hole in the one scan standing between a poisoned instruction file
+ * and a session that loads it.
+ *
+ * It is a standalone, dependency-free DATA module (like ./cf-charset.mjs) for
+ * two reasons: `src/instructions.mjs` re-exports it as the library's public
+ * door, and the hook imports it RELATIVELY — deliberately not through the
+ * `agent-sanitizer` specifier the plugin bundle pins to a published engine.
+ * This scope is hook POLICY, not engine behavior: it must ship and move with the
+ * hook that walks it, or a plugin built against an older pin would prune the
+ * wrong directories while believing it had scanned everything.
+ */
+/**
+ * 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 nobody 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[];
+/**
+ * Every glob whose matches Claude Code loads as model context: the
+ * per-directory instruction files (CLAUDE.md, CLAUDE.local.md, AGENTS.md) and
+ * the whitelisted `.claude/` markdown. 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 something scans it here.
+ *
+ * `**` does not descend into dot directories, so NESTED `.claude/` trees need
+ * 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 matched. That same rule is why the root `.claude` needs
+ * no separate entry: a leading doubled star matches zero segments, so the
+ * nested patterns cover the root tree too.
+ *
+ * Pair with {@link excludeFromContextScan}: the patterns alone already refuse to
+ * MATCH a bulk directory, but only pruning the WALK avoids paying to read it.
+ */
+export const CLAUDE_INSTRUCTION_GLOBS: readonly string[];