agent-sanitizer 2.47.14 → 2.48.0

package/THREAT-MODEL.md

@@ -383,6 +383,22 @@ build that emits that event, and `scan-loaded-instructions` switched off in
 Nothing on disk tells them apart, so the PreToolUse gate names all three, once
 per session, rather than leaving the gap silent.
 
+A fourth state is not one of them and is not reported as one: the host emits no
+event when it has nothing to announce. The gate therefore asks not "does anything
+load at launch" but "does anything load whose load `InstructionsLoaded` NAMES,
+with bytes in it" — the `eventNamed` column of the same table, read through
+`announcedByInstructionsLoaded` for the project's own tree and through
+`USER_GLOBAL_EVENT_NAMED_GLOBS` for the user-global root, whose files carry no
+`.claude` segment to classify by. A launch holding only an `AGENTS.md`, a skill
+or an empty `~/.claude/CLAUDE.md` fires no event however the hook is wired, so
+the missing scan there is evidence of nothing. The trade this accepts is a false
+NEGATIVE: a repo whose announced instruction files all sit in subdirectories —
+a monorepo of per-package `CLAUDE.md` under a root carrying only `AGENTS.md`, on
+a machine with no user-global memory — loses the notice until a tool call touches
+one of those directories, which is what the gate's per-call `touchedDir` check
+recovers. Weighed against a false POSITIVE on every session launched outside a
+project, which trains the operator to skip the notice everywhere.
+
 That table is a claim about someone else's product, so the event that names a
 loaded file is also what falsifies it. `contextScopeContradiction` checks every
 path the hook is handed and reports two observations: context loading out of a

package/claude-hooks/lib/invisible-alert.mjs

