agent-sanitizer 2.35.0 → 2.36.0

package/types/src/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[];