agent-sanitizer 2.37.1 → 2.37.3

package/THREAT-MODEL.md

@@ -282,21 +282,49 @@ threshold. `cleanFile` strips the payload in place (Layer-1 strip), failing loud
 if a contaminated file cannot be rewritten.
 
 As Claude Code hooks the coverage is split to match how Claude Code loads these
-files. `scan-invisible-chars` (SessionStart) scans the launch set — the project
-root's own instruction files, the `CLAUDE.md` chain above it, and the root
-`.claude/` context subdirectories — and `scan-loaded-instructions`
-(InstructionsLoaded) scans every other instruction file — including the
-user-global `~/.claude` memory and rules, which load into every session on the
-machine — reading the one path the event names, at the moment it loads. The second cannot block: the file is already in
-context when it fires, so its neutralization is to strip the payload from disk
-(so no reload re-reads it) and tell the model to treat what it just read as
-untrusted data. Auto-cleaning is confined to `CLAUDE_PROJECT_DIR` in both — an
-ancestor file, or one under `~/.claude`, is shared with every other project on
-the machine, so it is reported through the cross-hook alert and never
-rewritten. A Claude Code build that emits
+files, and `src/claude-context.mjs` is where the split is defined: one table of
+context KINDS, each row naming what loads it and when.
+
+- **SessionStart** (`scan-invisible-chars`) scans the launch set — the project
+  root's own instruction files, the `CLAUDE.md` chain above it, and the root
+  `.claude/` context subdirectories. O(directory depth), not O(tree).
+- **InstructionsLoaded** (`scan-loaded-instructions`) scans each file the host
+  names as it loads it: the rows marked `eventNamed` — the `CLAUDE.md` family
+  and `.claude/rules` — wherever they sit, including the user-global `~/.claude`
+  memory and rules that load into every session on the machine.
+- **Everything else** — a nested `AGENTS.md`, a nested `.claude/` skill,
+  command or output-style — is covered on demand by the whole-tree
+  `CLAUDE_INSTRUCTION_GLOBS` scan (what the CLI walks) and by the PostToolUse
+  sanitizer when a tool reads one. Covering those eagerly means the whole-tree
+  walk at session start that this split exists to remove.
+
+The lazy half cannot block: the file is already in context when it fires, so its
+neutralization is to strip the payload from disk (so no reload re-reads it) and
+tell the model to treat what it just read as untrusted data. Auto-cleaning is
+confined to `CLAUDE_PROJECT_DIR` in both — an ancestor file, or one under
+`~/.claude`, is shared with every other project on the machine, so it is reported
+through the cross-hook alert and never rewritten. A Claude Code build that emits
 no `InstructionsLoaded` event loses the lazy half entirely; the PreToolUse gate
 says so once per session rather than leaving the gap silent.
 
+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
+`.claude/` subdirectory the whitelist does not carry (the launch scan prunes
+that directory, so every other file in it is unscanned), and a kind marked
+event-blind arriving through the event anyway (the lazy scan reaches further
+than the table, and this section, credit it with). Everything else is silent, in
+both directions: a path the table does not name — an `@import` of arbitrary
+markdown — reports nothing rather than guessing, and a directory it names as
+storage (`worktrees/`, `projects/`) reports nothing because whitelisting storage
+is the whole-tree walk again. Both observations also require a `load_reason` the
+host chose itself: an `@import` names a file the user's own markdown pointed at,
+which says nothing about what a scan would reach on its own. The
+notice never widens the scan on its own — one load cannot tell a context
+directory from an import target, and whitelisting the wrong one buys back the
+startup cost this split removed — so the whitelist stays hand-maintained and the
+notice's job is to put a stale entry in front of a person.
+
 ## User-prompt verdict
 
 `./prompt` classifies a submitted prompt as **pass / pass-with-note / block** on

package/claude-hooks/scan-loaded-instructions.mjs

@@ -2,17 +2,14 @@
  * InstructionsLoaded: scan an instruction file for hidden-Unicode injection at
  * the moment Claude Code loads it into context.
  *
- * This is the lazy half of the instruction-file scan. Claude Code loads a
- * subdirectory's CLAUDE.md (and a path-scoped rule, an `@import`, a
- * post-compaction reload) only when it needs it, and this event names the file
- * it just loaded — so the scan costs one read and one `scanText` on exactly the
- * file that entered context, with no glob and no walk. The SessionStart scan
- * covers what loads at launch from the project root and its parents; everything
- * else arrives here, including the user-global `~/.claude` memory and rules that
- * load into every session on the machine — a second root that would otherwise
- * need its own walk at every startup. Between them the coverage is wider than
- * the whole-tree walk they replace, which could not see a file created after it
- * ran, a rule outside the project, or the CLAUDE.md chain above it.
+ * This is the lazy half of the instruction-file scan: the event names the file
+ * it just loaded, so the scan costs one read and one `scanText` on exactly the
+ * file that entered context, with no glob and no walk. SessionStart covers what
+ * loads at launch from the project root and its parents; the kinds
+ * `src/claude-context.mjs` marks `eventNamed` arrive here, the user-global
+ * `~/.claude` memory and rules among them — a second root that would otherwise
+ * need its own walk at every startup. Naming a file is also the only way the
+ * host can prove that table wrong, which is what {@link scopeNotice} reports.
  *
  * The event CANNOT block: its exit code is ignored and the bytes are already in
  * context by the time it fires. What it can do is exactly what SessionStart does
