agent-sanitizer 2.66.4 → 2.66.5

package/README.md

@@ -250,7 +250,7 @@ To wire them yourself instead, one entry dispatches every mode on `--hook=`:
 | `SessionStart`       | `scan-invisible-chars`     |
 | `InstructionsLoaded` | `scan-loaded-instructions` |
 
-**Wire all five.** The instruction-file scan is split across two of them: `SessionStart` covers the files that load at launch, and `InstructionsLoaded` covers every one a subdirectory loads later. A host that wires the first without the second leaves a nested `CLAUDE.md` scanned by nothing, and the one-time PreToolUse coverage notice is the only thing that says so.
+**Wire all five.** The instruction-file scan is split across two of them: `SessionStart` covers the files that load at launch, and `InstructionsLoaded` covers every one a subdirectory loads later. A host that wires the first without the second leaves a nested `CLAUDE.md` scanned by nothing. The one-time PreToolUse coverage notice says so, but only when a file announced at launch went unscanned: a project whose only `CLAUDE.md` files sit in subdirectories gets no notice.
 
 `InstructionsLoaded` needs Claude Code **2.1.69 or newer** — 2.1.68 does not emit the event, so the hook never fires however you wire it. Check with `claude --version`.
 

package/THREAT-MODEL.md

@@ -547,8 +547,10 @@ entirely: a host that never wired the `InstructionsLoaded` event to
 `scan-loaded-instructions`, a Claude Code older than 2.1.69, which is the first
 build that emits that event, and `scan-loaded-instructions` switched off in
 `AGENT_SANITIZER_DISABLED_HOOKS`.
-Nothing on disk tells them apart, so the PreToolUse gate names all three, once
-per session, rather than leaving the gap silent.
+The PreToolUse gate reports the gap once per session rather than leaving it
+silent. It checks the disable list and asks the session's own `claude --version`,
+so the notice names only the cause it could not rule out: usually the wiring,
+which only `/hooks` shows.
 
 A fourth state is not one of them and is not reported as one: the host emits no
 event when it has nothing to announce. The gate therefore asks not "does anything
@@ -561,10 +563,11 @@ or an empty `~/.claude/CLAUDE.md` fires no event however the hook is wired, so
 the missing scan there is evidence of nothing. The trade this accepts is a false
 NEGATIVE: a repo whose announced instruction files all sit in subdirectories —
 a monorepo of per-package `CLAUDE.md` under a root carrying only `AGENTS.md`, on
-a machine with no user-global memory — loses the notice until a tool call touches
-one of those directories, which is what the gate's per-call `touchedDir` check
-recovers. Weighed against a false POSITIVE on every session launched outside a
-project, which trains the operator to skip the notice everywhere.
+a machine with no user-global memory — gets no notice at all. A tool call that
+touches such a directory is no evidence either: Claude Code loads the nested
+file only after that call, so its PreToolUse runs before any scan could have.
+Weighed against a false POSITIVE on every session launched outside a project,
+which trains the operator to skip the notice everywhere.
 
 That table is a claim about someone else's product, so the event that names a
 loaded file is also what falsifies it. `contextScopeContradiction` checks every

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

