agent-sanitizer 2.24.2 → 2.26.0

package/claude-hooks/scan-invisible-chars.mjs

@@ -31,6 +31,18 @@ import {
 } from "./lib/invisible-alert.mjs";
 import { bestEffortTrace, trace, TraceEvent } from "./lib/trace.mjs";
 import { reportSlowHook, startHookTimer } from "./lib/hook-timing.mjs";
+// Relative, not the `agent-sanitizer` specifier every other engine import uses:
+// this is the scan's SCOPE, which is hook policy and must move with the hook.
+// Routing it through the specifier would resolve it, in the shipped plugin
+// bundle, against a PINNED older engine that does not export it — leaving the
+// walk with undefined globs while believing it had scanned everything. The
+// module is dependency-free data (see src/claude-context.mjs), so importing it
+// statically carries none of the fail-open hazard lazyImport exists to cover.
+import {
+  CLAUDE_CONTEXT_SUBDIRS,
+  CLAUDE_INSTRUCTION_GLOBS,
+  excludeFromContextScan,
+} from "../src/claude-context.mjs";
 
 // Layer-1 primitives, bound via lazyImport (see its doc for the fail-OPEN
 // hazard of a bare static npm import — here the instruction files would load
@@ -192,99 +204,27 @@ function decodeRun(run) {
   };
 }
 
-/**
- * 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 = Object.freeze([
-  "agents",
-  "commands",
-  "output-styles",
-  "skills",
-]);
-
-// The glob patterns for one `.claude` tree at `prefix` (empty for the project
-// root, a doubled-star segment for nested ones): its top-level markdown, plus the
-// whitelisted context subdirectories. Built once, from the one list above.
-/** @param {string} prefix @returns {string[]} */
-function claudeDirPatterns(prefix) {
-  return [
-    `${prefix}.claude/*.md`,
-    ...CLAUDE_CONTEXT_SUBDIRS.map((sub) => `${prefix}.claude/${sub}/**/*.md`),
-  ];
-}
-
-/**
- * Entries the walk must not descend into or return: `node_modules`, and every
- * child of a `.claude` directory that is not whitelisted context.
- *
- * The patterns alone would already refuse to MATCH those files, but globSync
- * 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).
- *
- * globSync calls this with both bare names and repo-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}
- */
-function excludeFromScan(entry) {
-  if (entry === "node_modules") return true;
-  const parts = entry.split(/[/\\]/);
-  const claudeIndex = parts.indexOf(".claude");
-  const tail = parts.slice(claudeIndex + 1);
-  if (claudeIndex === -1 || tail.length === 0) return false;
-  // `.claude/<file>.md` is context (a top-level note); anything else directly
-  // under `.claude` must be a whitelisted subdirectory to be walked at all.
-  if (tail.length === 1 && tail[0].endsWith(".md")) return false;
-  return !CLAUDE_CONTEXT_SUBDIRS.includes(tail[0]);
-}
-
 /**
  * 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[]}
  */
 function findInstructionFiles(dir) {
-  return globSync(
-    [
-      "**/CLAUDE.md",
-      "**/CLAUDE.local.md",
-      "**/AGENTS.md",
-      ...claudeDirPatterns("**/"),
-    ],
-    { cwd: dir, exclude: excludeFromScan },
-  ).map((name) => join(dir, name));
+  return globSync([...CLAUDE_INSTRUCTION_GLOBS], {
+    cwd: dir,
+    exclude: excludeFromContextScan,
+  }).map((name) => join(dir, name));
 }
 
 // Scanner