@@ -38,9 +38,10 @@ import {
 // module's, not a copy of the SessionStart hook's target-discovery glue.
 import {
   ancestorInstructionFiles,
-  CLAUDE_CONTEXT_SUBDIRS,
+  announcedByInstructionsLoaded,
   CLAUDE_LAUNCH_GLOBS,
   excludeFromContextScan,
+  USER_GLOBAL_EVENT_NAMED_GLOBS,
 } from "../../src/claude-context.mjs";
 
 // Layer-1 scrubber for the untrusted alert-store contents the gate splices into a
@@ -370,11 +371,10 @@ export function launchInstructionFiles(dir) {
 }
 
 /**
- * Whether anything Claude Code loads at launch from `dir` actually has bytes.
- * An existing but EMPTY file (a freshly `touch`ed `~/.claude/CLAUDE.md`) is
- * nothing to load: Claude Code 2.1.246 fires no InstructionsLoaded event when
- * a launch has nothing in it, so the missing event is expected there, not a
- * sign the scanner is unwired.
+ * Whether any of `files` has bytes for the host to load. An existing but EMPTY
+ * file (a freshly `touch`ed `~/.claude/CLAUDE.md`) is nothing to load: Claude
+ * Code 2.1.246 fires no InstructionsLoaded event when a launch has nothing in
+ * it, so the missing event is expected there, not a sign the scanner is unwired.
  *
  * A file this uid cannot even STAT (EACCES, EISDIR, ELOOP…) is unvetted
  * context, not evidence of absence — the same split scan-invisible-chars.mjs's
@@ -382,11 +382,11 @@ export function launchInstructionFiles(dir) {
  * as "no content" would suppress the notice over a file that may carry a real,
  * unscanned payload, so only ENOENT counts as nothing there; anything else
  * counts as content and leaves the notice free to fire.
- * @param {string} dir
+ * @param {string[]} files
  * @returns {boolean}
  */
-function launchHasContent(dir) {
-  for (const file of launchInstructionFiles(dir)) {
+function anyFileHasBytes(files) {
+  for (const file of files) {
     try {
       if (statSync(file).size > 0) return true;
     } catch (err) {
@@ -397,13 +397,32 @@ function launchHasContent(dir) {
   return false;
 }
 
+/**
+ * The files loading at launch from `dir` whose load `InstructionsLoaded` would
+ * ANNOUNCE. Claude Code names CLAUDE.md, CLAUDE.local.md and `.claude/rules` as
+ * it loads them and stays silent for every other kind, so a launch carrying only
+ * an `AGENTS.md` or a skill fires no event however the hook is wired — and its
+ * silence is evidence of nothing.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function announcedLaunchFiles(dir) {
+  return launchInstructionFiles(dir).filter(announcedByInstructionsLoaded);
+}
+
 /**
  * Whether the USER-GLOBAL `~/.claude` memory and rules — a second root Claude
  * Code loads at launch regardless of the project directory (see
- * scan-loaded-instructions.mjs's header) — has any bytes. `launchHasContent`
- * cannot see this root on its own: it is `dir`-relative, and `~/.claude` is
- * outside `dir`'s own tree whenever the project is not `$HOME` itself, exactly
- * the case a project opened anywhere but home is in.
+ * scan-loaded-instructions.mjs's header) — holds an announced file with bytes.
+ * {@link announcedLaunchFiles} cannot see this root on its own: it is
+ * `dir`-relative, and `~/.claude` is outside `dir`'s own tree whenever the
+ * project is not `$HOME` itself, exactly the case a project opened anywhere but
+ * home is in.
+ *
+ * Globs the announced kinds directly rather than filtering paths afterwards:
+ * this root IS a `.claude` directory, and under `CLAUDE_CONFIG_DIR` it may carry
+ * no `.claude` segment at all, so a path-shape classifier has nothing to read
+ * there and would answer "not announced" for every user-global rule.
  *
  * Honours `CLAUDE_CONFIG_DIR` the way plugin/scripts/enable-auto-update.mjs's
  * own resolution does, since that root — not always `~/.claude` — is where
@@ -413,19 +432,12 @@ function launchHasContent(dir) {
  */
 function userGlobalLaunchHasContent(env = process.env) {
   const configDir = env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
-  const candidates = globSync(
-    ["*.md", ...CLAUDE_CONTEXT_SUBDIRS.map((sub) => `${sub}/**/*.md`)],
-    { cwd: configDir, exclude: excludeFromContextScan },
-  ).map((name) => join(configDir, name));
-  for (const file of candidates) {
-    try {
-      if (statSync(file).size > 0) return true;
-    } catch (err) {
-      if (/** @type {NodeJS.ErrnoException} */ (err).code !== "ENOENT")
-        return true;
-    }
-  }
-  return false;
+  return anyFileHasBytes(
+    globSync([...USER_GLOBAL_EVENT_NAMED_GLOBS], {
+      cwd: configDir,
+      exclude: excludeFromContextScan,
+    }).map((name) => join(configDir, name)),
+  );
 }
 
 /**
@@ -440,8 +452,9 @@ function userGlobalLaunchHasContent(env = process.env) {
  * tool touched a directory that DOES carry real, unscanned content.
  *
  * SessionStart scans what loads at launch; a subdirectory's file is scanned by
- * the event; no scan means nothing says so — unless nothing touched so far had
- * anything to scan either. The notice names all three remaining causes, since
+ * the event; no scan means nothing says so — unless nothing touched so far held
+ * a file the event would have ANNOUNCED, with bytes in it. The three remaining
+ * causes are named together, since
  * the marker cannot tell them apart: an unwired event, a Claude Code older than
  * EVENT_MIN_CLI_VERSION, or the hook disabled via AGENT_SANITIZER_DISABLED_HOOKS.
  * @param {string} [sessionId]  the harness's session identity (see
@@ -461,11 +474,14 @@ export function instructionsLoadedGapNotice(
   if (markerIsTrusted(instructionsLoadedNoticeFile(sessionId))) return null;
   const launchCached = markerIsTrusted(launchEmptyFile(sessionId));
   const launchHasBytes =
-    !launchCached && (launchHasContent(dir) || userGlobalLaunchHasContent());
+    !launchCached &&
+    (anyFileHasBytes(announcedLaunchFiles(dir)) ||
+      userGlobalLaunchHasContent());
   if (!launchCached && !launchHasBytes)
     writeSentinelFile(launchEmptyFile(sessionId));
   const touchedHasBytes =
-    touchedDir !== undefined && launchHasContent(touchedDir);
+    touchedDir !== undefined &&
+    anyFileHasBytes(announcedLaunchFiles(touchedDir));
   if (!launchHasBytes && !touchedHasBytes) return null;
   return (
     "agent-sanitizer: no InstructionsLoaded scan has run this session, so " +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.47.14",
+  "version": "2.48.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

@@ -301,6 +301,46 @@ function classifyContextPath(path) {
   );
 }
 
+/**
+ * The `eventNamed` kinds spelled relative to the USER-GLOBAL config root — the
+ * `~/.claude` (or `CLAUDE_CONFIG_DIR`) directory Claude Code loads at launch
+ * whatever the project is.
+ *
+ * A second spelling because that root is a `.claude` directory ITSELF: its files
+ * are `CLAUDE.md` and `rules/x.md`, not `.claude/rules/x.md`, and under
+ * `CLAUDE_CONFIG_DIR` the path may carry no `.claude` segment at all — so
+ * {@link announcedByInstructionsLoaded}, which reads a path's own segments, has
+ * nothing there to classify by. Every row's shape is asserted in
+ * test/claude-context.test.mjs, since a shape with no spelling here would glob
+ * to nothing and read as "no event is coming".
+ */
+export const USER_GLOBAL_EVENT_NAMED_GLOBS = Object.freeze(
+  CLAUDE_CONTEXT_KINDS.filter((row) => row.eventNamed).map((row) =>
+    row.shape === "dir-file" ? row.name : `${row.name}/**/*.md`,
+  ),
+);
+
+/**
+ * Whether Claude Code announces loading `path` with an `InstructionsLoaded`
+ * event — the `eventNamed` column of {@link CLAUDE_CONTEXT_KINDS}, asked of one
+ * path.
+ *
+ * The complement of {@link contextScopeContradiction}, which checks the same
+ * column against an event that DID fire. This one answers before any fires, so a
+ * consumer can tell "the event is not coming" from "the event never came": a
+ * launch carrying only an `AGENTS.md` or a skill has nothing for the host to
+ * announce, and its silence is evidence of nothing.
+ *
+ * A path the table does not name gets `false`, the same conservative answer a
+ * row added without the flag gets: this says an event IS coming, never that a
+ * file is uninteresting.
+ * @param {string} path  absolute or relative; only its segments are read
+ * @returns {boolean}
+ */
+export function announcedByInstructionsLoaded(path) {
+  return classifyContextPath(path)?.eventNamed === true;
+}
+
 // The `load_reason` values that mean Claude Code reached the file on its own —
 // its launch scan, and its walk into a directory. Every other reason names a
 // file something else chose, which is not evidence about the scan's scope.

package/src/instructions.mjs

@@ -51,6 +51,7 @@ import { excludeNodeModules } from "./claude-context.mjs";
 // reads that scope from instead of re-spelling it.
 export {
   ancestorInstructionFiles,
+  announcedByInstructionsLoaded,
   CLAUDE_CONTEXT_KINDS,
   CLAUDE_CONTEXT_SUBDIRS,
   CLAUDE_DIR_INSTRUCTION_FILES,
@@ -59,6 +60,7 @@ export {
   CLAUDE_MEMORY_FILES,
   contextScopeContradiction,
   excludeFromContextScan,
+  USER_GLOBAL_EVENT_NAMED_GLOBS,
 } from "./claude-context.mjs";
 
 // Prefix on any decoded tag-character payload. The decoded text is

package/types/claude-context.d.mts

@@ -56,6 +56,24 @@ export function excludeNodeModules(entry: string): boolean;
  * @returns {boolean}
  */
 export function excludeFromContextScan(entry: string): boolean;
+/**
+ * Whether Claude Code announces loading `path` with an `InstructionsLoaded`
+ * event — the `eventNamed` column of {@link CLAUDE_CONTEXT_KINDS}, asked of one
+ * path.
+ *
+ * The complement of {@link contextScopeContradiction}, which checks the same
+ * column against an event that DID fire. This one answers before any fires, so a
+ * consumer can tell "the event is not coming" from "the event never came": a
+ * launch carrying only an `AGENTS.md` or a skill has nothing for the host to
+ * announce, and its silence is evidence of nothing.
+ *
+ * A path the table does not name gets `false`, the same conservative answer a
+ * row added without the flag gets: this says an event IS coming, never that a
+ * file is uninteresting.
+ * @param {string} path  absolute or relative; only its segments are read
+ * @returns {boolean}
+ */
+export function announcedByInstructionsLoaded(path: string): boolean;
 /**
  * What a file the host just loaded as model context says about this table, or
  * null when it says nothing new. The InstructionsLoaded event is the only
@@ -156,3 +174,17 @@ export const CLAUDE_INSTRUCTION_GLOBS: readonly string[];
  * set, and with {@link excludeFromContextScan} to prune the `.claude` walk.
  */
 export const CLAUDE_LAUNCH_GLOBS: readonly string[];
+/**
+ * The `eventNamed` kinds spelled relative to the USER-GLOBAL config root — the
+ * `~/.claude` (or `CLAUDE_CONFIG_DIR`) directory Claude Code loads at launch
+ * whatever the project is.
+ *
+ * A second spelling because that root is a `.claude` directory ITSELF: its files
+ * are `CLAUDE.md` and `rules/x.md`, not `.claude/rules/x.md`, and under
+ * `CLAUDE_CONFIG_DIR` the path may carry no `.claude` segment at all — so
+ * {@link announcedByInstructionsLoaded}, which reads a path's own segments, has
+ * nothing there to classify by. Every row's shape is asserted in
+ * test/claude-context.test.mjs, since a shape with no spelling here would glob
+ * to nothing and read as "no event is coming".
+ */
+export const USER_GLOBAL_EVENT_NAMED_GLOBS: readonly string[];

package/types/claude-hooks/lib/invisible-alert.d.mts

@@ -109,8 +109,9 @@ export function launchInstructionFiles(dir: string): string[];
  * tool touched a directory that DOES carry real, unscanned content.
  *
  * SessionStart scans what loads at launch; a subdirectory's file is scanned by
- * the event; no scan means nothing says so — unless nothing touched so far had
- * anything to scan either. The notice names all three remaining causes, since
+ * the event; no scan means nothing says so — unless nothing touched so far held
+ * a file the event would have ANNOUNCED, with bytes in it. The three remaining
+ * causes are named together, since
  * the marker cannot tell them apart: an unwired event, a Claude Code older than
  * EVENT_MIN_CLI_VERSION, or the hook disabled via AGENT_SANITIZER_DISABLED_HOOKS.
  * @param {string} [sessionId]  the harness's session identity (see

package/types/instructions.d.mts

@@ -148,4 +148,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 { ancestorInstructionFiles, CLAUDE_CONTEXT_KINDS, CLAUDE_CONTEXT_SUBDIRS, CLAUDE_DIR_INSTRUCTION_FILES, CLAUDE_INSTRUCTION_GLOBS, CLAUDE_LAUNCH_GLOBS, CLAUDE_MEMORY_FILES, contextScopeContradiction, excludeFromContextScan } from "./claude-context.mjs";
+export { ancestorInstructionFiles, announcedByInstructionsLoaded, CLAUDE_CONTEXT_KINDS, CLAUDE_CONTEXT_SUBDIRS, CLAUDE_DIR_INSTRUCTION_FILES, CLAUDE_INSTRUCTION_GLOBS, CLAUDE_LAUNCH_GLOBS, CLAUDE_MEMORY_FILES, contextScopeContradiction, excludeFromContextScan, USER_GLOBAL_EVENT_NAMED_GLOBS } from "./claude-context.mjs";

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

@@ -56,6 +56,24 @@ export function excludeNodeModules(entry: string): boolean;
  * @returns {boolean}
  */
 export function excludeFromContextScan(entry: string): boolean;
+/**
+ * Whether Claude Code announces loading `path` with an `InstructionsLoaded`
+ * event — the `eventNamed` column of {@link CLAUDE_CONTEXT_KINDS}, asked of one
+ * path.
+ *
+ * The complement of {@link contextScopeContradiction}, which checks the same
+ * column against an event that DID fire. This one answers before any fires, so a
+ * consumer can tell "the event is not coming" from "the event never came": a
+ * launch carrying only an `AGENTS.md` or a skill has nothing for the host to
+ * announce, and its silence is evidence of nothing.
+ *
+ * A path the table does not name gets `false`, the same conservative answer a
+ * row added without the flag gets: this says an event IS coming, never that a
+ * file is uninteresting.
+ * @param {string} path  absolute or relative; only its segments are read
+ * @returns {boolean}
+ */
+export function announcedByInstructionsLoaded(path: string): boolean;
 /**
  * What a file the host just loaded as model context says about this table, or
  * null when it says nothing new. The InstructionsLoaded event is the only
@@ -156,3 +174,17 @@ export const CLAUDE_INSTRUCTION_GLOBS: readonly string[];
  * set, and with {@link excludeFromContextScan} to prune the `.claude` walk.
  */
 export const CLAUDE_LAUNCH_GLOBS: readonly string[];
+/**
+ * The `eventNamed` kinds spelled relative to the USER-GLOBAL config root — the
+ * `~/.claude` (or `CLAUDE_CONFIG_DIR`) directory Claude Code loads at launch
+ * whatever the project is.
+ *
+ * A second spelling because that root is a `.claude` directory ITSELF: its files
+ * are `CLAUDE.md` and `rules/x.md`, not `.claude/rules/x.md`, and under
+ * `CLAUDE_CONFIG_DIR` the path may carry no `.claude` segment at all — so
+ * {@link announcedByInstructionsLoaded}, which reads a path's own segments, has
+ * nothing there to classify by. Every row's shape is asserted in
+ * test/claude-context.test.mjs, since a shape with no spelling here would glob
+ * to nothing and read as "no event is coming".
+ */
+export const USER_GLOBAL_EVENT_NAMED_GLOBS: readonly string[];