@@ -42,7 +39,10 @@ import {
 import { bestEffortTrace, trace, TraceEvent } from "./lib/trace.mjs";
 import { reportSlowHook, startHookTimer } from "./lib/hook-timing.mjs";
 import { formatReport } from "./lib/invisible-report.mjs";
-import { isInsideDir } from "../src/claude-context.mjs";
+import {
+  contextScopeContradiction,
+  isInsideDir,
+} from "../src/claude-context.mjs";
 
 // The instruction-scanner SSOT, bound via lazyImport (see its doc for the
 // fail-OPEN hazard of a bare static npm import — here a loaded instruction file
@@ -119,8 +119,8 @@ export function readLoadedFile(payload) {
     );
   return {
     filePath,
-    // Metadata for the trace channel only, so an unknown/absent reason is a
-    // label, never a reason to skip the scan.
+    // Labelled, never missing: the trace channel and the scope notice both read
+    // it, and an unknown reason must not read as a reason to skip the scan.
     loadReason: typeof loadReason === "string" ? loadReason : "unknown",
   };
 }
@@ -175,6 +175,26 @@ export function scanLoadedFile(
   }
 }
 
+/**
+ * The operator-facing line for a file whose path contradicts the scope table, or
+ * null when it does not. This hook is where that check belongs and the only
+ * place it can run: the host naming a file as it loads is the one observation
+ * that can prove the SessionStart scan's scope wrong, and a scope that is wrong
+ * about a `.claude/` subdirectory is a launch scan with a hole in it.
+ *
+ * Separate from the finding channels below: this is a maintenance signal about
+ * THIS package, not a verdict about the file, so it never reaches the model and
+ * never arms the tool-call gate.
+ * @param {string} filePath
+ * @param {string} loadReason  why the host loaded it, which decides whether the
+ *   load is evidence about the scan's scope at all
+ * @returns {string | null}
+ */
+export function scopeNotice(filePath, loadReason) {
+  const stale = contextScopeContradiction(filePath, loadReason);
+  return stale && `${HOOK_NAME} scope notice: ${stale}.`;
+}
+
 /**
  * The operator- and model-facing text for a scanned file. Both channels carry
  * it: the bytes are already in context, so the model is told to distrust what it
@@ -221,6 +241,10 @@ export async function cliMain({ trace: sink = trace } = {}) {
     // before the payload's OWN fields are validated for the same reason.
     recordInstructionsLoaded(payload?.session_id);
     const loaded = readLoadedFile(payload);
+    // Before the scan: a file this hook cannot read still told us where the host
+    // loads context from, and that is the half the scope table needs.
+    const notice = scopeNotice(loaded.filePath, loaded.loadReason);
+    if (notice) process.stderr.write(notice + "\n");
     const result = scanLoadedFile(loaded.filePath);
     if (result === null) {
       emitTrace(TraceEvent.SCAN_LOADED_INSTRUCTIONS_RAN, {

package/package.json

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

@@ -1,94 +1,120 @@
 /**
- * WHICH files an agent loads as model context, as data: the glob sets and the
- * walk-pruning predicate that together define "everything Claude Code reads as
- * instructions, and nothing else".
- *
- * TWO scopes live here, because Claude Code has two load moments and scanning
- * them at one moment is what made session start unusable:
+ * WHICH files an agent loads as model context, as data: one table of context
+ * KINDS, and the views of it each load moment needs — a launch-time glob set, a
+ * whole-tree glob set, and the check that can tell the table it is wrong.
  *
  *   - {@link CLAUDE_LAUNCH_GLOBS} + {@link ancestorInstructionFiles} — what
- *     loads AT LAUNCH: the working directory's own instruction files, the same
- *     files in every directory above it, and the root `.claude` context tree.
- *     Rooted at the scan root, so it costs one shallow glob and a walk up the
- *     parent chain no matter how large the tree below is.
+ *     loads AT LAUNCH, costing a shallow glob and a walk up the parent chain
+ *     whatever the tree below holds.
  *   - {@link CLAUDE_INSTRUCTION_GLOBS} — every instruction file ANYWHERE in a
- *     tree, `**`-rooted. A library caller asking "scan this project" wants
- *     this; a SessionStart hook must not, because Claude Code loads a
- *     subdirectory's `CLAUDE.md` only when it reads a file in that
- *     subdirectory, and a launch in `$HOME` charges the whole home tree —
- *     ~100 seconds of blocked startup — for files that mostly never load.
- *     Those lazily-loaded files are scanned by the InstructionsLoaded hook, at
- *     the moment they load.
- *
- * This is the SINGLE SOURCE for both. 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 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 DATA module carrying no package dependency (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.
+ *     tree. A SessionStart hook must not walk this: a launch in `$HOME` charges
+ *     the whole home tree — ~100 seconds of blocked startup — for files that
+ *     mostly never load, and the InstructionsLoaded hook scans those as they do.
+ *   - {@link contextScopeContradiction} — what a file the host just loaded says
+ *     about this table, so a stale row surfaces as a notice, not as a hole.
+ *
+ * A standalone DATA module with no package dependency: `src/instructions.mjs`
+ * re-exports it as the library's public door, and the hooks import it RELATIVELY
+ * rather than through the `agent-sanitizer` specifier the plugin bundle pins to a
+ * published engine. This scope is hook POLICY, not engine behavior — it must move
+ * with the hook that walks it, or a plugin built against an older pin prunes the
+ * wrong directories while believing it scanned everything.
  */
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 
+// One row of the kind table. Both flags default to the conservative answer —
+// this kind is not on the ancestor chain, and no event announces it — so a row
+// added without them claims nothing the host has not been observed doing. Both
+// describe how a kind LOADS, so neither means anything on a `claude-bulk` row:
+// the readers below gate on shape before they read either flag.
 /**
- * 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.
+ * @param {"dir-file" | "claude-md" | "claude-subdir" | "claude-bulk"} shape
+ * @param {string} name  how a reader spells this kind
+ * @param {{ ancestorChain?: boolean, eventNamed?: boolean }} [flags]
  */