@@ -324,6 +264,11 @@ function scanFile(filePath) {
 }
 
 export {
+  // Re-exported, never redefined: the scope this hook walks is the library's
+  // (src/claude-context.mjs), and a consumer that reads it off this hook must
+  // get that same list rather than a second copy that can drift.
+  CLAUDE_CONTEXT_SUBDIRS,
+  CLAUDE_INSTRUCTION_GLOBS,
   decodeRun,
   findInstructionFiles,
   scanFile,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.24.2",
+  "version": "2.26.0",
   "description": "Defend an agent against hidden-content injection: strip payload-capable invisible Unicode and ANSI, splice out human-invisible HTML, and flag data-exfil URLs in untrusted text before any model sees it.",
   "type": "module",
   "repository": {

package/src/claude-context.mjs

@@ -0,0 +1,125 @@
+/**
+ * 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 = Object.freeze([
+  "agents",
+  "commands",
+  "output-styles",
+  "skills",
+]);
+
+// The glob patterns for one `.claude` tree at `prefix` (empty for the project
+// root, a doubled-star segment for nested ones): its top-level markdown, plus the
+// whitelisted context subdirectories. Built once, from the one list above.
+/** @param {string} prefix @returns {string[]} */
+function claudeDirPatterns(prefix) {
+  return [
+    `${prefix}.claude/*.md`,
+    ...CLAUDE_CONTEXT_SUBDIRS.map((sub) => `${prefix}.claude/${sub}/**/*.md`),
+  ];
+}
+
+/**
+ * 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 = Object.freeze([
+  "**/CLAUDE.md",
+  "**/CLAUDE.local.md",
+  "**/AGENTS.md",
+  ...claudeDirPatterns("**/"),
+]);
+
+/**
+ * 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) {
+  return entry === "node_modules";
+}
+
+/**
+ * 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) {
+  if (excludeNodeModules(entry)) return true;
+  const parts = entry.split(/[/\\]/);
+  const claudeIndex = parts.indexOf(".claude");
+  const tail = parts.slice(claudeIndex + 1);
+  if (claudeIndex === -1 || tail.length === 0) return false;
+  // `.claude/<file>.md` is context (a top-level note); anything else directly
+  // under `.claude` must be a whitelisted subdirectory to be walked at all.
+  if (tail.length === 1 && tail[0].endsWith(".md")) return false;
+  return !CLAUDE_CONTEXT_SUBDIRS.includes(tail[0]);
+}

package/src/html.mjs

@@ -2313,26 +2313,45 @@ function multiUrlAttr(value) {
  * `context` selects the per-URL check the caller applies: resource URLs get the
  * exfil-shape test; form-submission and meta-refresh targets additionally flag
  * any absolute off-origin destination.
+ *
+ * `autoFetched` says whether reaching this URL takes a deliberate act. Exactly
+ * one attribute here does: `href` on an `<a>`, which somebody has to follow.
+ * Every other one is fetched by the renderer on sight (`src`, `srcset`,
+ * `background`, and `href` on a `<link>`), fires on a click aimed at something
+ * else (`ping`), or navigates on its own (a form action, a meta refresh). The
+ * distinction is the caller's severity line, not a detection line — the URL is
+ * reported either way (see the exfil tier in ../src/output.mjs).
  * @param {string} text
- * @returns {Array<{ url: string, isImage: boolean, context: "resource" | "form" | "refresh" }>}
+ * @returns {Array<{ url: string, isImage: boolean, autoFetched: boolean, context: "resource" | "form" | "refresh" }>}
  */
 function extractHtmlUrls(text) {
   const tree = parseFragment(text);
-  /** @type {Array<{ url: string, isImage: boolean, context: "resource" | "form" | "refresh" }>} */
+  /** @type {Array<{ url: string, isImage: boolean, autoFetched: boolean, context: "resource" | "form" | "refresh" }>} */
   const urls = [];
   visit(tree, "element", (/** @type {any} */ node) => {
     // hast element nodes always carry a `properties` object (parse5 sets it).
     const props = node.properties;
     const isImage = node.tagName === "img";
+    const isAnchor = node.tagName === "a";
     for (const key of ["src", "href", "background"])
       if (typeof props[key] === "string")
-        urls.push({ url: props[key], isImage, context: "resource" });
+        urls.push({
+          url: props[key],
+          isImage,
+          autoFetched: !(key === "href" && isAnchor),
+          context: "resource",
+        });
     for (const key of ["srcSet", "ping"])
       for (const url of multiUrlAttr(props[key]))
-        urls.push({ url, isImage, context: "resource" });
+        urls.push({ url, isImage, autoFetched: true, context: "resource" });
     for (const key of ["action", "formAction"])
       if (typeof props[key] === "string")
-        urls.push({ url: props[key], isImage: false, context: "form" });
+        urls.push({
+          url: props[key],
+          isImage: false,
+          autoFetched: true,
+          context: "form",
+        });
     // rehype delivers `http-equiv` as an array (comma-separated); join it back
     // so a `refresh` directive is matched regardless of how it was tokenized.
     const httpEquiv = Array.isArray(props.httpEquiv)
@@ -2344,7 +2363,13 @@ function extractHtmlUrls(text) {
       typeof props.content === "string"
     ) {
       const url = metaRefreshUrl(props.content);
-      if (url) urls.push({ url, isImage: false, context: "refresh" });
+      if (url)
+        urls.push({
+          url,
+          isImage: false,
+          autoFetched: true,
+          context: "refresh",
+        });
     }
   });
   return urls;
@@ -2362,13 +2387,18 @@ const OFF_ORIGIN_REASON = {
  * 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) {
   if (!MD_LINK_HINT.test(text) && !HTML_TAG_PRESENT.test(text)) return null;
 
-  /** @type {Array<{ isImage: boolean, reason: string, target: string }>} */
+  /** @type {Array<{ isImage: boolean, autoFetched: boolean, reason: string, target: string }>} */
   const threats = [];
 
   try {
@@ -2386,20 +2416,25 @@ export function detectExfil(text) {
       if (!reason) return;
       threats.push({
         isImage: node.type === "image",
+        // A markdown image is fetched the moment the document renders; a link
+        // (or a definition, which only names one) is not.
+        autoFetched: node.type === "image",
         reason,
         target: urlHost(node.url),
       });
     });
 
     // HTML attributes (not AST nodes in remark).
-    for (const { url, isImage, context } of extractHtmlUrls(text)) {
+    for (const { url, isImage, autoFetched, context } of extractHtmlUrls(
+      text,
+    )) {
       const reason =
         checkExfilUrl(url) ||
         (context !== "resource" && isOffOrigin(url)
           ? OFF_ORIGIN_REASON[context]
           : null);
       if (!reason) continue;
-      threats.push({ isImage, reason, target: urlHost(url) });
+      threats.push({ isImage, autoFetched, reason, target: urlHost(url) });
     }
   } catch {
     // The parse/visit blew up (stack overflow on pathological nesting). Fail
@@ -2409,6 +2444,9 @@ export function detectExfil(text) {
     return [
       {
         isImage: false,
+        // Fail closed on the severity tier too: an input the scanner could not
+        // read is not evidence that what it hides is harmless.
+        autoFetched: true,
         reason: "input too deeply nested to scan for exfil URLs",
         target: "(unparseable HTML)",
       },

package/src/index.mjs

@@ -73,7 +73,8 @@ export {
  * 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
@@ -83,7 +84,7 @@ export {
  *
  * 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
@@ -91,15 +92,15 @@ export {
  * 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 async function sanitize(text, options) {
   if (typeof text !== "string")
     throw new TypeError("sanitize(text, options): text must be a string");
   const { html = false } = options ?? {};
-  const { cleaned, found, warnings } = await sanitizeText(text, {
+  const { cleaned, found, warnings, notes } = await sanitizeText(text, {
     html,
     exfilScan: html,
   });
-  return { cleaned, found, warnings };
+  return { cleaned, found, warnings, notes };
 }

package/src/instructions.mjs

@@ -12,6 +12,10 @@
  * The target file set is CALLER-SUPPLIED: pass the globs your agent's
  * instruction files live under (e.g. `["CLAUDE.md", "AGENTS.md",
  * ".claude/**\/*.md", "**\/SKILL.md"]`), so no agent's convention is baked in.
+ * Claude Code's own convention is re-exported below
+ * ({@link CLAUDE_INSTRUCTION_GLOBS} / {@link excludeFromContextScan}) so a
+ * caller that wants it takes the SessionStart hook's exact scope rather than
+ * approximating it — see ./claude-context.mjs.
  */
 import {
   readFileSync,
@@ -36,6 +40,18 @@ import {
   countPayloadInvisible,
   stripInvisible,
 } from "./invisible.mjs";
+import { excludeNodeModules } from "./claude-context.mjs";
+
+// The library's public door onto Claude Code's context scope. The definitions
+// live in a dependency-free data module because the SessionStart hook imports
+// them relatively (see ./claude-context.mjs); re-exporting them here is what
+// makes `agent-sanitizer/instructions` the single place a CLI, a port or a fork
+// reads that scope from instead of re-spelling it.
+export {
+  CLAUDE_CONTEXT_SUBDIRS,
+  CLAUDE_INSTRUCTION_GLOBS,
+  excludeFromContextScan,
+} from "./claude-context.mjs";
 
 // Prefix on any decoded tag-character payload. The decoded text is
 // attacker-controlled and flows into the scan report, which itself reaches model
@@ -296,18 +312,28 @@ function keepContained(absPath, realRoot, literalRoot, pattern) {
  * 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, { cwd = process.cwd() } = {}) {
+export function findInstructionFiles(
+  globs,
+  { cwd = process.cwd(), exclude } = {},
+) {
   const literalRoot = resolve(cwd);
   const realRoot = realpathSync(literalRoot);
   const seen = new Set();
   for (const pattern of globs)
     for (const name of globSync(pattern, {
       cwd,
-      exclude: (entry) => entry === "node_modules",
+      exclude: (entry) =>
+        excludeNodeModules(entry) || (exclude?.(entry) ?? false),
     })) {
       // globSync returns absolute paths verbatim for an absolute pattern and
       // cwd-relative names otherwise; joining an already-absolute name would
@@ -324,12 +350,16 @@ export function findInstructionFiles(globs, { cwd = process.cwd() } = {}) {
  * 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, { cwd = process.cwd() } = {}) {
+export function scanInstructionFiles(
+  globs,
+  { cwd = process.cwd(), exclude } = {},
+) {
   const out = [];
-  for (const file of findInstructionFiles(globs, { cwd })) {
+  for (const file of findInstructionFiles(globs, { cwd, exclude })) {
     let content;
     try {
       content = readFileSync(file, "utf-8");

package/src/invisible.mjs

@@ -175,11 +175,7 @@ export const LONG_RUN_RE = new RegExp(
  */
 export function describeStripped(invisFound, deAnsi) {
   let msg = `Stripped: ${invisFound.map((code) => CATEGORY_LABELS[code]).join(", ")}`;
-  LONG_RUN_RE.lastIndex = 0;
-  // Probe only the PAYLOAD invisibles: a legitimate emoji/flag/variation
-  // sequence is carve-out-preserved and masked out here, so it never trips the
-  // injection marker (alert fatigue) while a genuine hidden run still surfaces.
-  if (LONG_RUN_RE.test(payloadInvisibleView(deAnsi)))
+  if (payloadLongRunSample(deAnsi) !== null)
     msg += " [LONG RUN — possible injection payload]";
   return (
     msg +
@@ -1048,6 +1044,90 @@ export function payloadInvisibleView(text) {
   return out;
 }
 
+/**
+ * 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) {
+  LONG_RUN_RE.lastIndex = 0;
+  return payloadInvisibleView(text).match(LONG_RUN_RE)?.[0] ?? 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) {
+  const payload = countPayloadInvisible(text);
+  const surplusPreservedJoiners = Math.max(
+    0,
+    [...text].length - [...stripInvisible(text)].length - payload,
+  );
+  return payload + surplusPreservedJoiners;
+}
+
+/**
+ * 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) {
+  return (
+    payloadLongRunSample(text) === null &&
+    countEffectiveInvisible(text) < LONG_RUN_THRESHOLD
+  );
+}
+
 /**
  * Strip payload-capable invisible chars and report which categories were
  * removed. A single leading U+FEFF (BOM) is preserved as a legitimate marker;

package/src/layer1.mjs

@@ -109,6 +109,21 @@ export function stripAnsiFully(input, kinds) {
   return out;
 }
 
+/**
+ * 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 =
+  "Inert ANSI stripped (display-only colour and/or a stray escape byte that " +
+  "formed no control sequence); pipe through cat -v to inspect raw escapes.";
+
 /**
  * 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