agent-sanitizer 2.47.13 → 2.47.14

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

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

package/claude-hooks/pretooluse-sanitize.mjs

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.47.13",
+  "version": "2.47.14",
   "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/types/claude-hooks/lib/invisible-alert.d.mts

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

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

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