-export const CLAUDE_CONTEXT_SUBDIRS = Object.freeze([
-  "agents",
-  "commands",
-  "output-styles",
-  "rules",
-  "skills",
-]);
+function kind(shape, name, { ancestorChain = false, eventNamed = false } = {}) {
+  return Object.freeze({ shape, name, ancestorChain, eventNamed });
+}
 
 /**
- * Claude Code's own per-directory memory files. Their own list because the
- * parent-chain load ({@link ancestorInstructionFiles}) is Claude Code's rule and
- * covers exactly these two.
+ * Every kind of file an agent loads as model context — plus, as `claude-bulk`
+ * rows, the `.claude/` directories that hold anything BUT context, so a consumer
+ * filtering this table must filter on `shape` and never take it whole.
+ *
+ * Each row carries the two facts code branches on. `shape` says where the kind
+ * lives; `ancestorChain` says whether Claude Code also loads it from the
+ * directories ABOVE a scan root; `eventNamed` says whether `InstructionsLoaded`
+ * names it as it loads, the claim {@link contextScopeContradiction} checks.
+ *
+ * Shapes:
+ *   - `dir-file` — `name`, in any directory (`packages/foo/CLAUDE.md`).
+ *   - `claude-md` — top-level markdown directly under a `.claude/` directory.
+ *   - `claude-subdir` — `.claude/<name>/` and everything markdown below it.
+ *   - `claude-bulk` — `.claude/<name>/`, holding data that is not context.
+ *
+ * The `claude-subdir` rows are a WHITELIST: an unlisted context directory costs
+ * a scan nobody paid for anyway, while an unlisted BULK directory costs every
+ * future session its startup. The `claude-bulk` rows name the bulk directories
+ * this project has seen, so a load out of one asks for no whitelist entry.
  */
