agent-sanitizer 2.47.12 → 2.47.14

package/claude-hooks/lib/env-config.mjs

@@ -105,7 +105,7 @@ export function minEnvSecretLen() {
   const hostLen = hostSource()?.minSecretLen;
   // The package floor comes from the same physical file
   // agent_sanitizer.secrets.config reads (DEFAULT_MIN_SECRET_LEN), so the JS
-  // pre-gate and the Python daemon cannot drift apart on it.
+  // pre-gate and the Python daemon read the same number.
   if (hostLen === undefined) return redactionFloor.min_secret_len;
   if (!Number.isInteger(hostLen) || hostLen <= 0)
     throw new Error(

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:
@@ -55,13 +69,13 @@ export const ALERT_BASE = join(
  * The path prefix every alert artifact of ONE session under this project shares.
  *
  * Session-keying is what makes the gate's one-time ask correct by construction.
- * The store and its ack used to be keyed by PROJECT alone and reset by a
- * destructive clear at SessionStart, which left two ways for a session to
- * inherit the previous one's answer: an early-exiting scanner arm (a dep-load
- * failure) returns before the clear, and nothing pins SessionStart against the
- * InstructionsLoaded events fired for the files loaded at launch. A session that
- * cannot see another session's files needs neither the clear nor the ordering —
- * past sessions' artifacts simply age out through {@link sweepStaleSessions}.
+ * Keying by PROJECT alone, reset by a destructive clear at SessionStart, would
+ * leave two ways for a session to inherit the previous one's answer: an
+ * early-exiting scanner arm (a dep-load failure) returns before the clear, and
+ * nothing pins SessionStart against the InstructionsLoaded events fired for
+ * the files loaded at launch. A session that cannot see another session's
+ * files needs neither the clear nor the ordering — past sessions' artifacts
+ * simply age out through {@link sweepStaleSessions}.
  * @param {string} [sessionId]  the harness's session identity
  * @returns {string}
  */
@@ -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 " +
@@ -414,11 +544,11 @@ export function invisibleCharAlert(sessionId) {
  * Add `text` to the alert the PreToolUse gate surfaces this session, keeping
  * whatever is already there.
  *
- * One O_EXCL-created, randomly-named file per finding. The store used to be a
- * single file appended through a read-modify-write, so two hooks recording a
- * finding at once silently dropped one of them; a fresh file per finding has no
- * shared cell to lose. Symlink-refusing (writeFileNoFollow) because the store
- * sits at a predictable, world-visible $TMPDIR path.
+ * One O_EXCL-created, randomly-named file per finding. A single file appended
+ * through a read-modify-write would let two hooks recording a finding at once
+ * silently drop one of them; a fresh file per finding has no shared cell to
+ * lose. Symlink-refusing (writeFileNoFollow) because the store sits at a
+ * predictable, world-visible $TMPDIR path.
  * @param {string} text
  * @param {string} [sessionId]
  * @returns {boolean} whether the finding was recorded

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/sanitize-output.mjs

@@ -680,7 +680,7 @@ export function sanitizerDepsLoaded() {
  * otherwise invisible because every later tool call then fails closed with no
  * stated cause — the recorded loader error and its remedy ride along. The text
  * comes from missingPackageMessage so this hook, the PreToolUse gate and the
- * prompt gate cannot drift apart on what a missing dependency reads like.
+ * prompt gate read the same words for what a missing dependency looks like.
  * @param {() => boolean} [depsLoaded]  injectable seam for testing
  * @param {string} [remedy]  what a reader should run; hosts pass their own
  * @returns {string}
@@ -801,8 +801,8 @@ export function emitHookFailure(
 
 /**
  * The suppression placeholder that replaces the tool output under the closed
- * posture. Named so the posture table and {@link emitFailClosed} cannot drift on
- * the wording the model sees.
+ * posture. Named so the posture table and {@link emitFailClosed} read the
+ * same wording the model sees.
  * @param {string} cause  the scrubbed hook error
  * @returns {string}
  */
@@ -963,12 +963,11 @@ export async function evaluateToolOutput(input, ext = {}) {
     containsPlaceholder(toolOutput)
   )
     warnings.push(ON_DISK_PLACEHOLDER_WARNING);
-  // `notes` is part of the guard, not covered by `modified`. The Layer-1
-  // carve-out that used to be the only note DID imply a strip, but the
-  // detect-only tiers do not: a preserved `<script>` and a plain-link exfil URL
-  // change no bytes and raise no warning, so without this clause the walk would
-  // return `clean` and the note would not be quieter — it would be GONE, taking
-  // "do not fetch, relay, or embed these URLs" with it.
+  // `notes` is part of the guard, not covered by `modified`. A detect-only
+  // tier's note implies no strip: a preserved `<script>` and a plain-link
+  // exfil URL change no bytes and raise no warning, so without this clause the
+  // walk would return `clean` and the note would not be quieter — it would be
+  // GONE, taking "do not fetch, relay, or embed these URLs" with it.
   if (!modified && warnings.length === 0 && notes.length === 0)
     return revealRead
       ? emit("flagged", { additional_context: REVEAL_READ_ENVELOPE })

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.12",
+  "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/src/gates.mjs

@@ -74,11 +74,11 @@ export function needsUrlScan(text) {
 // opaque run for ReDoS-safety. It is NOT derivable from that JSON: inlining the
 // detector regexes would reintroduce the cross-arm polynomial backtracking the
 // two-alternation split below exists to prevent, so this is a distinct
-// representation for a distinct constraint, not a copy. That duplication can't
-// be collapsed to one source, so it is instead DRIFT-GUARDED: the test in
-// test/secret-detectors-portability.test.mjs drives from the JSON and fails the
-// moment a detector is added/changed without a matching arm here — extend
-// SECRET_HINT when that fires.
+// representation for a distinct constraint, not a copy. drift-guard-ok: that
+// duplication can't be collapsed to one source, so a test instead guards it —
+// test/secret-detectors-portability.test.mjs drives from the JSON and fails
+// the moment a detector is added/changed without a matching arm here —
+// extend SECRET_HINT when that fires.
 // Split across TWO regexes, combined by matchesSecretHint:
 // one alternation of every arm makes a redos analyzer see cross-arm polynomial
 // backtracking (each arm is linear alone, but the union was a 3rd-degree

package/src/html.mjs

@@ -2350,10 +2350,10 @@ export function sanitizeHtml(text) {
 // post-parse walk never runs).
 const EXFIL_INDICATORS = [/\$\{[^{}]+\}/, /\{\{[^{}]+\}\}/];
 
-// Parameter NAMES whose presence used to flag on sight; now they only gate
-// WHICH raw params the value-shape test is applied to before the URL is parsed.
-// Kept narrow (the historically over-eager set) so the raw pre-parse pass stays
-// cheap; any non-keyword param is still value-gated post-parse by the walk.
+// Parameter NAMES that gate WHICH raw params the value-shape test is applied
+// to before the URL is parsed — presence alone no longer flags. Kept narrow so
+// the raw pre-parse pass stays cheap; any non-keyword param is still
+// value-gated post-parse by the walk.
 const KEYWORD_PARAM_NAME_RE =
   /^(?:data|d|payload|exfil|leak|steal|secret|token|key|env|password|pwd|cookie|session|auth)$/i;
 

package/src/index.mjs

@@ -7,12 +7,12 @@
  * is only paid for by callers that ask for it.
  *
  * Layers 1-3 are NOT implemented here: this module is a facade over the single
- * implementation in `./output.mjs` (`sanitizeText`). The two used to be
- * hand-synced copies and had already drifted apart in their warning prose, so
- * the layer bodies live in exactly one place and this file only translates the
- * facade's option/result shape. Importing `./output.mjs` costs nothing at module
- * scope — its graph is dependency-free and it lazy-loads `./html.mjs` on the
- * same terms this facade used to.
+ * implementation in `./output.mjs` (`sanitizeText`). A hand-synced copy would
+ * drift apart in its warning prose, so the layer bodies live in exactly one
+ * place and this file only translates the facade's option/result shape.
+ * Importing `./output.mjs` costs nothing at module scope — its graph is
+ * dependency-free and it lazy-loads `./html.mjs` on the same terms this facade
+ * does.
  *
  * The low-level building blocks stay public via the `./invisible` and `./html`
  * subpath entries; import those directly when you want a single layer without

package/src/invisible.mjs

@@ -127,11 +127,11 @@ export const STRIP = new RegExp(
 
 // SGR (Select Graphic Rendition) colour matching. Re-exported from ./ansi.mjs —
 // the ONE ANSI grammar, shared with the Layer-1 stripper, which cannot import
-// this module (layer1.mjs imports invisible.mjs, not the other way round). The
-// two used to be separate regexes with DIFFERENT parameter rules, and the looser
-// copy lived here: `ESC[12345m` read as SGR-only (so the operator got a
-// "display-only colour" note) while the stripper could not match it and spliced
-// a visible `[12345m` into the model's view.
+// this module (layer1.mjs imports invisible.mjs, not the other way round). A
+// second, looser copy here with DIFFERENT parameter rules would read
+// `ESC[12345m` as SGR-only (so the operator got a "display-only colour" note)
+// while the stripper could not match it and would splice a visible `[12345m`
+// into the model's view.
 export { SGR_RE } from "./ansi.mjs";
 
 /**
@@ -252,7 +252,7 @@ export function hasLongRun(text) {
  * payload-length invisible run, and a pointer to recover the bytes — a hex dump
  * is ASCII, so it passes through sanitization untouched. The single source of
  * this note, shared by the `sanitize` convenience entry and the tool-output
- * pipeline so the two can't drift.
+ * pipeline.
  * @param {string[]} invisFound CATEGORY codes applyLayer1 reported removing
  * @param {string} deAnsi ANSI-stripped text (invisible runs intact), for the LONG_RUN probe
  * @returns {string}
@@ -463,9 +463,9 @@ const MAX_TAG_SPEC_CHARS = 6;
 //
 // The two Compatibility Ideograph BLOCKS stay literal: they are not
 // Unified_Ideograph, and JS RegExp exposes no \p{Block=…}. Block boundaries are
-// immutable by Unicode's stability policy, so a literal span cannot drift; the
-// contract test in test/invisible-unicode-tables.test.mjs pins that every
-// ASSIGNED code point inside them is a Script=Han letter.
+// immutable by Unicode's stability policy, so a literal span stays correct
+// forever; the contract test in test/invisible-unicode-tables.test.mjs pins
+// that every ASSIGNED code point inside them is a Script=Han letter.
 const IVS_MIN = 0xe0100;
 const IVS_MAX = 0xe01ef;
 const CJK_IDEOGRAPH_RE =

package/src/output.mjs

@@ -163,10 +163,10 @@ function errMessage(err) {
  *      but each mutation can BREAK it again: a Layer-5 span deletion joins the
  *      bytes on either side of the deleted span and can leave a lone surrogate
  *      the model renders as a broken glyph and the redactor reads as U+FFFD.
- *      Repairing it inside whichever layer happened to need it (it used to live
- *      in the post-span-deletion re-redact, so it only ran when a redactor was
- *      configured) makes an invariant of Layer 1 conditional on an unrelated
- *      option.
+ *      Repairing it inside whichever layer happens to need it — e.g. only in
+ *      the post-span-deletion re-redact, so it runs only when a redactor is
+ *      configured — would make an invariant of Layer 1 conditional on an
+ *      unrelated option.
  *   2. `modified` is set — the caller's "bytes changed" banner.
  *   3. `unreportedChange` is set. A mutation that pushed no finding — a Layer-5
  *      span deletion whose filter returned no warning code — is a change the
@@ -196,9 +196,8 @@ function applyMutation(state, nextText) {
 /**
  * Run Layer 4 (`redact`) over the state's current text and fold any finding
  * back in. The single Layer-4 invocation site FOR THE PIPELINE STATE: the first
- * pass and the re-scan after a Layer-5 span deletion are the same call, so their
- * fail-closed handling, warning prose and post-redaction invariants cannot drift
- * apart.
+ * pass and the re-scan after a Layer-5 span deletion are the same call, so they
+ * share one fail-closed handling, warning prose and post-redaction invariant.
  *
  * One other site runs Layer 4 deliberately: {@link vetStageValue}, which vets a
  * stage value on its way out and has no `PipelineState` to fold a finding into.
@@ -714,10 +713,10 @@ export async function sanitizeText(text, options = {}) {
     notes,
     modified: state.modified,
     // Kept under its original name (it is a published field, and renaming a
-    // published field for a wording win is a breaking change) but now derived
-    // rather than tracked: "nothing here rose above a note". That is a strict
-    // generalization of what it used to mean — the inert-ANSI strip that set it
-    // before is now simply the most common way to end up note-only.
+    // published field for a wording win is a breaking change) but derived
+    // rather than tracked: "nothing here rose above a note". The inert-ANSI
+    // strip is simply the most common way to end up note-only, not the only
+    // one this field now covers.
     sgrNote:
       notes.length > 0 && warnings.length === 0 && !state.unreportedChange,
     ...(reveal !== undefined && { reveal }),

package/src/prompt.mjs

@@ -39,9 +39,10 @@ import { CONTROL_INTRODUCER_SOURCE } from "./ansi.mjs";
 // legitimate prompt (the SGR color carve-out is applied separately, after SGR
 // removal), so the whole block is gated, not a hand-picked subset that lets
 // DCS/SOS/PM/APC through. Built from the SHARED charset source instead of a
-// third hand-written copy: keeping the copies in step used to be a prose
-// obligation recorded in this very comment, and two of the three spelled ESC
-// differently, so even a grep-based drift check would have missed a divergence.
+// third hand-written copy: a hand-written third copy has no drift check
+// beyond a prose reminder in a comment, and a spelling difference between two
+// hand-written copies (e.g. how each spells ESC) is exactly what a grep-based
+// drift check would miss.
 const ANSI_INTRODUCER = new RegExp(CONTROL_INTRODUCER_SOURCE);
 
 /**

package/src/rehydrate.mjs

@@ -367,8 +367,8 @@ async function rehydrateEdit(
  * The shared anchor-ambiguity refusal: a stripped run abuts kept text it
  * resembles, so greedy deletion alignment cannot prove which bytes the region
  * owns. Edit's searched spans and Write's position-anchored regions hit the
- * same soundness gate and must speak the same language — one builder so the
- * two deny sentences cannot drift apart.
+ * same soundness gate and must speak the same language — one builder for
+ * both deny sentences.
  * @param {string} lead what could not be anchored ("the matched region", …)
  * @param {string} filePath
  * @param {string} guidance the caller-specific way out, without trailing punctuation

package/src/view-map.mjs

@@ -59,11 +59,11 @@ const FILE_VIEW = Symbol("agent-sanitizer:file-view");
  * Wrap a redactor's map-mode result in a frozen, branded view tagged with the
  * space its offsets are in.
  *
- * The redactor's own object is never touched. It used to be: the caller did
- * `view.pairs = pairsToUtf16(view.text, view.pairs)`, an in-place mutation of a
+ * The redactor's own object is never touched. A caller doing
+ * `view.pairs = pairsToUtf16(view.text, view.pairs)` would mutate in place a
  * value returned from an INJECTED seam. A redactor that memoizes its map result
  * (a reasonable thing for a caller to build) hands back the same object on the
- * second identical call, which then got converted a SECOND time — every
+ * second identical call, which would then get converted a SECOND time — every
  * placeholder preceded by an astral character shifts again and the same input
  * yields a different verdict.
  *

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

@@ -2,13 +2,13 @@
  * The path prefix every alert artifact of ONE session under this project shares.
  *
  * Session-keying is what makes the gate's one-time ask correct by construction.
- * The store and its ack used to be keyed by PROJECT alone and reset by a
- * destructive clear at SessionStart, which left two ways for a session to
- * inherit the previous one's answer: an early-exiting scanner arm (a dep-load
- * failure) returns before the clear, and nothing pins SessionStart against the
- * InstructionsLoaded events fired for the files loaded at launch. A session that
- * cannot see another session's files needs neither the clear nor the ordering —
- * past sessions' artifacts simply age out through {@link sweepStaleSessions}.
+ * Keying by PROJECT alone, reset by a destructive clear at SessionStart, would
+ * leave two ways for a session to inherit the previous one's answer: an
+ * early-exiting scanner arm (a dep-load failure) returns before the clear, and
+ * nothing pins SessionStart against the InstructionsLoaded events fired for
+ * the files loaded at launch. A session that cannot see another session's
+ * files needs neither the clear nor the ordering — past sessions' artifacts
+ * simply age out through {@link sweepStaleSessions}.
  * @param {string} [sessionId]  the harness's session identity
  * @returns {string}
  */
@@ -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.
@@ -134,11 +157,11 @@ export function invisibleCharAlert(sessionId?: string): string | null;
  * Add `text` to the alert the PreToolUse gate surfaces this session, keeping
  * whatever is already there.
  *
- * One O_EXCL-created, randomly-named file per finding. The store used to be a
- * single file appended through a read-modify-write, so two hooks recording a
- * finding at once silently dropped one of them; a fresh file per finding has no
- * shared cell to lose. Symlink-refusing (writeFileNoFollow) because the store
- * sits at a predictable, world-visible $TMPDIR path.
+ * One O_EXCL-created, randomly-named file per finding. A single file appended
+ * through a read-modify-write would let two hooks recording a finding at once
+ * silently drop one of them; a fresh file per finding has no shared cell to
+ * lose. Symlink-refusing (writeFileNoFollow) because the store sits at a
+ * predictable, world-visible $TMPDIR path.
  * @param {string} text
  * @param {string} [sessionId]
  * @returns {boolean} whether the finding was recorded

package/types/claude-hooks/sanitize-output.d.mts

@@ -163,7 +163,7 @@ export function sanitizerDepsLoaded(): boolean;
  * otherwise invisible because every later tool call then fails closed with no
  * stated cause — the recorded loader error and its remedy ride along. The text
  * comes from missingPackageMessage so this hook, the PreToolUse gate and the
- * prompt gate cannot drift apart on what a missing dependency reads like.
+ * prompt gate read the same words for what a missing dependency looks like.
  * @param {() => boolean} [depsLoaded]  injectable seam for testing
  * @param {string} [remedy]  what a reader should run; hosts pass their own
  * @returns {string}

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[]}
  */

package/types/invisible.d.mts

@@ -51,7 +51,7 @@ export function hasLongRun(text: string): boolean;
  * payload-length invisible run, and a pointer to recover the bytes — a hex dump
  * is ASCII, so it passes through sanitization untouched. The single source of
  * this note, shared by the `sanitize` convenience entry and the tool-output
- * pipeline so the two can't drift.
+ * pipeline.
  * @param {string[]} invisFound CATEGORY codes applyLayer1 reported removing
  * @param {string} deAnsi ANSI-stripped text (invisible runs intact), for the LONG_RUN probe
  * @returns {string}

package/types/view-map.d.mts

@@ -19,11 +19,11 @@
  * Wrap a redactor's map-mode result in a frozen, branded view tagged with the
  * space its offsets are in.
  *
- * The redactor's own object is never touched. It used to be: the caller did
- * `view.pairs = pairsToUtf16(view.text, view.pairs)`, an in-place mutation of a
+ * The redactor's own object is never touched. A caller doing
+ * `view.pairs = pairsToUtf16(view.text, view.pairs)` would mutate in place a
  * value returned from an INJECTED seam. A redactor that memoizes its map result
  * (a reasonable thing for a caller to build) hands back the same object on the
- * second identical call, which then got converted a SECOND time — every
+ * second identical call, which would then get converted a SECOND time — every
  * placeholder preceded by an astral character shifts again and the same input
  * yields a different verdict.
  *