agent-sanitizer 2.24.2 → 2.26.0

package/src/output.mjs

@@ -24,10 +24,15 @@
  * actually removes something, so a secret that a deletion reconstitutes is
  * still caught before this function returns.
  */
-import { CATEGORY, describeStripped } from "./invisible.mjs";
+import {
+  CATEGORY,
+  describeStripped,
+  isIncidentalInvisible,
+} from "./invisible.mjs";
 import { needsMarkdownPipeline } from "./gates.mjs";
 import {
   applyLayer1,
+  INERT_ANSI_NOTE,
   isBenignAnsiKinds,
   LONE_SURROGATE_RE,
 } from "./layer1.mjs";
@@ -37,6 +42,13 @@ import {
   describeWarned,
   LONE_SURROGATE_WARNING,
 } from "./warnings.mjs";
+import {
+  finding,
+  note,
+  noteMessages,
+  warning,
+  warningMessages,
+} from "./severity.mjs";
 import { orderedMatches, spliceOrdered } from "./view-map.mjs";
 
 /**
@@ -145,11 +157,13 @@ function normalizeLoneSurrogates(text) {
 }
 
 /**
- * @typedef {{ text: string, found: string[], warnings: string[], modified: boolean, sgrNote: boolean }} PipelineState
+ * @typedef {{ text: string, found: string[], findings: import("./severity.mjs").Finding[], modified: boolean, unreportedChange: boolean }} PipelineState
  *   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.
  */
 
 /**
@@ -166,10 +180,12 @@ function normalizeLoneSurrogates(text) {
  *      configured) makes an invariant of Layer 1 conditional on an unrelated
  *      option.
  *   2. `modified` is set — the caller's "bytes changed" banner.
- *   3. `sgrNote` is cleared. It claims a display-only ANSI-color strip was the
- *      SOLE change, which any later mutation falsifies; a caller that downgrades
- *      the banner on `sgrNote` would otherwise suppress a redaction or splice
- *      warning.
+ *   3. `unreportedChange` is set. A mutation that pushed no finding — a Layer-5
+ *      span deletion whose filter returned no warning code — is a change the
+ *      caller was never told about, and the returned `sgrNote` ("nothing here
+ *      rose above a note") must not invite a quiet banner over one. A mutation
+ *      that DID report itself is covered by its own WARNING, so this flag only
+ *      ever costs a note that would have been misleading.
  *
  * Callers decide WHETHER a mutation happened (each layer already knows: a
  * changed splice output, a redactor finding, a removed span) and call this with
@@ -186,7 +202,7 @@ function normalizeLoneSurrogates(text) {
 function applyMutation(state, nextText) {
   state.text = normalizeLoneSurrogates(nextText);
   state.modified = true;
-  state.sgrNote = false;
+  state.unreportedChange = true;
 }
 
 /**
@@ -224,8 +240,12 @@ async function runRedact(state, redact) {
   }
   if (!secrets) return;
   applyMutation(state, secrets.text);
-  state.warnings.push(
-    `API keys/secrets redacted: ${secrets.found.join(", ")}${secrets.note ?? ""}${REDACTION_DOCTRINE}`,
+  // Always a WARNING: a secret reached this output, and the caller-supplied
+  // `note` (which credential, from where) is the part an operator acts on.
+  state.findings.push(
+    warning(
+      `API keys/secrets redacted: ${secrets.found.join(", ")}${secrets.note ?? ""}${REDACTION_DOCTRINE}`,
+    ),
   );
 }
 
@@ -246,7 +266,7 @@ export const REDACTION_DOCTRINE =
 // (./index.mjs), which runs the same layers; re-exported here because both were
 // part of this module's public surface before they moved.
 export { needsMarkdownPipeline };
-export { describeRemoved, describeWarned } from "./warnings.mjs";
+export { describeExfil, describeRemoved, describeWarned } from "./warnings.mjs";
 
 /**
  * Delete each verbatim span in `spans` from `text`. The secure Layer-5
@@ -285,23 +305,54 @@ export function deleteVerbatimSpans(text, spans) {
   return { text: spliced.text, removed: spliced.spans.length };
 }
 
+/**
+ * The tier for what Layer 1 removed.
+ *
+ * INCIDENTAL means both axes are: the ANSI was display-only (or a stray escape
+ * that opened nothing) AND there were too few invisible characters to spell
+ * anything. Either axis alone keeps the WARNING — a cursor move beside one soft
+ * hyphen is still a cursor move, and ten tag characters beside a colour code are
+ * still ten ASCII letters.
+ *
+ * The whole downgrade is gated on `sgrCarveOut`, the caller asserting local,
+ * first-party output. Without it — a fetched page, an MCP connector — a single
+ * hidden character is not incidental at all; that is the channel where one gets
+ * PUT there.
+ *
+ * When the strip was inert AND nothing but ANSI was found, the note says so in
+ * its own words ({@link INERT_ANSI_NOTE}) rather than reciting a stripped
+ * category, because "we removed some colour codes" is the whole finding.
+ * @param {string[]} invisFound
+ * @param {string[]} ansiKinds
+ * @param {string} deAnsi
+ * @param {boolean} sgrCarveOut
+ * @returns {import("./severity.mjs").Finding}
+ */
+function layer1Finding(invisFound, ansiKinds, deAnsi, sgrCarveOut) {
+  const incidental =
+    sgrCarveOut &&
+    isBenignAnsiKinds(ansiKinds) &&
+    isIncidentalInvisible(deAnsi);
+  const ansiOnly = invisFound.length === 1 && invisFound[0] === CATEGORY.ANSI;
+  if (incidental && ansiOnly) return note(INERT_ANSI_NOTE);
+  return finding(!incidental, describeStripped(invisFound, deAnsi));
+}
+
 /**
  * Layer 1 + surrogate normalisation: invisible chars, ANSI, lone surrogates.
- * `sgrNote` is true when the ONLY change was INERT ANSI — display-only SGR
- * colour and/or a stray orphan introducer that formed no sequence — AND the
- * caller opted into the carve-out (`sgrCarveOut`); the caller reports that with
- * a terse note, not the WARNING prefix.
+ * Findings carry their own tier (see {@link layer1Finding}); a lone-surrogate
+ * normalisation is always loud, since splitting a secret across one is how a
+ * redactor is evaded.
  * @param {string} text
  * @param {boolean} sgrCarveOut
- * @returns {{ cleaned: string, found: string[], warnings: string[], modified: boolean, sgrNote: boolean }}
+ * @returns {{ cleaned: string, found: string[], findings: import("./severity.mjs").Finding[], modified: boolean }}
  */
 function processLayer1(text, sgrCarveOut) {
-  /** @type {string[]} */
-  const warnings = [];
+  /** @type {import("./severity.mjs").Finding[]} */
+  const findings = [];
   /** @type {string[]} */
   const found = [];
   let modified = false;
-  let sgrNote = false;
   const {
     cleaned: layer1,
     deAnsi,
@@ -312,16 +363,7 @@ function processLayer1(text, sgrCarveOut) {
   if (invisFound.length > 0) {
     found.push(...invisFound);
     modified = true;
-    // Inert ANSI with the carve-out enabled: the strip removed cosmetic styling
-    // and/or a stray escape byte, and nothing else (found is exactly [ANSI], so
-    // zero invisible chars were present). Report it as a note — a cursor-move,
-    // erase or OSC token lands in ansiKinds as CSI/OSC and keeps the WARNING.
-    sgrNote =
-      invisFound.length === 1 &&
-      invisFound[0] === CATEGORY.ANSI &&
-      isBenignAnsiKinds(ansiKinds) &&
-      sgrCarveOut;
-    if (!sgrNote) warnings.push(describeStripped(invisFound, deAnsi));
+    findings.push(layer1Finding(invisFound, ansiKinds, deAnsi, sgrCarveOut));
   }
   // Normalize lone UTF-16 surrogates for ALL output: a secret split by an
   // interposed lone surrogate reads as adjacent to a model rendering its own
@@ -332,11 +374,10 @@ function processLayer1(text, sgrCarveOut) {
   if (wellFormed !== cleaned) {
     cleaned = wellFormed;
     modified = true;
-    sgrNote = false;
     found.push(CATEGORY.LONE_SURROGATES);
-    warnings.push(LONE_SURROGATE_WARNING);
+    findings.push(warning(LONE_SURROGATE_WARNING));
   }
-  return { cleaned, found, warnings, modified, sgrNote };
+  return { cleaned, found, findings, modified };
 }
 
 /**
@@ -385,10 +426,18 @@ async function applyMarkdownPipeline(state, { html, exfilScan }) {
         if (layer2.removed.comments > 0)
           state.found.push(CATEGORY.HTML_COMMENTS);
         if (layer2.removed.hidden > 0) state.found.push(CATEGORY.HIDDEN_HTML);
-        state.warnings.push(describeHtmlSanitized(layer2.removed));
+        // A WARNING: these bytes were invisible to a human reading the rendered
+        // page and are now gone from the model's view too — the exact shape of
+        // a hidden-instruction payload, and the model cannot check what it was
+        // without the reveal sidecar.
+        state.findings.push(warning(describeHtmlSanitized(layer2.removed)));
       }
+      // A NOTE: nothing was removed and nothing was hidden. This line says "the
+      // page had scripts, treat their contents as data", which is true of nearly
+      // every page fetched — at WARNING volume it trained the reader to skip the
+      // banner Layer 2's actual splice needs.
       const preserved = describeWarned(layer2.warned);
-      if (preserved) state.warnings.push(preserved);
+      if (preserved) state.findings.push(note(preserved));
     }
   }
   // Layer 3 — detection only: the URLs stay intact, the model is told not to
@@ -397,9 +446,21 @@ async function applyMarkdownPipeline(state, { html, exfilScan }) {
   // suspicious, not less, yet Layer 2 has already removed it from `cleaned`.
   if (exfilScan) {
     const threats = detectExfil(inputText);
+    // Severity tracks who does the fetching. An auto-fetched target — an image,
+    // a stylesheet, a form action, a meta refresh — exfiltrates the moment the
+    // content renders, with nobody deciding anything: a WARNING. A plain LINK
+    // cannot exfiltrate unless the model chooses to follow it, and the sentence
+    // it is reported in is precisely the instruction not to, so it is a NOTE.
+    // One auto-fetched threat raises the whole finding — the loudest member
+    // wins, since they share one line.
     if (threats) {
       state.found.push(CATEGORY.EXFIL_URLS);
-      state.warnings.push(describeExfil(threats));
+      state.findings.push(
+        finding(
+          threats.some((threat) => threat.autoFetched),
+          describeExfil(threats),
+        ),
+      );
     }
   }
   return reveal;
@@ -432,17 +493,22 @@ async function applyMarkdownPipeline(state, { html, exfilScan }) {
  * no-finding paths are already well-formed.
  * @param {string} text
  * @param {SanitizeTextOptions["redact"]} redact
- * @param {string[]} warnings
+ * @param {import("./severity.mjs").Finding[]} findings
  * @param {string} label
  * @returns {Promise<string | undefined>} vetted text, or undefined if withheld
  */
-async function vetStageValue(text, redact, warnings, label) {
+async function vetStageValue(text, redact, findings, label) {
   if (!redact) return text;
   try {
     const secrets = await redact(text);
     return secrets ? normalizeLoneSurrogates(secrets.text) : text;
   } catch {
-    warnings.push(`Withheld the ${label}: it could not be vetted for secrets`);
+    // A WARNING: the caller asked for this field and is not getting it, and the
+    // reason is an unrunnable redactor — the same fault that fails `cleaned`
+    // closed, just with a survivable remedy here.
+    findings.push(
+      warning(`Withheld the ${label}: it could not be vetted for secrets`),
+    );
     return undefined;
   }
 }
@@ -474,22 +540,35 @@ async function vetStageValue(text, redact, warnings, label) {
  * 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 async function sanitizeText(text, options = {}) {
   const { redact, filterInjection, sgrCarveOut = false } = options;
-  const { warnings, found, cleaned, modified, sgrNote } = processLayer1(
+  const { findings, found, cleaned, modified } = processLayer1(
     text,
     sgrCarveOut,
   );
   /** @type {PipelineState} */
-  const state = { text: cleaned, found, warnings, modified, sgrNote };
+  const state = {
+    text: cleaned,
+    found,
+    findings,
+    modified,
+    unreportedChange: false,
+  };
 
   const revealText = await applyMarkdownPipeline(state, options);
 
@@ -520,7 +599,7 @@ export async function sanitizeText(text, options = {}) {
       // message; free text is refused (throws) so no filter-supplied byte ever
       // reaches the model-facing context. `null`/`undefined` means no warning.
       if (res.warning != null)
-        state.warnings.push(mapFilterWarning(res.warning));
+        state.findings.push(warning(mapFilterWarning(res.warning)));
     }
   }
 
@@ -535,15 +614,24 @@ export async function sanitizeText(text, options = {}) {
       : await vetStageValue(
           revealText,
           redact,
-          state.warnings,
+          state.findings,
           "pre-splice copy of the removed HTML",
         );
+  const warnings = warningMessages(state.findings);
+  const notes = noteMessages(state.findings);
   return {
     cleaned: state.text,
     found: state.found,
-    warnings: state.warnings,
+    warnings,
+    notes,
     modified: state.modified,
-    sgrNote: state.sgrNote,
+    // Kept under its original name (it is a published field, and renaming a
+    // published field for a wording win is a breaking change) but now derived
+    // rather than tracked: "nothing here rose above a note". That is a strict
+    // generalization of what it used to mean — the inert-ANSI strip that set it
+    // before is now simply the most common way to end up note-only.
+    sgrNote:
+      notes.length > 0 && warnings.length === 0 && !state.unreportedChange,
     ...(reveal !== undefined && { reveal }),
   };
 }
@@ -637,8 +725,10 @@ function depthMemo() {
 /**
  * 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):
@@ -654,13 +744,23 @@ function depthMemo() {
  * @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 async function sanitizeValue(value, options, warnings, reveals = []) {
+export async function sanitizeValue(
+  value,
+  options,
+  warnings,
+  reveals = [],
+  notes = [],
+) {
   return sanitizeValueAt(
     value,
     options,
     warnings,
+    notes,
     reveals,
     0,
     new WeakSet(),
@@ -677,6 +777,7 @@ export async function sanitizeValue(value, options, warnings, reveals = []) {
  * @param {any} value
  * @param {SanitizeTextOptions} options
  * @param {string[]} warnings
+ * @param {string[]} notes  accumulates each string leaf's NOTE-severity findings
  * @param {string[]} reveals  accumulates each string leaf's pre-Layer-2 text
  * @param {number} depth
  * @param {WeakSet<object>} seen
@@ -696,6 +797,7 @@ async function sanitizeValueAt(
   value,
   options,
   warnings,
+  notes,
   reveals,
   depth,
   seen,
@@ -704,6 +806,7 @@ async function sanitizeValueAt(
   if (typeof value === "string") {
     const result = await sanitizeText(value, options);
     warnings.push(...result.warnings);
+    notes.push(...result.notes);
     if (result.reveal !== undefined) reveals.push(result.reveal);
     return {
       value: result.cleaned,
@@ -792,6 +895,7 @@ async function sanitizeValueAt(
           item,
           options,
           warnings,
+          notes,
           reveals,
           depth + 1,
           seen,
@@ -827,6 +931,7 @@ async function sanitizeValueAt(
         item,
         options,
         warnings,
+        notes,
         reveals,
         depth + 1,
         seen,

package/src/prompt.mjs

@@ -21,11 +21,10 @@ import {
   CHECKS,
   CATEGORY,
   CATEGORY_LABELS,
-  LONG_RUN_RE,
   LONG_RUN_THRESHOLD,
   SCATTERED_THRESHOLD,
-  countPayloadInvisible,
-  stripInvisible,
+  countEffectiveInvisible,
+  payloadLongRunSample,
 } from "./invisible.mjs";
 import { isBenignAnsi, stripAnsiFully } from "./layer1.mjs";
 import { CONTROL_INTRODUCER_SOURCE } from "./ansi.mjs";
@@ -95,31 +94,15 @@ export function classifyPrompt(prompt, strip = stripAnsiFully) {
   const hasAnsi = ANSI_INTRODUCER.test(prompt);
   const deAnsi = strip(prompt);
 
-  const longRunSample = deAnsi.match(LONG_RUN_RE)?.[0] ?? null;
-  // Count only PAYLOAD invisibles for the scatter gate: ZWNJ/ZWJ (and emoji
-  // VS16) that do real rendering work are excluded, so a legitimately
-  // joiner-dense multilingual prompt (formal Persian, an emoji ZWJ sequence) is
-  // not blocked by sheer joiner count. This mirrors carveStrip's own
-  // payloadInvis < SCATTERED_THRESHOLD gate so the block and strip layers agree.
-  const payloadInvisible = countPayloadInvisible(deAnsi);
-  // Preserved-joiner covert channel (O3). countPayloadInvisible EXCLUDES the
-  // ZWNJ/ZWJ (and emoji selectors) that do real rendering work, so a channel
-  // built entirely from MEANINGFUL joiners — an attacker alternates
-  // `letter joiner letter joiner …` so every joiner sits between two cursive
-  // letters — counts as ZERO here and would pass, even though the strip layer
-  // (carveStrip) only PRESERVES joiners up to a per-document budget
-  // (TOTAL_PRESERVED_JOINER_BUDGET / CONSECUTIVE_JOINER_CAP) and strips the
-  // surplus as payload. A prompt channel cannot strip, only block, so mirror
-  // that budget by counting the joiners the strip layer WOULD remove — delegated
-  // to stripInvisible (the SSOT) rather than re-deriving the budget here, which
-  // would risk drift — and fold that surplus into the count the scatter gate
-  // sees. A leading BOM is preserved by the strip but counted by
-  // countPayloadInvisible, so the difference can go slightly negative; clamp it.
-  const surplusPreservedJoiners = Math.max(
-    0,
-    [...deAnsi].length - [...stripInvisible(deAnsi)].length - payloadInvisible,
-  );
-  const invisibleCount = payloadInvisible + surplusPreservedJoiners;
+  // Both gates read the SHARED definitions in ./invisible.mjs rather than
+  // spelling their own: what counts as a hidden run, and how many invisibles a
+  // text really carries once the carve-out's preserved joiners and its
+  // over-budget surplus are accounted for. See payloadLongRunSample /
+  // countEffectiveInvisible — including why the run probe masks the invisibles
+  // the strip layer would PRESERVE, so a legitimate emoji sequence cannot block
+  // a prompt that the strip layer would not even have flagged.
+  const longRunSample = payloadLongRunSample(deAnsi);
+  const invisibleCount = countEffectiveInvisible(deAnsi);
   const invisiblesBelowThreshold =
     longRunSample === null && invisibleCount < SCATTERED_THRESHOLD;
 

package/src/severity.mjs

@@ -0,0 +1,97 @@
+/**
+ * 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 = Object.freeze({
+  NOTE: "note",
+  WARNING: "warning",
+});
+
+/**
+ * @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) {
+  return { severity: SEVERITY.WARNING, message };
+}
+
+/**
+ * A NOTE-severity finding: reported, not alarming.
+ * @param {string} message
+ * @returns {Finding}
+ */
+export function note(message) {
+  return { severity: SEVERITY.NOTE, message };
+}
+
+/**
+ * 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, message) {
+  return isWarning ? warning(message) : note(message);
+}
+
+/**
+ * The messages of every WARNING-severity finding, in order.
+ * @param {readonly Finding[]} findings
+ * @returns {string[]}
+ */
+export function warningMessages(findings) {
+  return findings
+    .filter((entry) => entry.severity === SEVERITY.WARNING)
+    .map((entry) => entry.message);
+}
+
+/**
+ * The messages of every NOTE-severity finding, in order.
+ * @param {readonly Finding[]} findings
+ * @returns {string[]}
+ */
+export function noteMessages(findings) {
+  return findings
+    .filter((entry) => entry.severity === SEVERITY.NOTE)
+    .map((entry) => entry.message);
+}

package/types/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[];