-export const CLAUDE_MEMORY_FILES = Object.freeze([
-  "CLAUDE.md",
-  "CLAUDE.local.md",
+export const CLAUDE_CONTEXT_KINDS = Object.freeze([
+  kind("dir-file", "CLAUDE.md", { ancestorChain: true, eventNamed: true }),
+  kind("dir-file", "CLAUDE.local.md", {
+    ancestorChain: true,
+    eventNamed: true,
+  }),
+  // AGENTS.md is the cross-agent convention Claude Code does not read itself,
+  // kept because this package guards agents generally. Off the ancestor chain
+  // for the same reason: that load is Claude Code's rule.
+  kind("dir-file", "AGENTS.md"),
+  kind("claude-md", ".claude/*.md"),
+  kind("claude-subdir", "agents"),
+  kind("claude-subdir", "commands"),
+  kind("claude-subdir", "output-styles"),
+  kind("claude-subdir", "rules", { eventNamed: true }),
+  kind("claude-subdir", "skills"),
+  // Repo checkouts and session transcripts: storage the host writes and reads
+  // back, so a load out of one is not evidence that the whitelist is short.
+  kind("claude-bulk", "worktrees"),
+  kind("claude-bulk", "projects"),
+  kind("claude-bulk", "todos"),
 ]);
 
+/** The rows of one shape, in table order. @param {string} shape */
+function kindsOfShape(shape) {
+  return CLAUDE_CONTEXT_KINDS.filter((row) => row.shape === shape);
+}
+
+// The names of `rows`, frozen: what a caller that wants one shape's spelling —
+// a glob builder, the parent-chain walk — reads off the table.
+/** @param {readonly {name: string}[]} rows @returns {readonly string[]} */
+function namesOf(rows) {
+  return Object.freeze(rows.map((row) => row.name));
+}
+
+/** The `.claude/` subdirectories whose markdown loads as model context. */
+export const CLAUDE_CONTEXT_SUBDIRS = namesOf(kindsOfShape("claude-subdir"));
+
+/** The `.claude/` subdirectories known to hold storage rather than context. */
+const CLAUDE_BULK_SUBDIRS = namesOf(kindsOfShape("claude-bulk"));
+
 /**
- * Every per-directory instruction file: Claude Code's memory files plus
- * `AGENTS.md`, the cross-agent convention Claude Code does not read itself, kept
- * because this package guards agents generally and the file is loaded as
- * instructions by the ones that do.
+ * Claude Code's own per-directory memory files: the kinds it loads from every
+ * directory above a scan root as well as from the root itself.
  */
-export const CLAUDE_DIR_INSTRUCTION_FILES = Object.freeze([
-  ...CLAUDE_MEMORY_FILES,
-  "AGENTS.md",
-]);
+export const CLAUDE_MEMORY_FILES = namesOf(
+  // Shape first: only a per-directory file can be walked up a parent chain, so
+  // no `.claude/` row can reach this list whatever its flags say.
+  CLAUDE_CONTEXT_KINDS.filter(
+    (row) => row.shape === "dir-file" && row.ancestorChain,
+  ),
+);
+
+/** Every per-directory instruction file, memory files and `AGENTS.md` alike. */
+export const CLAUDE_DIR_INSTRUCTION_FILES = namesOf(kindsOfShape("dir-file"));
 
 // The glob patterns for one `.claude` tree at `prefix` (empty for the scan root,
-// a doubled-star segment for nested ones): its top-level markdown, plus the
-// whitelisted context subdirectories. Built once, from the one list above.
+// a doubled-star segment for nested ones), built from the table's rows.
 /** @param {string} prefix @returns {string[]} */
 function claudeDirPatterns(prefix) {
   return [
@@ -98,12 +124,10 @@ function claudeDirPatterns(prefix) {
 }
 
 /**
- * Every glob whose matches Claude Code loads as model context ANYWHERE in a
- * tree: 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.
+ * Every glob whose matches an agent loads as model context ANYWHERE in a tree.
+ * 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.
  *
  * This is the WHOLE-TREE scope, for a caller scanning a project on demand (the
  * CLI, the Python port). It is not what a SessionStart hook walks — see
@@ -125,10 +149,8 @@ export const CLAUDE_INSTRUCTION_GLOBS = Object.freeze([
 ]);
 
 /**
- * Every glob whose matches Claude Code loads AT LAUNCH from the scan root
- * itself: the root's own instruction files and its `.claude` context tree. Same
- * patterns as {@link CLAUDE_INSTRUCTION_GLOBS} without the doubled-star root, built
- * from the same two lists so the pair cannot drift.
+ * Every glob whose matches load AT LAUNCH from the scan root itself: the root's
+ * own instruction files and its `.claude` context tree.
  *
  * Deliberately NOT recursive. A subdirectory's `CLAUDE.md` is loaded when Claude
  * Code reads a file in that subdirectory, not at launch, so globbing for it at
@@ -147,12 +169,9 @@ export const CLAUDE_LAUNCH_GLOBS = Object.freeze([
 
 /**
  * The instruction files Claude Code loads from the directories ABOVE `dir`:
- * walking up to the filesystem root, `CLAUDE.md` and `CLAUDE.local.md` in each
- * parent are loaded IN FULL at launch, so a payload planted in a parent
- * directory reaches the model exactly like one in the project's own file.
- *
- * `AGENTS.md` is absent by design: the parent-chain load is Claude Code's rule,
- * and Claude Code does not read `AGENTS.md`.
+ * walking up to the filesystem root, every `ancestorChain` kind in each parent
+ * is loaded IN FULL at launch, so a payload planted in a parent directory
+ * reaches the model exactly like one in the project's own file.
  *
  * Returns CANDIDATES — absolute paths, existing or not, because this module
  * touches no filesystem. Most parents of any directory hold neither file, so a
@@ -210,6 +229,21 @@ export function excludeNodeModules(entry) {
   return entry === "node_modules";
 }
 
+// The path segments below one `.claude` directory in `path`, or null when it
+// names none. Pruning asks whether the path is inside a bulk directory of the
+// tree being walked, so it takes the OUTERMOST — a `worktrees/` checkout carries
+// a whole `.claude` of its own, below which the prune must keep applying.
+// Naming a kind asks what the file IS, so it takes the INNERMOST tree.
+/** @param {string} path @param {"outermost" | "innermost"} which */
+function claudeTail(path, which) {
+  const parts = path.split(/[/\\]/);
+  const claudeIndex =
+    which === "outermost"
+      ? parts.indexOf(".claude")
+      : parts.lastIndexOf(".claude");
+  return claudeIndex === -1 ? null : parts.slice(claudeIndex + 1);
+}
+
 /**
  * Entries a context scan must not descend into or return: `node_modules`, and
  * every child of a `.claude` directory that is not whitelisted context.
@@ -217,10 +251,10 @@ export function excludeNodeModules(entry) {
  * 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).
+ * holding a few repo checkouts is walked in full on every session start, and a
+ * `.claude` NESTED inside a worktree is scanned as if it were this session's
+ * context: a doubled-star segment does cross into a dot directory when the
+ * pattern names one.
  *
  * 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
@@ -230,12 +264,95 @@ export function excludeNodeModules(entry) {
  */
 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;
+  const tail = claudeTail(entry, "outermost");
+  if (tail === null || 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]);
 }
+
+/**
+ * The kind `path` is an instance of, or null when this table claims none — an
+ * `@import` of an arbitrary markdown file, a source file, an unlisted `.claude`
+ * directory. Null is the honest answer for anything the table does not name, and
+ * callers must treat it as "no claim", never as "not context".
+ * @param {string} path  absolute or relative; only its segments are read
+ * @returns {(typeof CLAUDE_CONTEXT_KINDS)[number] | null}
+ */
+function classifyContextPath(path) {
+  const segments = path.split(/[/\\]/);
+  const name = segments[segments.length - 1];
+  // A CLAUDE.md is that kind wherever it sits, `.claude` tree or not — which is
+  // what keeps the ordinary nested-memory load from reading as evidence about
+  // the directory it happens to sit under.
+  const dirFile = kindsOfShape("dir-file").find((row) => row.name === name);
+  const tail = claudeTail(path, "innermost");
+  if (dirFile || tail === null) return dirFile ?? null;
+  if (tail.length === 1 && name.endsWith(".md"))
+    return kindsOfShape("claude-md")[0];
+  // Both directory shapes, so a bulk directory classifies as itself rather than
+  // falling through to the unlisted-directory report below.
+  const dirShapes = ["claude-subdir", "claude-bulk"];
+  return (
+    CLAUDE_CONTEXT_KINDS.find(
+      (row) => dirShapes.includes(row.shape) && row.name === tail[0],
+    ) ?? null
+  );
+}
+
+// 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.
+const HOST_CHOSEN_LOAD_REASONS = ["session_start", "nested_traversal"];
+
+/**
+ * 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
+ * observation that can prove the table wrong, and this is what it proves:
+ *
+ *   - a `.claude/` subdirectory outside {@link CLAUDE_CONTEXT_SUBDIRS} loading
+ *     as context means the launch scan skips that whole directory — the file
+ *     here was scanned, every other file in it was not;
+ *   - a kind the table marks `eventNamed: false` being named means the event's
+ *     coverage is wider than the docs claim, and the lazy scan reaches files
+ *     nothing was crediting it with.
+ *
+ * Both observations are about what the host reaches ON ITS OWN, so both require
+ * a host-chosen `loadReason`: an `@import` names a file the user's own markdown
+ * pointed at, and acting on it would either whitelist an import target or credit
+ * the event with a kind it reaches only when imported. An unrecognized reason is
+ * treated the same way, so this loses a notice rather than inventing one.
+ *
+ * A path the table does not name at all says nothing about the table either, so
+ * it returns null rather than guessing. A `claude-bulk` row is silent for the
+ * reason in reverse: the table already knows that directory is storage.
+ * @param {string} path  the path the host loaded
+ * @param {string} loadReason  the event's `load_reason`, or "unknown" when the
+ *   host sent none; required rather than defaulted, since every observation here
+ *   holds only for a load the host chose itself
+ * @returns {string | null} what is stale, phrased for whoever fixes the table
+ */
+export function contextScopeContradiction(path, loadReason) {
+  if (!HOST_CHOSEN_LOAD_REASONS.includes(loadReason)) return null;
+  const row = classifyContextPath(path);
+  if (row?.eventNamed || row?.shape === "claude-bulk") return null;
+  if (row)
+    return (
+      `InstructionsLoaded named ${row.name}, which CLAUDE_CONTEXT_KINDS records as a kind the ` +
+      "event never names: the lazy scan reaches further than this table, and the docs built " +
+      "on it, claim"
+    );
+  const tail = claudeTail(path, "innermost");
+  if (tail === null || tail.length < 2) return null;
+  // A `.claude` tree nested inside storage describes that checkout's own layout,
+  // not this project's: whitelisting a directory that exists only inside a
+  // pruned worktree adds nothing the launch scan would ever walk.
+  const outer = /** @type {string[]} */ (claudeTail(path, "outermost"));
+  if (CLAUDE_BULK_SUBDIRS.includes(outer[0])) return null;
+  return (
+    `.claude/${tail[0]}/ loaded as model context, and CLAUDE_CONTEXT_SUBDIRS does not list it: ` +
+    "the SessionStart scan prunes that directory, so every OTHER file in it goes unscanned. " +
+    "Add it there if it is context, not bulk data"
+  );
+}

package/src/instructions.mjs

@@ -51,11 +51,13 @@ import { excludeNodeModules } from "./claude-context.mjs";
 // reads that scope from instead of re-spelling it.
 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";
 

package/types/claude-context.d.mts

@@ -1,11 +1,8 @@
 /**
  * The instruction files Claude Code loads from the directories ABOVE `dir`:
- * walking up to the filesystem root, `CLAUDE.md` and `CLAUDE.local.md` in each
- * parent are loaded IN FULL at launch, so a payload planted in a parent
- * directory reaches the model exactly like one in the project's own file.
- *
- * `AGENTS.md` is absent by design: the parent-chain load is Claude Code's rule,
- * and Claude Code does not read `AGENTS.md`.
+ * walking up to the filesystem root, every `ancestorChain` kind in each parent
+ * is loaded IN FULL at launch, so a payload planted in a parent directory
+ * reaches the model exactly like one in the project's own file.
  *
  * Returns CANDIDATES — absolute paths, existing or not, because this module
  * touches no filesystem. Most parents of any directory hold neither file, so a
@@ -47,10 +44,10 @@ export function excludeNodeModules(entry: string): boolean;
  * 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).
+ * holding a few repo checkouts is walked in full on every session start, and a
+ * `.claude` NESTED inside a worktree is scanned as if it were this session's
+ * context: a doubled-star segment does cross into a dot directory when the
+ * pattern names one.
  *
  * 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
@@ -60,43 +57,74 @@ export function excludeNodeModules(entry: string): boolean;
  */
 export function excludeFromContextScan(entry: string): boolean;
 /**
- * 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.
+ * 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
+ * observation that can prove the table wrong, and this is what it proves:
+ *
+ *   - a `.claude/` subdirectory outside {@link CLAUDE_CONTEXT_SUBDIRS} loading
+ *     as context means the launch scan skips that whole directory — the file
+ *     here was scanned, every other file in it was not;
+ *   - a kind the table marks `eventNamed: false` being named means the event's
+ *     coverage is wider than the docs claim, and the lazy scan reaches files
+ *     nothing was crediting it with.
+ *
+ * Both observations are about what the host reaches ON ITS OWN, so both require
+ * a host-chosen `loadReason`: an `@import` names a file the user's own markdown
+ * pointed at, and acting on it would either whitelist an import target or credit
+ * the event with a kind it reaches only when imported. An unrecognized reason is
+ * treated the same way, so this loses a notice rather than inventing one.
  *
- * 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.
+ * A path the table does not name at all says nothing about the table either, so
+ * it returns null rather than guessing. A `claude-bulk` row is silent for the
+ * reason in reverse: the table already knows that directory is storage.
+ * @param {string} path  the path the host loaded
+ * @param {string} loadReason  the event's `load_reason`, or "unknown" when the
+ *   host sent none; required rather than defaulted, since every observation here
+ *   holds only for a load the host chose itself
+ * @returns {string | null} what is stale, phrased for whoever fixes the table
  */
-export const CLAUDE_CONTEXT_SUBDIRS: readonly string[];
+export function contextScopeContradiction(path: string, loadReason: string): string | null;
 /**
- * Claude Code's own per-directory memory files. Their own list because the
- * parent-chain load ({@link ancestorInstructionFiles}) is Claude Code's rule and
- * covers exactly these two.
+ * Every kind of file an agent loads as model context — plus, as `claude-bulk`
+ * rows, the `.claude/` directories that hold anything BUT context, so a consumer
+ * filtering this table must filter on `shape` and never take it whole.
+ *
+ * Each row carries the two facts code branches on. `shape` says where the kind
+ * lives; `ancestorChain` says whether Claude Code also loads it from the
+ * directories ABOVE a scan root; `eventNamed` says whether `InstructionsLoaded`
+ * names it as it loads, the claim {@link contextScopeContradiction} checks.
+ *
+ * Shapes:
+ *   - `dir-file` — `name`, in any directory (`packages/foo/CLAUDE.md`).
+ *   - `claude-md` — top-level markdown directly under a `.claude/` directory.
+ *   - `claude-subdir` — `.claude/<name>/` and everything markdown below it.
+ *   - `claude-bulk` — `.claude/<name>/`, holding data that is not context.
+ *
+ * The `claude-subdir` rows are a WHITELIST: an unlisted context directory costs
+ * a scan nobody paid for anyway, while an unlisted BULK directory costs every
+ * future session its startup. The `claude-bulk` rows name the bulk directories
+ * this project has seen, so a load out of one asks for no whitelist entry.
  */
-export const CLAUDE_MEMORY_FILES: readonly string[];
+export const CLAUDE_CONTEXT_KINDS: readonly Readonly<{
+    shape: "dir-file" | "claude-md" | "claude-subdir" | "claude-bulk";
+    name: string;
+    ancestorChain: boolean;
+    eventNamed: boolean;
+}>[];
+/** The `.claude/` subdirectories whose markdown loads as model context. */
+export const CLAUDE_CONTEXT_SUBDIRS: readonly string[];
 /**
- * Every per-directory instruction file: Claude Code's memory files plus
- * `AGENTS.md`, the cross-agent convention Claude Code does not read itself, kept
- * because this package guards agents generally and the file is loaded as
- * instructions by the ones that do.
+ * Claude Code's own per-directory memory files: the kinds it loads from every
+ * directory above a scan root as well as from the root itself.
  */
+export const CLAUDE_MEMORY_FILES: readonly string[];
+/** Every per-directory instruction file, memory files and `AGENTS.md` alike. */
 export const CLAUDE_DIR_INSTRUCTION_FILES: readonly string[];
 /**
- * Every glob whose matches Claude Code loads as model context ANYWHERE in a
- * tree: 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.
+ * Every glob whose matches an agent loads as model context ANYWHERE in a tree.
+ * 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.
  *
  * This is the WHOLE-TREE scope, for a caller scanning a project on demand (the
  * CLI, the Python port). It is not what a SessionStart hook walks — see
@@ -114,10 +142,8 @@ export const CLAUDE_DIR_INSTRUCTION_FILES: readonly string[];
  */
 export const CLAUDE_INSTRUCTION_GLOBS: readonly string[];
 /**
- * Every glob whose matches Claude Code loads AT LAUNCH from the scan root
- * itself: the root's own instruction files and its `.claude` context tree. Same
- * patterns as {@link CLAUDE_INSTRUCTION_GLOBS} without the doubled-star root, built
- * from the same two lists so the pair cannot drift.
+ * Every glob whose matches load AT LAUNCH from the scan root itself: the root's
+ * own instruction files and its `.claude` context tree.
  *
  * Deliberately NOT recursive. A subdirectory's `CLAUDE.md` is loaded when Claude
  * Code reads a file in that subdirectory, not at launch, so globbing for it at

package/types/claude-hooks/scan-loaded-instructions.d.mts

@@ -38,6 +38,22 @@ export function scanLoadedFile(filePath: string, { projectDir, clean, read }?: {
     cleaned: boolean;
     reason: string | null;
 } | null;
+/**
+ * The operator-facing line for a file whose path contradicts the scope table, or
+ * null when it does not. This hook is where that check belongs and the only
+ * place it can run: the host naming a file as it loads is the one observation
+ * that can prove the SessionStart scan's scope wrong, and a scope that is wrong
+ * about a `.claude/` subdirectory is a launch scan with a hole in it.
+ *
+ * Separate from the finding channels below: this is a maintenance signal about
+ * THIS package, not a verdict about the file, so it never reaches the model and
+ * never arms the tool-call gate.
+ * @param {string} filePath
+ * @param {string} loadReason  why the host loaded it, which decides whether the
+ *   load is evidence about the scan's scope at all
+ * @returns {string | null}
+ */
+export function scopeNotice(filePath: string, loadReason: string): string | null;
 /**
  * The operator- and model-facing text for a scanned file. Both channels carry
  * it: the bytes are already in context, so the model is told to distrust what it

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_SUBDIRS, CLAUDE_DIR_INSTRUCTION_FILES, CLAUDE_INSTRUCTION_GLOBS, CLAUDE_LAUNCH_GLOBS, CLAUDE_MEMORY_FILES, excludeFromContextScan } from "./claude-context.mjs";
+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";

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

@@ -1,11 +1,8 @@
 /**
  * The instruction files Claude Code loads from the directories ABOVE `dir`:
- * walking up to the filesystem root, `CLAUDE.md` and `CLAUDE.local.md` in each
- * parent are loaded IN FULL at launch, so a payload planted in a parent
- * directory reaches the model exactly like one in the project's own file.
- *
- * `AGENTS.md` is absent by design: the parent-chain load is Claude Code's rule,
- * and Claude Code does not read `AGENTS.md`.
+ * walking up to the filesystem root, every `ancestorChain` kind in each parent
+ * is loaded IN FULL at launch, so a payload planted in a parent directory
+ * reaches the model exactly like one in the project's own file.
  *
  * Returns CANDIDATES — absolute paths, existing or not, because this module
  * touches no filesystem. Most parents of any directory hold neither file, so a
@@ -47,10 +44,10 @@ export function excludeNodeModules(entry: string): boolean;
  * 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).
+ * holding a few repo checkouts is walked in full on every session start, and a
+ * `.claude` NESTED inside a worktree is scanned as if it were this session's
+ * context: a doubled-star segment does cross into a dot directory when the
+ * pattern names one.
  *
  * 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
@@ -60,43 +57,74 @@ export function excludeNodeModules(entry: string): boolean;
  */
 export function excludeFromContextScan(entry: string): boolean;
 /**
- * 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.
+ * 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
+ * observation that can prove the table wrong, and this is what it proves:
+ *
+ *   - a `.claude/` subdirectory outside {@link CLAUDE_CONTEXT_SUBDIRS} loading
+ *     as context means the launch scan skips that whole directory — the file
+ *     here was scanned, every other file in it was not;
+ *   - a kind the table marks `eventNamed: false` being named means the event's
+ *     coverage is wider than the docs claim, and the lazy scan reaches files
+ *     nothing was crediting it with.
+ *
+ * Both observations are about what the host reaches ON ITS OWN, so both require
+ * a host-chosen `loadReason`: an `@import` names a file the user's own markdown
+ * pointed at, and acting on it would either whitelist an import target or credit
+ * the event with a kind it reaches only when imported. An unrecognized reason is
+ * treated the same way, so this loses a notice rather than inventing one.
  *
- * 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.
+ * A path the table does not name at all says nothing about the table either, so
+ * it returns null rather than guessing. A `claude-bulk` row is silent for the
+ * reason in reverse: the table already knows that directory is storage.
+ * @param {string} path  the path the host loaded
+ * @param {string} loadReason  the event's `load_reason`, or "unknown" when the
+ *   host sent none; required rather than defaulted, since every observation here
+ *   holds only for a load the host chose itself
+ * @returns {string | null} what is stale, phrased for whoever fixes the table
  */
-export const CLAUDE_CONTEXT_SUBDIRS: readonly string[];
+export function contextScopeContradiction(path: string, loadReason: string): string | null;
 /**
- * Claude Code's own per-directory memory files. Their own list because the
- * parent-chain load ({@link ancestorInstructionFiles}) is Claude Code's rule and
- * covers exactly these two.
+ * Every kind of file an agent loads as model context — plus, as `claude-bulk`
+ * rows, the `.claude/` directories that hold anything BUT context, so a consumer
+ * filtering this table must filter on `shape` and never take it whole.
+ *
+ * Each row carries the two facts code branches on. `shape` says where the kind
+ * lives; `ancestorChain` says whether Claude Code also loads it from the
+ * directories ABOVE a scan root; `eventNamed` says whether `InstructionsLoaded`
+ * names it as it loads, the claim {@link contextScopeContradiction} checks.
+ *
+ * Shapes:
+ *   - `dir-file` — `name`, in any directory (`packages/foo/CLAUDE.md`).
+ *   - `claude-md` — top-level markdown directly under a `.claude/` directory.
+ *   - `claude-subdir` — `.claude/<name>/` and everything markdown below it.
+ *   - `claude-bulk` — `.claude/<name>/`, holding data that is not context.
+ *
+ * The `claude-subdir` rows are a WHITELIST: an unlisted context directory costs
+ * a scan nobody paid for anyway, while an unlisted BULK directory costs every
+ * future session its startup. The `claude-bulk` rows name the bulk directories
+ * this project has seen, so a load out of one asks for no whitelist entry.
  */
-export const CLAUDE_MEMORY_FILES: readonly string[];
+export const CLAUDE_CONTEXT_KINDS: readonly Readonly<{
+    shape: "dir-file" | "claude-md" | "claude-subdir" | "claude-bulk";
+    name: string;
+    ancestorChain: boolean;
+    eventNamed: boolean;
+}>[];
+/** The `.claude/` subdirectories whose markdown loads as model context. */
+export const CLAUDE_CONTEXT_SUBDIRS: readonly string[];
 /**
- * Every per-directory instruction file: Claude Code's memory files plus
- * `AGENTS.md`, the cross-agent convention Claude Code does not read itself, kept
- * because this package guards agents generally and the file is loaded as
- * instructions by the ones that do.
+ * Claude Code's own per-directory memory files: the kinds it loads from every
+ * directory above a scan root as well as from the root itself.
  */
+export const CLAUDE_MEMORY_FILES: readonly string[];
+/** Every per-directory instruction file, memory files and `AGENTS.md` alike. */
 export const CLAUDE_DIR_INSTRUCTION_FILES: readonly string[];
 /**
- * Every glob whose matches Claude Code loads as model context ANYWHERE in a
- * tree: 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.
+ * Every glob whose matches an agent loads as model context ANYWHERE in a tree.
+ * 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.
  *
  * This is the WHOLE-TREE scope, for a caller scanning a project on demand (the
  * CLI, the Python port). It is not what a SessionStart hook walks — see
@@ -114,10 +142,8 @@ export const CLAUDE_DIR_INSTRUCTION_FILES: readonly string[];
  */
 export const CLAUDE_INSTRUCTION_GLOBS: readonly string[];
 /**
- * Every glob whose matches Claude Code loads AT LAUNCH from the scan root
- * itself: the root's own instruction files and its `.claude` context tree. Same
- * patterns as {@link CLAUDE_INSTRUCTION_GLOBS} without the doubled-star root, built
- * from the same two lists so the pair cannot drift.
+ * Every glob whose matches load AT LAUNCH from the scan root itself: the root's
+ * own instruction files and its `.claude` context tree.
  *
  * Deliberately NOT recursive. A subdirectory's `CLAUDE.md` is loaded when Claude
  * Code reads a file in that subdirectory, not at launch, so globbing for it at