agent-sanitizer 2.35.0 → 2.36.0

package/src/claude-context.mjs

@@ -1,27 +1,44 @@
 /**
- * WHICH files an agent loads as model context, as data: the glob set and the
+ * 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".
  *
- * This is the SINGLE SOURCE for that scope. It used to live inside
+ * TWO scopes live here, because Claude Code has two load moments and scanning
+ * them at one moment is what made session start unusable:
+ *
+ *   - {@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.
+ *   - {@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 (the 30-second session start
- * this whitelist exists to fix) or MISSES a context directory entirely, which
- * is a silent hole in the one scan standing between a poisoned instruction file
- * and a session that loads it.
+ * 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, dependency-free DATA module (like ./cf-charset.mjs) for
- * two reasons: `src/instructions.mjs` re-exports it as the library's public
- * door, and the hook imports it RELATIVELY — deliberately not through the
- * `agent-sanitizer` specifier the plugin bundle pins to a published engine.
- * This scope is hook POLICY, not engine behavior: it must ship and move with the
- * hook that walks it, or a plugin built against an older pin would prune the
- * wrong directories while believing it had scanned everything.
+ * 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.
  */
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 
 /**
  * The `.claude/` subdirectories whose markdown Claude Code loads as model
@@ -44,11 +61,33 @@ export const CLAUDE_CONTEXT_SUBDIRS = Object.freeze([
   "agents",
   "commands",
   "output-styles",
+  "rules",
   "skills",
 ]);
 
-// The glob patterns for one `.claude` tree at `prefix` (empty for the project
-// root, a doubled-star segment for nested ones): its top-level markdown, plus the
+/**
+ * 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.
+ */
+export const CLAUDE_MEMORY_FILES = Object.freeze([
+  "CLAUDE.md",
+  "CLAUDE.local.md",
+]);
+
+/**
+ * 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.
+ */
+export const CLAUDE_DIR_INSTRUCTION_FILES = Object.freeze([
+  ...CLAUDE_MEMORY_FILES,
+  "AGENTS.md",
+]);
+
+// 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.
 /** @param {string} prefix @returns {string[]} */
 function claudeDirPatterns(prefix) {
@@ -59,12 +98,16 @@ function claudeDirPatterns(prefix) {
 }
 
 /**
- * Every glob whose matches Claude Code loads as model context: the
- * per-directory instruction files (CLAUDE.md, CLAUDE.local.md, AGENTS.md) and
- * the whitelisted `.claude/` markdown. Claude Code loads these on entry to their
- * containing directory — a load path that bypasses the PostToolUse sanitizer —
- * so a payload planted in e.g. `packages/foo/CLAUDE.md` reaches the model
- * uncleaned unless something scans it here.
+ * 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.
+ *
+ * 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
+ * {@link CLAUDE_LAUNCH_GLOBS} for why, and for what does.
  *
  * `**` does not descend into dot directories, so NESTED `.claude/` trees need
  * their own doubled-star-prefixed patterns: without them a directory-scoped
@@ -77,12 +120,85 @@ function claudeDirPatterns(prefix) {
  * MATCH a bulk directory, but only pruning the WALK avoids paying to read it.
  */
 export const CLAUDE_INSTRUCTION_GLOBS = Object.freeze([
-  "**/CLAUDE.md",
-  "**/CLAUDE.local.md",
-  "**/AGENTS.md",
+  ...CLAUDE_DIR_INSTRUCTION_FILES.map((name) => `**/${name}`),
   ...claudeDirPatterns("**/"),
 ]);
 
+/**
+ * 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.
+ *
+ * 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
+ * session start pays a whole-tree walk (the entire home directory, when the
+ * session is launched there) to pre-scan files that mostly never load. The
+ * InstructionsLoaded hook scans each of those at the moment it loads instead —
+ * which is also the only moment that catches one created mid-session.
+ *
+ * Pair with {@link ancestorInstructionFiles} for the other half of the launch
+ * set, and with {@link excludeFromContextScan} to prune the `.claude` walk.
+ */
+export const CLAUDE_LAUNCH_GLOBS = Object.freeze([
+  ...CLAUDE_DIR_INSTRUCTION_FILES,
+  ...claudeDirPatterns(""),
+]);
+
+/**
+ * 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`.
+ *
+ * Returns CANDIDATES — absolute paths, existing or not, because this module
+ * touches no filesystem. Most parents of any directory hold neither file, so a
+ * caller that buckets its misses as "absent" should filter first: ~10 phantom
+ * entries per session would drown the one signal that bucket carries, a target
+ * that existed when the scan listed it and vanished before the read.
+ * @param {string} dir  the scan root; its own files are NOT included
+ * @returns {string[]}
+ */
+export function ancestorInstructionFiles(dir) {
+  /** @type {string[]} */
+  const files = [];
+  let current = resolve(dir);
+  // `dirname` is its own fixed point at the filesystem root, which is what ends
+  // the walk on every platform without spelling a root path here.
+  for (
+    let parent = dirname(current);
+    parent !== current;
+    parent = dirname(current)
+  ) {
+    current = parent;
+    for (const name of CLAUDE_MEMORY_FILES) files.push(join(current, name));
+  }
+  return files;
+}
+
+/**
+ * Whether `file` lives inside `dir`. Lexical, on already-absolute paths, and the
+ * bound on where an instruction-file scanner may REWRITE: a file above the scan
+ * root is shared with every other project beneath that root, so it is reported
+ * rather than silently edited. Both scanners ask this — one for a target it
+ * globbed, one for a path an event handed it — and a copy each is a copy that
+ * can drift into rewriting a file the other would not.
+ *
+ * Symlinks are deliberately not resolved: the guard that stops a link from
+ * redirecting the write has to live at the write itself (cleanFile opens
+ * O_NOFOLLOW), and resolving here would only duplicate it a check too early.
+ * @param {string} dir
+ * @param {string} file
+ * @returns {boolean}
+ */
+export function isInsideDir(dir, file) {
+  const rel = relative(dir, file);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
 /**
  * The one directory no instruction-file walk ever descends into. Its own
  * function so the name is spelled once, and so the two predicates that need it

package/src/instructions.mjs

@@ -13,8 +13,10 @@
  * instruction files live under (e.g. `["CLAUDE.md", "AGENTS.md",
  * ".claude/**\/*.md", "**\/SKILL.md"]`), so no agent's convention is baked in.
  * Claude Code's own convention is re-exported below
- * ({@link CLAUDE_INSTRUCTION_GLOBS} / {@link excludeFromContextScan}) so a
- * caller that wants it takes the SessionStart hook's exact scope rather than
+ * ({@link CLAUDE_INSTRUCTION_GLOBS} for a whole tree,
+ * {@link CLAUDE_LAUNCH_GLOBS} + {@link ancestorInstructionFiles} for just what a
+ * session loads at launch, {@link excludeFromContextScan} to prune either walk)
+ * so a caller that wants it takes the hooks' exact scope rather than
  * approximating it — see ./claude-context.mjs.
  */
 import {
@@ -48,8 +50,12 @@ import { excludeNodeModules } from "./claude-context.mjs";
 // makes `agent-sanitizer/instructions` the single place a CLI, a port or a fork
 // reads that scope from instead of re-spelling it.
 export {
+  ancestorInstructionFiles,
   CLAUDE_CONTEXT_SUBDIRS,
+  CLAUDE_DIR_INSTRUCTION_FILES,
   CLAUDE_INSTRUCTION_GLOBS,
+  CLAUDE_LAUNCH_GLOBS,
+  CLAUDE_MEMORY_FILES,
   excludeFromContextScan,
 } from "./claude-context.mjs";
 

package/types/claude-context.d.mts

@@ -1,3 +1,37 @@
+/**
+ * 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`.
+ *
+ * Returns CANDIDATES — absolute paths, existing or not, because this module
+ * touches no filesystem. Most parents of any directory hold neither file, so a
+ * caller that buckets its misses as "absent" should filter first: ~10 phantom
+ * entries per session would drown the one signal that bucket carries, a target
+ * that existed when the scan listed it and vanished before the read.
+ * @param {string} dir  the scan root; its own files are NOT included
+ * @returns {string[]}
+ */
+export function ancestorInstructionFiles(dir: string): string[];
+/**
+ * Whether `file` lives inside `dir`. Lexical, on already-absolute paths, and the
+ * bound on where an instruction-file scanner may REWRITE: a file above the scan
+ * root is shared with every other project beneath that root, so it is reported
+ * rather than silently edited. Both scanners ask this — one for a target it
+ * globbed, one for a path an event handed it — and a copy each is a copy that
+ * can drift into rewriting a file the other would not.
+ *
+ * Symlinks are deliberately not resolved: the guard that stops a link from
+ * redirecting the write has to live at the write itself (cleanFile opens
+ * O_NOFOLLOW), and resolving here would only duplicate it a check too early.
+ * @param {string} dir
+ * @param {string} file
+ * @returns {boolean}
+ */
+export function isInsideDir(dir: string, file: string): boolean;
 /**
  * The one directory no instruction-file walk ever descends into. Its own
  * function so the name is spelled once, and so the two predicates that need it
@@ -25,30 +59,6 @@ export function excludeNodeModules(entry: string): boolean;
  * @returns {boolean}
  */
 export function excludeFromContextScan(entry: string): boolean;
-/**
- * WHICH files an agent loads as model context, as data: the glob set and the
- * walk-pruning predicate that together define "everything Claude Code reads as
- * instructions, and nothing else".
- *
- * This is the SINGLE SOURCE for that scope. It used to live inside
- * `claude-hooks/scan-invisible-chars.mjs`, which meant the SessionStart hook
- * knew the answer and nobody else did: `src/instructions.mjs` takes
- * caller-supplied globs by design (no agent's convention is baked into the
- * engine), so the CLI, the Python port and every downstream fork spelled their
- * own approximation of this list — and an approximation that drifts either
- * scans bulk data that can never reach the model (the 30-second session start
- * this whitelist exists to fix) or MISSES a context directory entirely, which
- * is a silent hole in the one scan standing between a poisoned instruction file
- * and a session that loads it.
- *
- * It is a standalone, dependency-free DATA module (like ./cf-charset.mjs) for
- * two reasons: `src/instructions.mjs` re-exports it as the library's public
- * door, and the hook imports it RELATIVELY — deliberately not through the
- * `agent-sanitizer` specifier the plugin bundle pins to a published engine.
- * This scope is hook POLICY, not engine behavior: it must ship and move with the
- * hook that walks it, or a plugin built against an older pin would prune the
- * wrong directories while believing it had scanned everything.
- */
 /**
  * The `.claude/` subdirectories whose markdown Claude Code loads as model
  * context. This is a WHITELIST, and that is the point: `.claude/` is also where
@@ -68,12 +78,29 @@ export function excludeFromContextScan(entry: string): boolean;
  */
 export const CLAUDE_CONTEXT_SUBDIRS: readonly string[];
 /**
- * Every glob whose matches Claude Code loads as model context: the
- * per-directory instruction files (CLAUDE.md, CLAUDE.local.md, AGENTS.md) and
- * the whitelisted `.claude/` markdown. Claude Code loads these on entry to their
- * containing directory — a load path that bypasses the PostToolUse sanitizer —
- * so a payload planted in e.g. `packages/foo/CLAUDE.md` reaches the model
- * uncleaned unless something scans it here.
+ * 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.
+ */
+export const CLAUDE_MEMORY_FILES: 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.
+ */
+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.
+ *
+ * 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
+ * {@link CLAUDE_LAUNCH_GLOBS} for why, and for what does.
  *
  * `**` does not descend into dot directories, so NESTED `.claude/` trees need
  * their own doubled-star-prefixed patterns: without them a directory-scoped
@@ -86,3 +113,20 @@ export const CLAUDE_CONTEXT_SUBDIRS: readonly string[];
  * MATCH a bulk directory, but only pruning the WALK avoids paying to read it.
  */
 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.
+ *
+ * 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
+ * session start pays a whole-tree walk (the entire home directory, when the
+ * session is launched there) to pre-scan files that mostly never load. The
+ * InstructionsLoaded hook scans each of those at the moment it loads instead —
+ * which is also the only moment that catches one created mid-session.
+ *
+ * Pair with {@link ancestorInstructionFiles} for the other half of the launch
+ * set, and with {@link excludeFromContextScan} to prune the `.claude` walk.
+ */
+export const CLAUDE_LAUNCH_GLOBS: readonly string[];

package/types/claude-hooks/lib/hook-io.d.mts

@@ -425,6 +425,7 @@ export const HookEvent: Readonly<{
     POST_TOOL_USE: "PostToolUse";
     USER_PROMPT_SUBMIT: "UserPromptSubmit";
     SESSION_START: "SessionStart";
+    INSTRUCTIONS_LOADED: "InstructionsLoaded";
 }>;
 /** Claude Code permissionDecision verdicts. */
 export const PermissionDecision: Readonly<{

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

@@ -1,3 +1,66 @@
+/**
+ * Marker the InstructionsLoaded scanner writes on every fire, so another hook
+ * can tell whether that event is being scanned at all this session.
+ *
+ * Keyed by the SESSION, and never cleared at SessionStart like the alert pair
+ * above (a later session sweeps it once it is older than the TTL):
+ * nothing pins the order of SessionStart against the InstructionsLoaded events
+ * Claude Code fires for the files it loads at launch, so a clear could erase a
+ * marker written moments earlier and produce the notice on a session that IS
+ * covered. Session-keyed, the question each session asks is answered by that
+ * session's own file and no ordering matters. A host that exports no session id
+ * falls back to one shared name — where the marker can outlive its session, and
+ * a later session on a host that stopped emitting the event stays quiet.
+ * @param {string} [sessionId]
+ * @returns {string}
+ */
+export function instructionsLoadedFile(sessionId?: string): string;
+/**
+ * Companion marker: the notice below has been surfaced this session.
+ * @param {string} [sessionId]
+ * @returns {string}
+ */
+export function instructionsLoadedNoticeFile(sessionId?: string): string;
+/**
+ * Whether the InstructionsLoaded scanner has run this session — i.e. whether the
+ * lazily-loaded instruction files are being scanned at all. Ownership-validated
+ * like every other marker here: a co-tenant could otherwise plant the
+ * predictable path and suppress the notice below, which is the whole signal that
+ * nested files are going unscanned.
+ * @param {string} [sessionId]
+ * @returns {boolean}
+ */
+export function instructionsLoadedSeen(sessionId?: string): boolean;
+/**
+ * Record that the InstructionsLoaded scanner engaged. Symlink-safe presence
+ * write (see writeSentinelFile) at a predictable $TMPDIR path.
+ *
+ * The event fires once per instruction file loaded, so the already-recorded case
+ * returns without a write — and the stale-marker sweep rides the FIRST fire of a
+ * session, where one readdir is paid once rather than per loaded file.
+ * @param {string} [sessionId]
+ * @returns {void}
+ */
+export function recordInstructionsLoaded(sessionId?: string): void;
+/**
+ * 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. Records the notice as it hands it out, so it rides on ONE tool call
+ * rather than every one — the per-call repeat is what trains a reader to skip it.
+ *
+ * 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.
+ *
+ * The notice names the OBSERVABLE — no scan ran — and both of its causes, because
+ * the marker cannot tell a host that never emits the event from an operator who
+ * switched the hook off in AGENT_SANITIZER_DISABLED_HOOKS, and asserting the
+ * first would send an operator who chose the second to the wrong fix.
+ * @param {string} [sessionId]  the harness's session identity, so the answer
+ *   belongs to THIS session (see instructionsLoadedFile)
+ * @returns {string | null}
+ */
+export function instructionsLoadedGapNotice(sessionId?: string): string | null;
 /**
  * The alert findings if invisible-char injection was detected in instruction
  * files and couldn't be auto-cleaned, else null. ALERT_FILE lives at a predictable,
@@ -9,6 +72,21 @@
  * @returns {string | null}
  */
 export function invisibleCharAlert(): string | null;
+/**
+ * Add `text` to the alert the PreToolUse gate surfaces, keeping whatever is
+ * already there.
+ *
+ * Appending, where the SessionStart scanner TRUNCATES: that scan runs once and
+ * owns the session's reset, while an instruction file loaded mid-session is one
+ * more finding on top of whatever the launch scan left — a truncating write here
+ * would silently drop the earlier report. Symlink-refusing (writeFileNoFollow)
+ * and ownership-checked on read, because ALERT_FILE sits at a predictable,
+ * world-visible $TMPDIR path; a foreign or squatted file reads as empty and is
+ * replaced rather than appended to.
+ * @param {string} text
+ * @returns {void}
+ */
+export function appendAlert(text: string): void;
 /**
  * True once the gate has surfaced its blocking ask this session. Validates
  * ownership (not mere existence): a co-tenant could pre-create ALERT_ACK_FILE at its

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

@@ -0,0 +1,26 @@
+/**
+ * The operator-facing report for hidden-Unicode findings in instruction files.
+ *
+ * Its own module because two hooks render it — the SessionStart scan of the
+ * files that load at launch, and the InstructionsLoaded scan of every file
+ * loaded after that — and a second copy would drift in exactly the way that
+ * matters: the framing that keeps a decoded payload from reading as an
+ * instruction (see decodeRun's `untrusted data` prefix) is part of the report,
+ * not decoration on it.
+ */
+/**
+ * @param {Array<{
+ *   file: string,
+ *   findings: Array<{ line: number | null, charCount: number, method: string, decoded: string }>,
+ * }>} allFindings
+ * @returns {string}
+ */
+export function formatReport(allFindings: Array<{
+    file: string;
+    findings: Array<{
+        line: number | null;
+        charCount: number;
+        method: string;
+        decoded: string;
+    }>;
+}>): string;

package/types/claude-hooks/lib/trace.d.mts

@@ -47,6 +47,7 @@ export function bestEffortTrace(sink: TraceFn): TraceFn;
 export const TraceEvent: Readonly<{
     HOOK_RAN: "hook_ran";
     SCAN_INVISIBLE_CHARS_RAN: "scan_invisible_chars_ran";
+    SCAN_LOADED_INSTRUCTIONS_RAN: "scan_loaded_instructions_ran";
 }>;
 /**
  * The sink shape a hook emits through: the event name, its metadata fields, and

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

@@ -71,6 +71,7 @@ export function cliMain(opts?: {
 export function scanFile(filePath: string): ReturnType<typeof import("agent-sanitizer/instructions").scanText>;
 import { CLAUDE_CONTEXT_SUBDIRS } from "../src/claude-context.mjs";
 import { CLAUDE_INSTRUCTION_GLOBS } from "../src/claude-context.mjs";
+import { CLAUDE_LAUNCH_GLOBS } from "../src/claude-context.mjs";
 /**
  * The SSOT decoder, re-exported through a lazy-bound wrapper (the binding is
  * `let` and may be re-bound by the cold-start reload, so the export must read
@@ -86,18 +87,23 @@ export function decodeRun(run: string): {
     decoded: string;
 };
 /**
- * Every file under `dir` that Claude Code loads as model context: the
- * per-directory instruction files (CLAUDE.md, CLAUDE.local.md, AGENTS.md) and
- * the whitelisted `.claude/` markdown. Claude Code loads these on entry to their
- * containing directory — a load path that bypasses the PostToolUse sanitizer —
- * so a payload planted in e.g. `packages/foo/CLAUDE.md` reaches the model
- * uncleaned unless it is scanned here.
+ * Every file Claude Code loads as model context AT LAUNCH: `dir`'s own
+ * instruction files and its `.claude/` context tree, plus the CLAUDE.md /
+ * CLAUDE.local.md of every directory above it (loaded in full at launch, and
+ * until now never scanned by anything). These load before the session's first
+ * tool call — a path that bypasses the PostToolUse sanitizer — so a payload in
+ * one of them reaches the model uncleaned unless it is scanned here.
  *
- * The scope itself — which globs, and which directories the walk must prune —
- * is the library's {@link CLAUDE_INSTRUCTION_GLOBS} /
- * {@link excludeFromContextScan}, so this hook and every other consumer read one
- * list (see src/claude-context.mjs for why it is imported relatively rather than
- * through the `agent-sanitizer` specifier the plugin bundle pins).
+ * Bounded on purpose: one shallow glob plus a walk up the parent chain. The
+ * `**`-rooted scope ({@link CLAUDE_INSTRUCTION_GLOBS}) walks the entire tree
+ * below `dir`, which for a session launched in a home directory is ~100 seconds
+ * of blocked startup spent on files Claude Code does not load at launch. Those
+ * 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).
  * @param {string} dir
  * @returns {string[]}
  */
@@ -107,20 +113,4 @@ import { ALERT_ACK_FILE } from "./lib/invisible-alert.mjs";
 export let LONG_RUN_RE: RegExp;
 export let LONG_RUN_THRESHOLD: 10;
 export let TOTAL_INVISIBLE_THRESHOLD: 30;
-/**
- * @param {Array<{
- *   file: string,
- *   findings: Array<{ line: number | null, charCount: number, method: string, decoded: string }>,
- * }>} allFindings
- * @returns {string}
- */
-export function formatReport(allFindings: Array<{
-    file: string;
-    findings: Array<{
-        line: number | null;
-        charCount: number;
-        method: string;
-        decoded: string;
-    }>;
-}>): string;
-export { CLAUDE_CONTEXT_SUBDIRS, CLAUDE_INSTRUCTION_GLOBS, ALERT_FILE, ALERT_ACK_FILE };
+export { CLAUDE_CONTEXT_SUBDIRS, CLAUDE_INSTRUCTION_GLOBS, CLAUDE_LAUNCH_GLOBS, ALERT_FILE, ALERT_ACK_FILE };

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

@@ -0,0 +1,66 @@
+/**
+ * The payload fields this hook reads, validated. A payload missing either is
+ * harness-contract drift, not a clean file: reporting "no findings" for bytes we
+ * never saw is the one answer that must never be reachable, so this throws into
+ * the declared fault posture instead.
+ * @param {unknown} payload
+ * @returns {{ filePath: string, content: string, loadReason: string }}
+ */
+export function readLoadedFile(payload: unknown): {
+    filePath: string;
+    content: string;
+    loadReason: string;
+};
+/**
+ * Scan one loaded instruction file. Returns the report and what to do with it:
+ * `cleaned` says the payload is gone from disk, `alert` carries the text that
+ * must arm the PreToolUse gate (empty when the clean succeeded).
+ *
+ * The scan runs on the payload's bytes, never a re-read of the path: those are
+ * the bytes that reached the model, and a file rewritten between the load and
+ * this hook would otherwise be scanned in a state the model never saw.
+ * @param {{ filePath: string, content: string }} loaded
+ * @param {{ projectDir?: string, clean?: typeof cleanFile }} [opts]  injectable
+ *   for tests; the default cleans through the SSOT's guarded rewrite
+ * @returns {{ report: string, cleaned: boolean, reason: string | null } | null}
+ *   null when the file is clean
+ */
+export function scanLoadedFile({ filePath, content }: {
+    filePath: string;
+    content: string;
+}, { projectDir, clean }?: {
+    projectDir?: string;
+    clean?: typeof cleanFile;
+}): {
+    report: string;
+    cleaned: boolean;
+    reason: string | null;
+} | 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
+ * just read, and the user is told what changed on disk.
+ * @param {{ report: string, cleaned: boolean, reason: string | null }} result
+ * @param {string} filePath
+ * @returns {string}
+ */
+export function loadedFileMessage({ report, cleaned, reason }: {
+    report: string;
+    cleaned: boolean;
+    reason: string | null;
+}, filePath: string): string;
+/**
+ * The hook's CLI: read the event, scan the loaded bytes, clean and report.
+ * Exported so a bundle entry (which must claim the CLI slot before this module
+ * loads) can run the exact same wiring instead of duplicating it.
+ * @param {{ trace?: import("./lib/trace.mjs").TraceFn }} [opts]  `trace` is
+ *   where this scan announces engagement; a host with its own trace channel
+ *   passes its sink (see lib/trace.mjs)
+ * @returns {Promise<void>}
+ */
+export function cliMain({ trace: sink }?: {
+    trace?: import("./lib/trace.mjs").TraceFn;
+}): Promise<void>;
+declare const cleanFile: typeof import("agent-sanitizer/instructions").cleanFile;
+export const HOOK_NAME: "scan-loaded-instructions";
+export {};

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