@@ -19,10 +19,13 @@ import {
   rmSync,
   statSync,
 } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { basename, join } from "node:path";
 import { homedir } from "node:os";
 import {
+  DISABLED_HOOKS_ENV,
+  disabledHooks,
   hookgateMarkerPath,
   lazyImport,
   markerIsTrusted,
@@ -340,12 +343,13 @@ export function recordInstructionsLoaded(sessionId) {
  */
 const EVENT_MIN_CLI_VERSION = "2.1.69";
 
+/** The `--hook=` name of the InstructionsLoaded scanner. */
+const LOADED_SCAN_HOOK = "scan-loaded-instructions";
+
 /**
  * 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.
+ * glob of `dir` can never change the answer.
  * @param {string} [sessionId]
  * @returns {string}
  */
@@ -455,36 +459,106 @@ function userGlobalLaunchHasContent(env = process.env) {
   );
 }
 
+/**
+ * The running Claude Code's version as `[major, minor, patch]`, or null when it
+ * cannot be read. Asks the binary rather than `CLAUDE_CODE_VERSION`: a remote
+ * host hands hooks a stale value there (2.1.42 under a 2.1.304 CLI).
+ * `CLAUDE_CODE_EXECPATH` names the binary running this session. Without it the
+ * answer is null: PATH's `claude` may be another install, and reporting its
+ * version as this session's would name a false cause. On an npm install that
+ * path is `node`, whose `v…` output also reads as null.
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {number[] | null}
+ */
+function runningCliVersion(env = process.env) {
+  if (!env.CLAUDE_CODE_EXECPATH) return null;
+  const result = spawnSync(env.CLAUDE_CODE_EXECPATH, ["--version"], {
+    encoding: "utf8",
+    timeout: 2000,
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  const match = /^(\d+)\.(\d+)\.(\d+)/u.exec(result.stdout ?? "");
+  return match ? match.slice(1).map(Number) : null;
+}
+
+/**
+ * Whether `version` is older than EVENT_MIN_CLI_VERSION.
+ * @param {number[]} version
+ * @returns {boolean}
+ */
+function predatesEvent(version) {
+  const floor = EVENT_MIN_CLI_VERSION.split(".").map(Number);
+  for (let i = 0; i < floor.length; i++)
+    if (version[i] !== floor[i]) return version[i] < floor[i];
+  return false;
+}
+
+/**
+ * The causes of a missing InstructionsLoaded scan that this hook could NOT rule
+ * out, each with the command that settles it. The disable list and the CLI
+ * version are checked here; only the wiring is left for `/hooks`. A cause that
+ * is confirmed is returned alone, since it explains the gap by itself.
+ * @param {Record<string, string | undefined>} env
+ * @param {(env: Record<string, string | undefined>) => number[] | null} cliVersion
+ * @returns {string}
+ */
+function unexplainedGapCauses(env, cliVersion) {
+  // A real list of hook names never reaches this one-name `known`, so the
+  // unknown-name report would misfire on every other entry: it is silenced.
+  if (disabledHooks([LOADED_SCAN_HOOK], env, () => {}).size > 0)
+    return `${LOADED_SCAN_HOOK} is switched off in ${DISABLED_HOOKS_ENV}; removing it from that list restores the scan.`;
+  const unwired =
+    `this host never wired the InstructionsLoaded event to ${LOADED_SCAN_HOOK} ` +
+    "(the `/hooks` command lists what this session registered; wiring it " +
+    "restores the scan), or the hook crashed before it ran";
+  const version = cliVersion(env);
+  if (version === null)
+    return (
+      `${LOADED_SCAN_HOOK} is not disabled. Either ${unwired}, or this Claude ` +
+      `Code is older than ${EVENT_MIN_CLI_VERSION}, the first build that emits ` +
+      "the event (its version could not be read: run `claude --version`)."
+    );
+  if (predatesEvent(version))
+    return (
+      `this Claude Code is ${version.join(".")}, older than ` +
+      `${EVENT_MIN_CLI_VERSION}, the first build that emits the event; ` +
+      "upgrading restores the scan."
+    );
+  return (
+    `${LOADED_SCAN_HOOK} is not disabled and Claude Code ${version.join(".")} ` +
+    `emits the event, so either ${unwired}.`
+  );
+}
+
 /**
  * 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, the
- * host's cold-start marker says setup is still running, or neither launch nor
- * `touchedDir` could have fired the event.
+ * host's cold-start marker says setup is still running, or nothing announced at
+ * launch could have fired the event.
  *
  * 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.
+ * in a returned response. Launch-emptiness is cached once found, since the
+ * launch set is fixed for the session.
  *
- * 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 held
- * a file the event would have ANNOUNCED, with bytes in it. The three remaining
- * causes are named together, 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.
+ * Launch is the only evidence read. Claude Code fires the session_start events
+ * before the first PreToolUse, but a subdirectory's CLAUDE.md loads only AFTER
+ * the tool call that reaches it, so a PreToolUse can never already see that
+ * file's scan, however the hook is wired.
  * @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
+ * @param {{
+ *   env?: Record<string, string | undefined>,
+ *   cliVersion?: (env: Record<string, string | undefined>) => number[] | null,
+ * }} [options]  injectable for tests; any other value, such as a directory
+ *   string from an older caller, reads as no options
  * @returns {string | null}
  */
 export function instructionsLoadedGapNotice(
   sessionId,
   dir = PROJECT_DIR,
-  touchedDir,
+  { env = process.env, cliVersion = runningCliVersion } = {},
 ) {
   if (instructionsLoadedSeen(sessionId)) return null;
   if (markerIsTrusted(instructionsLoadedNoticeFile(sessionId))) return null;
@@ -497,31 +571,20 @@ export function instructionsLoadedGapNotice(
   // notice for every later session on the host.
   const marker = hookgateMarkerPath();
   if (markerIsTrusted(marker) && probeSetupAlive(marker)) return null;
-  const launchCached = markerIsTrusted(launchEmptyFile(sessionId));
-  const launchHasBytes =
-    !launchCached &&
-    (anyFileHasBytes(announcedLaunchFiles(dir)) ||
-      userGlobalLaunchHasContent());
-  if (!launchCached && !launchHasBytes)
+  if (markerIsTrusted(launchEmptyFile(sessionId))) return null;
+  if (
+    !anyFileHasBytes(announcedLaunchFiles(dir)) &&
+    !userGlobalLaunchHasContent(env)
+  ) {
     writeSentinelFile(launchEmptyFile(sessionId));
-  const touchedHasBytes =
-    touchedDir !== undefined &&
-    anyFileHasBytes(announcedLaunchFiles(touchedDir));
-  if (!launchHasBytes && !touchedHasBytes) return null;
+    return null;
+  }
   return (
     "agent-sanitizer: no InstructionsLoaded scan has run this session, so " +
     "instruction files loaded from SUBDIRECTORIES (a nested CLAUDE.md, a " +
     "directory-scoped rule) are reaching the model unscanned for hidden " +
     "Unicode — the session-start scan covers only the files loaded at launch. " +
-    "Tell the user, and name all three causes with the command that decides " +
-    "each: this host never wired the InstructionsLoaded event to " +
-    "scan-loaded-instructions (the `/hooks` command lists what this session " +
-    "actually registered, whichever config dir or plugin root the host uses; " +
-    "wiring it restores the coverage), a Claude Code " +
-    `older than ${EVENT_MIN_CLI_VERSION}, the first build that emits the event ` +
-    "(`claude --version`; upgrading restores it), or scan-loaded-instructions " +
-    "switched off in AGENT_SANITIZER_DISABLED_HOOKS (`echo " +
-    "$AGENT_SANITIZER_DISABLED_HOOKS`)."
+    `Tell the user: ${unexplainedGapCauses(env, cliVersion)}`
   );
 }
 

package/claude-hooks/pretooluse-sanitize.mjs

@@ -29,7 +29,6 @@
  */
 import { createRequire } from "node:module";
 import { readFileSync } from "node:fs";
-import { dirname } from "node:path";
 import {
   isMain,
   lazyImport,
@@ -438,40 +437,6 @@ export function preToolUseLayers(
   );
 }
 
-// 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 five stages. Returns the `hookSpecificOutput` fields to emit, or
  * null for a clean no-op. Throws only if a stage's engine throws; the caller
@@ -523,11 +488,7 @@ export async function buildPreToolUseResponse(input, rehydrate, sink, layers) {
   // 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,
-    undefined,
-    toolTargetDir(tool, toolInput),
-  );
+  const gapNotice = instructionsLoadedGapNotice(input.session_id);
   if (gapNotice !== null) contexts.push(gapNotice);
 
   // The rewriting stages, run by the declared pipeline: the driver — not this

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.66.4",
+  "version": "2.66.5",
   "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

@@ -82,9 +82,7 @@ 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.
+ * glob of `dir` can never change the answer.
  * @param {string} [sessionId]
  * @returns {string}
  */
@@ -105,30 +103,32 @@ 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, the notice already ran this session, the
- * host's cold-start marker says setup is still running, or neither launch nor
- * `touchedDir` could have fired the event.
+ * host's cold-start marker says setup is still running, or nothing announced at
+ * launch could have fired the event.
  *
  * 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.
+ * in a returned response. Launch-emptiness is cached once found, since the
+ * launch set is fixed for the session.
  *
- * 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 held
- * a file the event would have ANNOUNCED, with bytes in it. The three remaining
- * causes are named together, 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.
+ * Launch is the only evidence read. Claude Code fires the session_start events
+ * before the first PreToolUse, but a subdirectory's CLAUDE.md loads only AFTER
+ * the tool call that reaches it, so a PreToolUse can never already see that
+ * file's scan, however the hook is wired.
  * @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
+ * @param {{
+ *   env?: Record<string, string | undefined>,
+ *   cliVersion?: (env: Record<string, string | undefined>) => number[] | null,
+ * }} [options]  injectable for tests; any other value, such as a directory
+ *   string from an older caller, reads as no options
  * @returns {string | null}
  */
-export function instructionsLoadedGapNotice(sessionId?: string, dir?: string, touchedDir?: string): string | null;
+export function instructionsLoadedGapNotice(sessionId?: string, dir?: string, { env, cliVersion }?: {
+    env?: Record<string, string | undefined>;
+    cliVersion?: (env: Record<string, string | undefined>) => number[] | null;
+}): 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.