agent-sanitizer 2.57.4 → 2.58.0

package/README.md

@@ -460,9 +460,16 @@ normalizeConfusables(
   { scan: (t) => myHomoglyphEngine.scan(t) }, // override the default namespace-guard engine
 );
 
-import { scanInstructionFiles, cleanFile } from "agent-sanitizer/instructions";
+import {
+  contextScanExclude,
+  scanInstructionFiles,
+  cleanFile,
+} from "agent-sanitizer/instructions";
 const findings = scanInstructionFiles(["CLAUDE.md", "**/SKILL.md"], {
   cwd: projectDir,
+  // Skip what git says is not this checkout's source: ignored directories and
+  // nested worktrees. Ignored FILES (CLAUDE.local.md) are still scanned.
+  exclude: contextScanExclude(projectDir),
 });
 for (const { file } of findings) cleanFile(`${projectDir}/${file}`);
 
@@ -542,6 +549,9 @@ verdicts through the bundled CLI, so no second implementation can drift. An `op`
 field selects the entry point (default `sanitize`); the self-contained ones —
 `sanitizeText`, `classifyPrompt`, `scanInstructionFiles`, `cleanFile` — are
 bridged, while entry points taking a JS callback have no wire form. Bridged
+`scanInstructionFiles` walks the whole-tree scope: it skips `node_modules`, the
+directories git ignores wholesale and any nested worktree, since a finding from
+one of those names a file the scanned checkout does not own. Bridged
 `sanitizeText` runs Layers 1–3 only: no secret redaction (Layer 4), no injection
 filtering (Layer 5), and—since the bridge never wires `sgrCarveOut`—Layer 1's
 findings are never downgraded, so `notes` carries only the Layer-2/3 tiers and

package/THREAT-MODEL.md

@@ -427,6 +427,24 @@ context KINDS, each row naming what loads it and when.
   sanitizer when a tool reads one. Covering those eagerly means the whole-tree
   walk at session start that this split exists to remove.
 
+Both walks skip what git says is not the checkout's own source: `node_modules`,
+the non-context children of a `.claude/` directory, and every nested worktree
+(`contextScanExclude`, `src/repo-scope.mjs`). The whole-tree walk also skips the
+directories git ignores wholesale; **the launch walk deliberately does not**.
+`.gitignore` is repo-controlled, so honouring it there would let a repo hide a
+planted `.claude/skills/…/SKILL.md` from the one scan that runs before the first
+tool call — whereas anything the whole-tree walk skips is still scanned by
+`scan-loaded-instructions` at the moment the host loads it. Ignored FILES are
+never pruned in either walk: `CLAUDE.local.md` is gitignored by convention and
+loads as model context at launch.
+
+Asking git costs a subprocess inside the directory being scanned, and that
+directory is the untrusted party here — git reads its `.git/config`, and
+`ls-files` runs `core.fsmonitor` as a command to refresh the index, which
+`safe.directory` does not cover for a planted config owned by the same uid.
+`runGit` pins `core.fsmonitor=false` on every query so a scan of a hostile
+checkout cannot become code execution.
+
 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

package/bin/sanitize-cli.mjs

@@ -18,6 +18,8 @@
  *   sanitizeText       { text, html?, exfilScan?, flagDigestValues? } -> { cleaned, warnings, notes, modified, sgrNote }
  *   classifyPrompt     { text }                    -> { action, reason? }
  *   scanInstructionFiles { globs, cwd? }           -> { findings: [{ file, findings }] }
+ *     Skips `node_modules`, the directories git ignores wholesale, and any
+ *     nested worktree — none of them is the scanned checkout's own source.
  *   cleanFile          { path }                    -> { changed }
  *
  * A failure response is `{ "error": string }`. Two modes, same binary:
