agent-sanitizer 2.47.13 → 2.47.15

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

@@ -11,23 +11,38 @@
  * have one definition.
  */
 import {
+  existsSync,
+  globSync,
   lstatSync,
   mkdirSync,
   readdirSync,
   readFileSync,
   rmSync,
+  statSync,
 } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { basename, join } from "node:path";
-import { tmpdir, userInfo } from "node:os";
+import { homedir, tmpdir, userInfo } from "node:os";
 import {
   lazyImport,
   markerIsTrusted,
+  PROJECT_DIR,
   PROJECT_HASH,
   scrubUntrustedText,
   writeFileNoFollow,
   writeSentinelFile,
 } from "./hook-io.mjs";
+// Relative, like scan-invisible-chars.mjs's own import of this module: the
+// launch scope is hook POLICY (see src/claude-context.mjs), and this table is
+// pure data with no fs access of its own — the fs calls below are this
+// module's, not a copy of the SessionStart hook's target-discovery glue.
+import {
+  ancestorInstructionFiles,
+  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
 // permissionDecisionReason. The WELL-FORMED composition, not the bare applyLayer1:
@@ -256,13 +271,14 @@ export function sweepStaleSessions(sessionId) {
  * The ack always expires; the findings only when this session has its own store
  * and so merely INHERITED these.
  *
- * The two InstructionsLoaded markers under the same prefix answer "did a scan
- * run at all", so FALLBACK_TTL_MS must never reach them: expiring one mid-session
- * would render the gap notice on a session that WAS scanned. They still go, at
- * MARKER_TTL_MS — the same age the loop above ages a real session's prefix out
- * at, and far past any session's life — because the loop skips this prefix and
- * would otherwise leave a session-less host's markers in $TMPDIR forever, with
- * the gap notice suppressed on every later session.
+ * The three InstructionsLoaded markers under the same prefix answer "did a scan
+ * run at all" and "was launch empty", so FALLBACK_TTL_MS must never reach them:
+ * expiring one mid-session would render the gap notice on a session that WAS
+ * scanned, or re-glob a launch this session already found empty. They still go,
+ * at MARKER_TTL_MS — the same age the loop above ages a real session's prefix
+ * out at, and far past any session's life — because the loop skips this prefix
+ * and would otherwise leave a session-less host's markers in $TMPDIR forever,
+ * with the gap notice suppressed on every later session.
  * @param {string} [sessionId]
  * @returns {void}
  */
@@ -281,7 +297,11 @@ function sweepStaleFallback(sessionId) {
   };
   for (const path of [alertAckFile(), ...entries])
     if (!withinFallbackTtl(path)) drop(path);
-  for (const path of [instructionsLoadedFile(), instructionsLoadedNoticeFile()])
+  for (const path of [
+    instructionsLoadedFile(),
+    instructionsLoadedNoticeFile(),
+    launchEmptyFile(),
+  ])
     if (!withinTtl(path, MARKER_TTL_MS)) drop(path);
 }
 
@@ -311,32 +331,158 @@ export function recordInstructionsLoaded(sessionId) {
 const EVENT_MIN_CLI_VERSION = "2.1.69";
 
 /**
- * The one-time context line for a session where no InstructionsLoaded scan ran,
- * or null when the scan has been seen or the notice was already surfaced this
- * session.
+ * Companion marker: this session already found the LAUNCH set empty — that set
+ * (which files load at session start) cannot change mid-session, so a second
+ * glob of `dir` can never change that half of the answer. It says nothing about
+ * a directory touched later; {@link instructionsLoadedGapNotice}'s `touchedDir`
+ * covers that half fresh on every call instead.
+ * @param {string} [sessionId]
+ * @returns {string}
+ */
+export function launchEmptyFile(sessionId) {
+  return `${instructionsLoadedFile(sessionId)}.launch-empty`;
+}
+
+/**
+ * Every file Claude Code loads as model context AT LAUNCH from `dir`: its own
+ * instruction files, its `.claude/` context tree, and the CLAUDE.md /
+ * CLAUDE.local.md of every directory above it. THE SSOT scan-invisible-chars.mjs
+ * reads too (re-exported there as `findInstructionFiles`) — sharing the one
+ * function is what keeps the SessionStart scan's targets and this module's
+ * launch-emptiness check from drifting into two different answers for "what
+ * loads at launch". See src/claude-context.mjs for why this is the shallow
+ * launch scope and not a whole-tree walk.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+export function launchInstructionFiles(dir) {
+  return [
+    ...globSync([...CLAUDE_LAUNCH_GLOBS], {
+      cwd: dir,
+      exclude: excludeFromContextScan,
+    }).map((name) => join(dir, name)),
+    // Filtered, unlike the glob's matches: almost every parent directory holds
+    // neither memory file, so the unfiltered chain would file ~10 phantom
+    // targets per session into scan-invisible-chars.mjs's operator-facing
+    // "absent" bucket. A file that appears after this check was not loaded at
+    // launch either, so nothing is lost by not listing it.
+    ...ancestorInstructionFiles(dir).filter((file) => existsSync(file)),
+  ];
+}
+
+/**
+ * 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.
  *
- * PURE: it does not record that the notice was handed out. The caller records
- * separately, once the notice has actually landed in a response — a deny
- * assembled after this call discards the notice, and a marker written here would
- * have burned the session's one chance to report the loss.
+ * 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
+ * classifyReadFailure makes between ABSENT and SKIPPED. Reading such a failure
+ * 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[]} files
+ * @returns {boolean}
+ */
+function anyFileHasBytes(files) {
+  for (const file of files) {
+    try {
+      if (statSync(file).size > 0) return true;
+    } catch (err) {
+      if (/** @type {NodeJS.ErrnoException} */ (err).code !== "ENOENT")
+        return true;
+    }
+  }
+  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) — 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
+ * Claude Code actually reads this content from.
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {boolean}
+ */
+function userGlobalLaunchHasContent(env = process.env) {
+  const configDir = env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+  return anyFileHasBytes(
+    globSync([...USER_GLOBAL_EVENT_NAMED_GLOBS], {
+      cwd: configDir,
+      exclude: excludeFromContextScan,
+    }).map((name) => join(configDir, name)),
+  );
+}
+
+/**
+ * The one-time context line for a session where no InstructionsLoaded scan ran,
+ * or null when the scan has been seen, the notice already ran this session, or
+ * neither launch nor `touchedDir` could have fired the event.
  *
- * The loss it names is real and otherwise invisible: SessionStart scans the
- * instruction files that load at launch, and everything a subdirectory loads
- * later is scanned by the event. No scan, and nothing says so.
+ * PURE for the notice: nothing is recorded until the caller confirms it landed
+ * in a returned response. Launch-emptiness is cached once found — fixed for the
+ * session — but `touchedDir` is re-checked every call: the claim below is about
+ * SUBDIRECTORY files, so an empty launch must not silence a later call whose
+ * tool touched a directory that DOES carry real, unscanned content.
  *
- * The notice names the OBSERVABLE — no scan ran — and all three causes, because
- * the marker cannot tell them apart: a host that never wired the event to
- * scan-loaded-instructions, a Claude Code older than EVENT_MIN_CLI_VERSION, and
- * the hook switched off in AGENT_SANITIZER_DISABLED_HOOKS; asserting one sends a
- * reader who is in another to the wrong fix. The wiring cause leads because it is
- * the only one the reader can repair in this session, and nothing else reports it.
- * @param {string} [sessionId]  the harness's session identity, so the answer
- *   belongs to THIS session (see instructionsLoadedFile)
+ * 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 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
+ *   instructionsLoadedFile)
+ * @param {string} [dir]  the project root to check (injectable; defaults to
+ *   the real project)
+ * @param {string} [touchedDir]  this tool call's own target directory, when
+ *   known — re-checked every call, never cached
  * @returns {string | null}
  */
-export function instructionsLoadedGapNotice(sessionId) {
+export function instructionsLoadedGapNotice(
+  sessionId,
+  dir = PROJECT_DIR,
+  touchedDir,
+) {
   if (instructionsLoadedSeen(sessionId)) return null;
   if (markerIsTrusted(instructionsLoadedNoticeFile(sessionId))) return null;
+  const launchCached = markerIsTrusted(launchEmptyFile(sessionId));
+  const launchHasBytes =
+    !launchCached &&
+    (anyFileHasBytes(announcedLaunchFiles(dir)) ||
+      userGlobalLaunchHasContent());
+  if (!launchCached && !launchHasBytes)
+    writeSentinelFile(launchEmptyFile(sessionId));
+  const touchedHasBytes =
+    touchedDir !== undefined &&
+    anyFileHasBytes(announcedLaunchFiles(touchedDir));
+  if (!launchHasBytes && !touchedHasBytes) return null;
   return (
     "agent-sanitizer: no InstructionsLoaded scan has run this session, so " +
     "instruction files loaded from SUBDIRECTORIES (a nested CLAUDE.md, a " +

package/claude-hooks/pretooluse-sanitize.mjs

@@ -29,6 +29,7 @@
  */
 import { createRequire } from "node:module";
 import { readFileSync } from "node:fs";
+import { dirname } from "node:path";
 import {
   isMain,
   lazyImport,
@@ -424,6 +425,40 @@ export function preToolUseLayers(rehydrate, env = process.env) {
     : layers;
 }
 
+// The tools whose path field Claude Code sends as an absolute path by
+// contract, so reading it needs no cwd to resolve against. Bounded to these:
+// Glob/Grep's `path` can be relative or omitted (defaults to a cwd this
+// payload does not carry), and Bash has no reliable target at all — the same
+// carve-out WRITE_SHAPED_TOOLS below takes for Bash writes.
+const PATH_FIELD_BY_TOOL = /** @type {Record<string, string>} */ (
+  Object.freeze({
+    Read: "file_path",
+    Edit: "file_path",
+    Write: "file_path",
+    MultiEdit: "file_path",
+    NotebookEdit: "notebook_path",
+  })
+);
+
+/**
+ * The directory THIS tool call targets, for the InstructionsLoaded gap-notice
+ * check — or undefined when the tool carries no reliable absolute path. An
+ * imprecise guess here only ever WIDENS coverage (see instructionsLoadedGapNotice's
+ * `touchedDir`): missing a real target loses nothing this check did not
+ * already lack, and there is no wrong-directory case that suppresses a real
+ * finding.
+ * @param {string} tool
+ * @param {any} toolInput
+ * @returns {string | undefined}
+ */
+function toolTargetDir(tool, toolInput) {
+  const field = PATH_FIELD_BY_TOOL[tool];
+  const path = field && toolInput?.[field];
+  return typeof path === "string" && path.startsWith("/")
+    ? dirname(path)
+    : undefined;
+}
+
 /**
  * Compose the four protections. Returns the `hookSpecificOutput` fields to
  * emit, or null for a clean no-op. Throws only if a layer's engine throws; the
@@ -468,7 +503,11 @@ export async function buildPreToolUseResponse(
   // the notice was surfaced: a rehydrate deny below returns before the response
   // is assembled, and recording here would burn the session's one report on a
   // call that never carried it.
-  const gapNotice = instructionsLoadedGapNotice(input.session_id);
+  const gapNotice = instructionsLoadedGapNotice(
+    input.session_id,
+    undefined,
+    toolTargetDir(tool, toolInput),
+  );
   if (gapNotice !== null) contexts.push(gapNotice);
 
   // Layers 2-4, run by the declared pipeline: the driver — not this call order —

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

@@ -21,8 +21,8 @@
  * false positive the SSOT had already fixed, and its clean path was a bare
  * `writeFileSync` with none of cleanFile's symlink/UTF-8/TOCTOU guards.
  */
-import { existsSync, readFileSync, globSync } from "node:fs";
-import { join, relative, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { relative, resolve } from "node:path";
 import {
   awaitLazyDependency,
   emitHookResponse,
@@ -45,6 +45,7 @@ import {
   alertAckFile,
   alertDir,
   appendAlert,
+  launchInstructionFiles,
   sweepStaleSessions,
 } from "./lib/invisible-alert.mjs";
 import { formatReport } from "./lib/invisible-report.mjs";
@@ -59,11 +60,9 @@ import { reportSlowHook, startHookTimer } from "./lib/hook-timing.mjs";
 // so importing it statically carries none of the fail-open hazard lazyImport
 // exists to cover.
 import {
-  ancestorInstructionFiles,
   CLAUDE_CONTEXT_SUBDIRS,
   CLAUDE_INSTRUCTION_GLOBS,
   CLAUDE_LAUNCH_GLOBS,
-  excludeFromContextScan,
   isInsideDir,
 } from "../src/claude-context.mjs";
 
@@ -234,26 +233,14 @@ function decodeRun(run) {
  * files load when a tool reads their directory, and scan-loaded-instructions
  * scans each one at that moment.
  *
- * The scope itself — which globs, and which directories the walk must prune — is
- * the library's (see src/claude-context.mjs for why it is imported relatively
- * rather than through the `agent-sanitizer` specifier the plugin bundle pins).
+ * lib/invisible-alert.mjs's `launchInstructionFiles` IS this function — shared
+ * so its InstructionsLoaded gap-notice check reads the identical target set
+ * this scan does, rather than a second enumeration that could drift.
  * @param {string} dir
  * @returns {string[]}
  */
 function findInstructionFiles(dir) {
-  return [
-    ...globSync([...CLAUDE_LAUNCH_GLOBS], {
-      cwd: dir,
-      exclude: excludeFromContextScan,
-    }).map((name) => join(dir, name)),
-    // Filtered, unlike the glob's matches: almost every parent directory holds
-    // neither memory file, so the unfiltered chain would file ~10 phantom
-    // targets per session into the `absent` bucket and bury the one thing that
-    // bucket reports — a target that existed when the scan listed it and was
-    // gone by the read. A file that appears after this check was not loaded at
-    // launch either, so nothing is lost by not listing it.
-    ...ancestorInstructionFiles(dir).filter((file) => existsSync(file)),
-  ];
+  return launchInstructionFiles(dir);
 }
 
 // Scanner

package/package.json

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

@@ -74,31 +74,55 @@ export function sweepStaleSessions(sessionId?: string): void;
  * @returns {void}
  */
 export function recordInstructionsLoaded(sessionId?: string): void;
+/**
+ * Companion marker: this session already found the LAUNCH set empty — that set
+ * (which files load at session start) cannot change mid-session, so a second
+ * glob of `dir` can never change that half of the answer. It says nothing about
+ * a directory touched later; {@link instructionsLoadedGapNotice}'s `touchedDir`
+ * covers that half fresh on every call instead.
+ * @param {string} [sessionId]
+ * @returns {string}
+ */
+export function launchEmptyFile(sessionId?: string): string;
+/**
+ * Every file Claude Code loads as model context AT LAUNCH from `dir`: its own
+ * instruction files, its `.claude/` context tree, and the CLAUDE.md /
+ * CLAUDE.local.md of every directory above it. THE SSOT scan-invisible-chars.mjs
+ * reads too (re-exported there as `findInstructionFiles`) — sharing the one
+ * function is what keeps the SessionStart scan's targets and this module's
+ * launch-emptiness check from drifting into two different answers for "what
+ * loads at launch". See src/claude-context.mjs for why this is the shallow
+ * launch scope and not a whole-tree walk.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+export function launchInstructionFiles(dir: string): string[];
 /**
  * The one-time context line for a session where no InstructionsLoaded scan ran,
- * or null when the scan has been seen or the notice was already surfaced this
- * session.
- *
- * PURE: it does not record that the notice was handed out. The caller records
- * separately, once the notice has actually landed in a response — a deny
- * assembled after this call discards the notice, and a marker written here would
- * have burned the session's one chance to report the loss.
+ * or null when the scan has been seen, the notice already ran this session, or
+ * neither launch nor `touchedDir` could have fired the event.
  *
- * The loss it names is real and otherwise invisible: SessionStart scans the
- * instruction files that load at launch, and everything a subdirectory loads
- * later is scanned by the event. No scan, and nothing says so.
+ * PURE for the notice: nothing is recorded until the caller confirms it landed
+ * in a returned response. Launch-emptiness is cached once found — fixed for the
+ * session — but `touchedDir` is re-checked every call: the claim below is about
+ * SUBDIRECTORY files, so an empty launch must not silence a later call whose
+ * tool touched a directory that DOES carry real, unscanned content.
  *
- * The notice names the OBSERVABLE — no scan ran — and all three causes, because
- * the marker cannot tell them apart: a host that never wired the event to
- * scan-loaded-instructions, a Claude Code older than EVENT_MIN_CLI_VERSION, and
- * the hook switched off in AGENT_SANITIZER_DISABLED_HOOKS; asserting one sends a
- * reader who is in another to the wrong fix. The wiring cause leads because it is
- * the only one the reader can repair in this session, and nothing else reports it.
- * @param {string} [sessionId]  the harness's session identity, so the answer
- *   belongs to THIS session (see instructionsLoadedFile)
+ * 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 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
+ *   instructionsLoadedFile)
+ * @param {string} [dir]  the project root to check (injectable; defaults to
+ *   the real project)
+ * @param {string} [touchedDir]  this tool call's own target directory, when
+ *   known — re-checked every call, never cached
  * @returns {string | null}
  */
-export function instructionsLoadedGapNotice(sessionId?: string): string | null;
+export function instructionsLoadedGapNotice(sessionId?: string, dir?: string, touchedDir?: string): string | null;
 /**
  * Record that the gap notice above was surfaced, so it rides on ONE tool call
  * rather than every one — the per-call repeat is what trains a reader to skip it.

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

@@ -116,9 +116,9 @@ export function decodeRun(run: string): {
  * files load when a tool reads their directory, and scan-loaded-instructions
  * scans each one at that moment.
  *
- * The scope itself — which globs, and which directories the walk must prune — is
- * the library's (see src/claude-context.mjs for why it is imported relatively
- * rather than through the `agent-sanitizer` specifier the plugin bundle pins).
+ * lib/invisible-alert.mjs's `launchInstructionFiles` IS this function — shared
+ * so its InstructionsLoaded gap-notice check reads the identical target set
+ * this scan does, rather than a second enumeration that could drift.
  * @param {string} dir
  * @returns {string[]}
  */

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[];