@@ -170,9 +172,18 @@ export const OPS = {
     // (matches the fail-loud contract every other typed field here follows).
     if ("cwd" in req && typeof req.cwd !== "string")
       throw new Error("request.cwd must be a string");
-    const { scanInstructionFiles } = await import("../src/instructions.mjs");
-    const opts = typeof req.cwd === "string" ? { cwd: req.cwd } : {};
-    return { findings: scanInstructionFiles(globs, opts) };
+    const { contextScanExclude, scanInstructionFiles } =
+      await import("../src/instructions.mjs");
+    const cwd = typeof req.cwd === "string" ? req.cwd : process.cwd();
+    // Whole-tree scope: a gitignored build directory and a nested worktree are
+    // not this checkout's source, so a finding from one names a file the caller
+    // does not own — and `cleanFile` would rewrite it.
+    return {
+      findings: scanInstructionFiles(globs, {
+        cwd,
+        exclude: contextScanExclude(cwd),
+      }),
+    };
   },
 
   /** @param {Record<string, unknown>} req */

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

@@ -12,7 +12,6 @@
  */
 import {
   existsSync,
-  globSync,
   lstatSync,
   mkdirSync,
   readdirSync,
@@ -35,16 +34,17 @@ import {
   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.
+// launch scope is hook POLICY (see src/claude-context.mjs). Sharing the walk
+// itself is what keeps the prune's entry spelling from having two definitions —
+// an exclude predicate is only as precise as the entries it is handed.
 import {
   ancestorInstructionFiles,
   announcedByInstructionsLoaded,
   CLAUDE_LAUNCH_GLOBS,
-  excludeFromContextScan,
   USER_GLOBAL_EVENT_NAMED_GLOBS,
 } from "../../src/claude-context.mjs";
+import { contextScanExclude } from "../../src/repo-scope.mjs";
+import { walkContextGlobs } from "../../src/instructions.mjs";
 
 // Layer-1 scrubber for the untrusted alert-store contents the gate splices into a
 // permissionDecisionReason. The WELL-FORMED composition, not the bare applyLayer1:
@@ -359,10 +359,14 @@ export function launchEmptyFile(sessionId) {
  */
 export function launchInstructionFiles(dir) {
   return [
-    ...globSync([...CLAUDE_LAUNCH_GLOBS], {
-      cwd: dir,
-      exclude: excludeFromContextScan,
-    }).map((name) => join(dir, name)),
+    // This walk is the only thing covering launch-time ingress — nothing
+    // rescans what it skips — so it takes the posture that refuses to let a
+    // repo's own `.gitignore` narrow it (see contextScanExclude).
+    ...walkContextGlobs(
+      [...CLAUDE_LAUNCH_GLOBS],
+      dir,
+      contextScanExclude(dir, { ignoredDirs: false }),
+    ),
     // 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
@@ -435,10 +439,11 @@ function announcedLaunchFiles(dir) {
 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)),
+    walkContextGlobs(
+      [...USER_GLOBAL_EVENT_NAMED_GLOBS],
+      configDir,
+      contextScanExclude(configDir, { ignoredDirs: false }),
+    ),
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.57.4",
+  "version": "2.58.0",
   "description": "Defend an agent against hidden-content injection: strip payload-capable invisible Unicode and ANSI, splice out human-invisible HTML, and flag data-exfil URLs in untrusted text before any model sees it.",
   "type": "module",
   "repository": {

package/src/claude-context.mjs

@@ -222,11 +222,15 @@ export function isInsideDir(dir, file) {
  * 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
  * (a plain glob walk, and {@link excludeFromContextScan}) cannot disagree.
- * @param {string} entry  a bare entry name or a path relative to the scan root
+ *
+ * The LAST segment is what it reads: a dependency tree nested under a workspace
+ * package is the same dependency tree, and an entry naming one arrives as the
+ * path `packages/a/node_modules`, never as a bare name.
+ * @param {string} entry  a path relative to the scan root, `/`-separated
  * @returns {boolean}
  */
 export function excludeNodeModules(entry) {
-  return entry === "node_modules";
+  return entry.split(/[/\\]/).at(-1) === "node_modules";
 }
 
 // The path segments below one `.claude` directory in `path`, or null when it
@@ -256,10 +260,10 @@ function claudeTail(path, which) {
  * 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
- * against `node_modules`.
- * @param {string} entry  a bare entry name or a path relative to the scan root
+ * Entries are paths relative to the scan root, so a top-level one is a bare
+ * name: it carries no `.claude` context and is judged only against
+ * `node_modules`.
+ * @param {string} entry  a path relative to the scan root, `/`-separated
  * @returns {boolean}
  */
 export function excludeFromContextScan(entry) {

package/src/instructions.mjs

@@ -15,7 +15,8 @@
  * Claude Code's own convention is re-exported below
  * ({@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)
+ * session loads at launch, {@link contextScanExclude} to prune either walk down
+ * to what git says is this checkout's own source)
  * so a caller that wants it takes the hooks' exact scope rather than
  * approximating it — see ./claude-context.mjs.
  */
@@ -63,6 +64,12 @@ export {
   USER_GLOBAL_EVENT_NAMED_GLOBS,
 } from "./claude-context.mjs";
 
+// The prune a caller should actually pass: the static scope above, plus the
+// directories git says are not this checkout's source. `excludeFromContextScan`
+// stays exported as the static half alone, for a caller with no repository to
+// ask.
+export { contextScanExclude } from "./repo-scope.mjs";
+
 // Prefix on any decoded tag-character payload. The decoded text is
 // attacker-controlled and flows into the scan report, which itself reaches model
 // context — so it must be framed as DATA, never re-presented as a live
@@ -336,6 +343,37 @@ function keepContained(absPath, realRoot, literalRoot, pattern) {
   );
 }
 
+/**
+ * Every `globs` match under `cwd`, as an absolute path, with `node_modules` and
+ * whatever `exclude` rejects pruned from the WALK rather than filtered from its
+ * results — which is where a wide glob's cost actually is.
+ *
+ * `withFileTypes` is what makes the prune ANSWERABLE. Without it the walker
+ * calls `exclude` once with an entry's bare name and again with its
+ * root-relative path, so a predicate holding `build` cannot tell a top-level
+ * `build/` from a tracked `src/build/` and prunes both; under an absolute
+ * pattern it is handed absolute paths and matches neither. A Dirent carries an
+ * absolute `parentPath`, which normalizes to exactly one root-relative,
+ * `/`-separated entry per walked directory whatever shape the pattern has.
+ * @param {string[]} globs
+ * @param {string} cwd
+ * @param {(entry: string) => boolean} [exclude]
+ * @returns {string[]} absolute paths, one match per element
+ */
+export function walkContextGlobs(globs, cwd, exclude) {
+  const root = resolve(cwd);
+  /** @param {import("node:fs").Dirent} dirent @returns {string} */
+  const absolute = (dirent) => join(dirent.parentPath, dirent.name);
+  return globSync(globs, {
+    cwd,
+    withFileTypes: true,
+    exclude: (dirent) => {
+      const entry = relative(root, absolute(dirent)).split(sep).join("/");
+      return excludeNodeModules(entry) || (exclude?.(entry) ?? false);
+    },
+  }).map(absolute);
+}
+
 /**
  * Expand `globs` (relative to `cwd`) to absolute file paths, skipping
  * `node_modules`. The glob set is the caller's instruction-file convention.
@@ -349,11 +387,11 @@ function keepContained(absPath, realRoot, literalRoot, pattern) {
  * tree), is SKIPPED, so one bad symlink never aborts scanning the rest of the
  * project.
  *
- * `exclude` prunes the WALK, which is where a wide glob's cost actually is —
- * a pattern that merely fails to match a bulk directory still pays to read it.
- * It is composed with, never replaces, the unconditional `node_modules` prune:
- * a caller narrowing the scan must not be able to widen it into a dependency
- * tree. Pass {@link excludeFromContextScan} to take Claude Code's own scope.
+ * `exclude` prunes the walk via {@link walkContextGlobs}, so it is handed one
+ * root-relative, `/`-separated path per entry. It is composed with, never
+ * replaces, the unconditional `node_modules` prune: a caller narrowing the scan
+ * must not be able to widen it into a dependency tree. Pass
+ * {@link excludeFromContextScan} to take Claude Code's own scope.
  * @param {string[]} globs
  * @param {{ cwd?: string, exclude?: (entry: string) => boolean }} [options]
  * @returns {string[]}
@@ -365,19 +403,12 @@ export function findInstructionFiles(
   const literalRoot = resolve(cwd);
   const realRoot = realpathSync(literalRoot);
   const seen = new Set();
+  // One pattern at a time, so a containment failure can name the glob that
+  // reached outside the tree.
   for (const pattern of globs)
-    for (const name of globSync(pattern, {
-      cwd,
-      exclude: (entry) =>
-        excludeNodeModules(entry) || (exclude?.(entry) ?? false),
-    })) {
-      // globSync returns absolute paths verbatim for an absolute pattern and
-      // cwd-relative names otherwise; joining an already-absolute name would
-      // double the prefix into a nonexistent path (the absolute-glob miss bug).
-      const absPath = isAbsolute(name) ? name : join(cwd, name);
+    for (const absPath of walkContextGlobs([pattern], cwd, exclude))
       if (keepContained(absPath, realRoot, literalRoot, pattern))
         seen.add(absPath);
-    }
   return [...seen];
 }
 

package/src/repo-scope.mjs

@@ -0,0 +1,240 @@
+/**
+ * What git says is NOT this checkout's own source, as a prune set for an
+ * instruction-file walk: the directories it ignores wholesale, and the linked
+ * worktrees nested inside the scan root. A context scan that walks those pays
+ * for a build tree it will never load from, and reports — and on the auto-clean
+ * path REWRITES — another branch's copy of a file this checkout does not own.
+ *
+ * Git is asked rather than `.gitignore` parsed: it owns that grammar, nested
+ * files, `info/exclude` and `core.excludesFile` included, and the answer is one
+ * subprocess away.
+ *
+ * Every entry is a DIRECTORY. `git ls-files -o -i` also lists ignored FILES, and
+ * discarding those is what keeps `CLAUDE.local.md` — gitignored by convention,
+ * and loaded as model context at launch — inside every scan.
+ *
+ * Kept out of ./claude-context.mjs, which promises a dependency-free data module
+ * with no filesystem of its own.
+ */
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+
+import { excludeFromContextScan, isInsideDir } from "./claude-context.mjs";
+
+/**
+ * How git is asked. Injectable so a test can drive the failure paths, which no
+ * filesystem state can force.
+ * @typedef {(file: string, args: string[], cwd: string) => string} GitRun
+ */
+
+// Both bounds exist so a scan cannot hang or balloon on a pathological repo:
+// past either one the query is abandoned and the walk keeps its wider,
+// pre-prune scope (see askGit).
+const GIT_TIMEOUT_MS = 10_000;
+const GIT_MAX_BUFFER = 32 * 1024 * 1024;
+
+/**
+ * The default {@link GitRun}: git's stdout, with its stderr dropped so a
+ * dubious-ownership complaint never lands in the operator's terminal from a
+ * scan that recovers from it anyway.
+ *
+ * `core.fsmonitor=false` is a security pin, not a tuning knob: the scanned
+ * checkout is the untrusted party here, `ls-files` runs that config value as a
+ * COMMAND to refresh the index, and `safe.directory` does not cover a planted
+ * `.git/config` owned by the same uid. Without it, "scan this directory for
+ * hidden-Unicode payloads" is arbitrary code execution.
+ * @type {GitRun}
+ */
+const runGit = (file, args, cwd) =>
+  execFileSync(file, ["-c", "core.fsmonitor=false", ...args], {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: GIT_TIMEOUT_MS,
+    maxBuffer: GIT_MAX_BUFFER,
+  });
+
+/**
+ * `git <args>` in `dir`, or null when git cannot answer — not a repo, git
+ * absent, dubious ownership, a timeout, output past `maxBuffer`.
+ *
+ * The one recovery this module needs, and it is what keeps the prune from ever
+ * being a new way for a session to fail: null degrades the caller to the WIDER
+ * scope it walked before this prune existed. A throw with neither an errno nor
+ * an exit status is not git refusing, it is a bug here, and it propagates.
+ * @param {GitRun} run
+ * @param {string[]} args
+ * @param {string} dir
+ * @returns {string | null}
+ */
+function askGit(run, args, dir) {
+  try {
+    return run("git", args, dir);
+  } catch (err) {
+    const spawned = /** @type {NodeJS.ErrnoException & {status?: number}} */ (
+      err
+    );
+    if (spawned.code === undefined && spawned.status === undefined) throw err;
+    return null;
+  }
+}
+
+// `-z` because the newline-framed form cannot represent a worktree whose path
+// contains a newline: the record truncates mid-path, and both readers below
+// then name a directory that does not exist. It needs git >= 2.36, and an
+// older git rejects the flag rather than mis-answering — the prune degrades
+// through askGit to its wider pre-prune scope, and the teardown guard reaches
+// its own entrypoint catch.
+const WORKTREE_LIST_ARGS = Object.freeze([
+  "worktree",
+  "list",
+  "--porcelain",
+  "-z",
+]);
+
+/**
+ * Whether `attrs` carries `name`, as a bare flag or with a value after it.
+ * @param {string[]} attrs @param {string} name @returns {boolean}
+ */
+const hasAttribute = (attrs, name) =>
+  attrs.some((attr) => attr === name || attr.startsWith(`${name} `));
+
+/**
+ * The linked worktrees in a `git worktree list --porcelain -z` dump, main and
+ * bare ones excluded — those are not removable, so their state is never at risk
+ * from a teardown command, and the main one is the scan root a prune must never
+ * swallow.
+ * @param {string} porcelain
+ * @returns {string[]} absolute worktree paths
+ */
+export function parseWorktreeList(porcelain) {
+  const paths = [];
+  // Attributes are NUL-TERMINATED and a record ends with the resulting empty
+  // attribute, so records split on a doubled NUL. The first is always the main
+  // worktree; `bare` marks a bare repo's. `prunable` marks one whose directory
+  // is already gone — it holds no work to lose, and asking git for its status
+  // would only spawn into a missing cwd.
+  for (const record of porcelain.split("\0\0").slice(1)) {
+    const attrs = record.split("\0");
+    if (hasAttribute(attrs, "bare") || hasAttribute(attrs, "prunable"))
+      continue;
+    const line = attrs.find((attr) => attr.startsWith("worktree "));
+    if (line) paths.push(line.slice("worktree ".length));
+  }
+  return paths;
+}
+
+/**
+ * The linked worktrees of the repo at `cwd`. The guard on `git worktree remove`
+ * asks this the same way the prune below does, so one parser answers for both.
+ * @param {string} cwd
+ * @param {GitRun} run
+ * @returns {string[]} absolute worktree paths
+ */
+export function linkedWorktrees(cwd, run) {
+  return parseWorktreeList(run("git", [...WORKTREE_LIST_ARGS], cwd));
+}
+
+/**
+ * The directories under `dir` that git ignores wholesale. `--directory`
+ * collapses each to a single trailing-slash entry, and that slash is the only
+ * thing separating an ignored directory from an ignored FILE in this output —
+ * dropping the files is what keeps a gitignored instruction file scannable.
+ *
+ * `-z` because without it git C-quotes any path with a space, a quote or a
+ * non-ASCII byte under `core.quotePath`, and the prune would silently miss
+ * exactly those directories.
+ * @param {string} dir
+ * @param {GitRun} run
+ * @returns {string[]}
+ */
+function ignoredDirectories(dir, run) {
+  const out = askGit(
+    run,
+    ["ls-files", "-o", "-i", "--directory", "--exclude-standard", "-z"],
+    dir,
+  );
+  if (out === null) return [];
+  return out
+    .split("\0")
+    .filter((entry) => entry.endsWith("/"))
+    .map((entry) => entry.slice(0, -1));
+}
+
+/**
+ * The worktrees git has registered that live inside `dir`, as paths relative to
+ * it. A nested checkout is not ignored by default, so nothing but git's own
+ * registry can tell it apart from an ordinary subdirectory.
+ * @param {string} dir
+ * @param {GitRun} run
+ * @returns {string[]}
+ */
+function nestedWorktrees(dir, run) {
+  const out = askGit(run, [...WORKTREE_LIST_ARGS], dir);
+  if (out === null) return [];
+  // git reports PHYSICAL paths, so a scan root reached through a symlink only
+  // ever matches once both sides are canonical. The relative tail it yields is
+  // valid under the literal spelling too, which is what the walker's entries
+  // are relative to. Asked after the git call so a missing `dir` still fails
+  // open through the spawn's ENOENT rather than throwing here.
+  const root = realpathSync(dir);
+  return parseWorktreeList(out)
+    .map((path) => resolve(path))
+    .filter((path) => isInsideDir(root, path))
+    .map((path) => relative(root, path).split(sep).join("/"));
+}
+
+// One prune set per scan root, because launchInstructionFiles runs on many tool
+// calls and each would otherwise spawn git twice. Bypassed for an injected
+// `run`, so a test never reads another test's answer. A worktree added
+// mid-process is missed until the next process, which is the same staleness the
+// walk's own glob already has.
+/** @type {Map<string, Set<string>>} */
+const pruneCache = new Map();
+
+/**
+ * Directory paths a context scan of `dir` must not walk, relative to it and
+ * `/`-separated: every wholly-ignored directory (unless `ignoredDirs` is off)
+ * and every linked worktree nested inside it.
+ * @param {string} dir
+ * @param {{ ignoredDirs?: boolean, run?: GitRun }} [options]
+ * @returns {Set<string>}
+ */
+export function repoPrunedDirs(dir, { ignoredDirs = true, run } = {}) {
+  const key = `${resolve(dir)}\0${ignoredDirs}`;
+  const cached = run === undefined ? pruneCache.get(key) : undefined;
+  if (cached !== undefined) return cached;
+  const ask = run ?? runGit;
+  const pruned = new Set([
+    ...(ignoredDirs ? ignoredDirectories(dir, ask) : []),
+    ...nestedWorktrees(dir, ask),
+  ]);
+  if (run === undefined) pruneCache.set(key, pruned);
+  return pruned;
+}
+
+/**
+ * The `exclude` predicate for an instruction-file walk of `dir`: the static
+ * context-scope prune, plus {@link repoPrunedDirs}.
+ *
+ * `ignoredDirs: false` is the LAUNCH scan's posture, and it is a security
+ * choice rather than a performance one: `.gitignore` is repo-controlled, so
+ * honouring it in the one scan that covers launch-time ingress would let a
+ * hostile repo hide a planted `.claude/skills/…/SKILL.md` from it by ignoring
+ * that directory. The whole-tree scan can honour it because anything it prunes
+ * is still scanned by scan-loaded-instructions at the moment the host loads it.
+ *
+ * The lookup is EXACT, so the walk must hand it the same spelling
+ * {@link repoPrunedDirs} uses — one root-relative, `/`-separated path per entry,
+ * which is what walkContextGlobs normalizes to. A predicate that accepted a bare
+ * name as well would prune a tracked `src/build/` for a top-level ignored
+ * `build/`, splicing real instruction files out of the scan.
+ * @param {string} dir
+ * @param {{ ignoredDirs?: boolean, run?: GitRun }} [options]
+ * @returns {(entry: string) => boolean}
+ */
+export function contextScanExclude(dir, options = {}) {
+  const pruned = repoPrunedDirs(dir, options);
+  return (entry) => excludeFromContextScan(entry) || pruned.has(entry);
+}

package/types/claude-context.d.mts

@@ -33,7 +33,11 @@ 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
  * (a plain glob walk, and {@link excludeFromContextScan}) cannot disagree.
- * @param {string} entry  a bare entry name or a path relative to the scan root
+ *
+ * The LAST segment is what it reads: a dependency tree nested under a workspace
+ * package is the same dependency tree, and an entry naming one arrives as the
+ * path `packages/a/node_modules`, never as a bare name.
+ * @param {string} entry  a path relative to the scan root, `/`-separated
  * @returns {boolean}
  */
 export function excludeNodeModules(entry: string): boolean;
@@ -49,10 +53,10 @@ export function excludeNodeModules(entry: string): boolean;
  * 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
- * against `node_modules`.
- * @param {string} entry  a bare entry name or a path relative to the scan root
+ * Entries are paths relative to the scan root, so a top-level one is a bare
+ * name: it carries no `.claude` context and is judged only against
+ * `node_modules`.
+ * @param {string} entry  a path relative to the scan root, `/`-separated
  * @returns {boolean}
  */
 export function excludeFromContextScan(entry: string): boolean;

package/types/instructions.d.mts

@@ -28,6 +28,24 @@ export function scanText(content: string): Array<{
     method: string;
     decoded: string;
 }>;
+/**
+ * Every `globs` match under `cwd`, as an absolute path, with `node_modules` and
+ * whatever `exclude` rejects pruned from the WALK rather than filtered from its
+ * results — which is where a wide glob's cost actually is.
+ *
+ * `withFileTypes` is what makes the prune ANSWERABLE. Without it the walker
+ * calls `exclude` once with an entry's bare name and again with its
+ * root-relative path, so a predicate holding `build` cannot tell a top-level
+ * `build/` from a tracked `src/build/` and prunes both; under an absolute
+ * pattern it is handed absolute paths and matches neither. A Dirent carries an
+ * absolute `parentPath`, which normalizes to exactly one root-relative,
+ * `/`-separated entry per walked directory whatever shape the pattern has.
+ * @param {string[]} globs
+ * @param {string} cwd
+ * @param {(entry: string) => boolean} [exclude]
+ * @returns {string[]} absolute paths, one match per element
+ */
+export function walkContextGlobs(globs: string[], cwd: string, exclude?: (entry: string) => boolean): string[];
 /**
  * Expand `globs` (relative to `cwd`) to absolute file paths, skipping
  * `node_modules`. The glob set is the caller's instruction-file convention.
@@ -41,11 +59,11 @@ export function scanText(content: string): Array<{
  * tree), is SKIPPED, so one bad symlink never aborts scanning the rest of the
  * project.
  *
- * `exclude` prunes the WALK, which is where a wide glob's cost actually is —
- * a pattern that merely fails to match a bulk directory still pays to read it.
- * It is composed with, never replaces, the unconditional `node_modules` prune:
- * a caller narrowing the scan must not be able to widen it into a dependency
- * tree. Pass {@link excludeFromContextScan} to take Claude Code's own scope.
+ * `exclude` prunes the walk via {@link walkContextGlobs}, so it is handed one
+ * root-relative, `/`-separated path per entry. It is composed with, never
+ * replaces, the unconditional `node_modules` prune: a caller narrowing the scan
+ * must not be able to widen it into a dependency tree. Pass
+ * {@link excludeFromContextScan} to take Claude Code's own scope.
  * @param {string[]} globs
  * @param {{ cwd?: string, exclude?: (entry: string) => boolean }} [options]
  * @returns {string[]}
@@ -148,4 +166,5 @@ 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 { contextScanExclude } from "./repo-scope.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";