agent-sanitizer 2.66.3 → 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
@@ -797,7 +800,7 @@ positive costs a sentence of context, never a mangled input):
   the identical Write confirms and passes. The confirmation is the model's
   deliberate retry — never a human permission prompt — held as a
   consumed-on-use, TTL-bounded sentinel (keyed to path + content + the dropped
-  values) via the same squat-resistant `$TMPDIR` helpers as the invisible-char
+  values) in `$TMPDIR` via the same squat-resistant helpers as the invisible-char
   gate. Tracked files, secret-free files, failed git probes and unmappable
   views all skip the guard (fail open). "Tracked" approximates "recoverable":
   an uncommitted secret line on a tracked file is an accepted gap — the
@@ -927,6 +930,16 @@ it, so what anchors its trust is worth stating exactly.
   under `TMPDIR` is read only when this user owns it with owner-only write, so a
   squatted shared-temp entry cannot pre-suppress the warning that a call ran
   unsanitized.
+- **Session state lives under that directory too, not in `$TMPDIR`.** The
+  InstructionsLoaded marker, the invisible-char gate's findings and ack, and the
+  Layer-2 reveal spans sit in `${CLAUDE_PLUGIN_DATA}/session-state`, created mode
+  700 and used only when both it and the data directory are real directories
+  this user owns with no group/other write (`privateDirAt`) and the leaf is
+  writable. An OS temp cleaner (macOS dirhelper purges `$TMPDIR` entries unread
+  for 3 days) would otherwise delete a live session's marker — a false "no
+  InstructionsLoaded scan has run" notice — or its findings, lifting the gate.
+  A host with no plugin data directory, or one that fails those checks, falls
+  back to `$TMPDIR` and keeps that exposure.
 - **Opting out.** `AGENT_SANITIZER_HOOK_BINARY=0` never downloads and never runs
   a binary. That leaves the node path running the shipped bundle and the
   compile cache above; `AGENT_SANITIZER_COMPILE_CACHE=0` turns the cache off as

package/claude-hooks/lib/hook-io.mjs

@@ -1,15 +1,21 @@
 /** Shared I/O helpers for the Claude Code hook scripts. */
 
 import {
+  accessSync,
+  constants as fsConstants,
   openSync,
   closeSync,
   lstatSync,
+  lutimesSync,
+  mkdirSync,
   readFileSync,
   unlinkSync,
   writeFileSync,
 } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
+import { tmpdir } from "node:os";
+import { isAbsolute, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { excludeProvisioning } from "./hook-timing.mjs";
 import { readKnob } from "./knobs.mjs";
@@ -695,6 +701,55 @@ export const PROJECT_HASH = createHash("sha256")
   .digest("hex")
   .slice(0, 8);
 
+/**
+ * The directory the session-lifetime stores live under: the alert markers and
+ * findings (invisible-alert.mjs) and the reveal sidecars (reveal.mjs). They must
+ * outlive the longest session, which $TMPDIR does not promise — macOS's daily
+ * dirhelper job deletes anything in the per-user `/var/folders/.../T/` not
+ * accessed for 3 days, and a marker written at launch and only ever `lstat`ed
+ * then vanishes from a session still running, its absence read as "never ran".
+ *
+ * `$CLAUDE_PLUGIN_DATA/session-state` when both levels are private to this uid
+ * ({@link privateDirAt}): write on the plugin data dir alone is enough to swap
+ * `session-state` out. Each level is created 0700 when absent — so the
+ * launch-time InstructionsLoaded event and the first tool call resolve the same
+ * root whichever runs first — and checked BEFORE the next is created inside it,
+ * so a symlinked or shared plugin data dir never gets a directory planted in
+ * its target. A root this process cannot write — a read-only mount, an owner
+ * bit removed — is no root: every marker write would fail and read as "the
+ * event never fired". Otherwise $TMPDIR, where the stores' squat checks apply.
+ * @param {Record<string, string | undefined>} env
+ * @returns {string}
+ */
+export function resolveStateRoot(env) {
+  const data = env.CLAUDE_PLUGIN_DATA;
+  // A relative path resolves against each hook process's cwd, so two processes
+  // would disagree on the root, and it could land inside a scanned tree.
+  if (!data || !isAbsolute(data)) return tmpdir();
+  const root = join(data, "session-state");
+  for (const dir of [data, root]) {
+    try {
+      mkdirSync(dir, { mode: 0o700 });
+    } catch (err) {
+      // Anything but "already there" — a read-only or unreachable plugin data
+      // dir — is an ordinary host: $TMPDIR still holds the state, at its
+      // shorter lifetime.
+      if (/** @type {NodeJS.ErrnoException} */ (err).code !== "EEXIST")
+        return tmpdir();
+    }
+    if (!privateDirAt(dir)) return tmpdir();
+  }
+  try {
+    accessSync(root, fsConstants.W_OK | fsConstants.X_OK);
+  } catch {
+    return tmpdir();
+  }
+  return root;
+}
+
+/** {@link resolveStateRoot} for this process, resolved once at load. */
+export const STATE_ROOT = resolveStateRoot(process.env);
+
 /** The marker filename stem; the project directory is appended to it. */
 const HOOKGATE_MARKER_STEM = "agent-sanitizer-hookgate-inflight-";
 
@@ -1067,7 +1122,7 @@ export function currentUid() {
 
 /**
  * Whether `st` (an lstat result) is owned by this process's uid. THE ownership
- * predicate for every $TMPDIR store these hooks trust — a second spelling is how
+ * predicate for every state store these hooks trust — a second spelling is how
  * four call sites came to share the passwd-lookup crash {@link currentUid}
  * documents. False when the platform has no uid model: ownership that cannot be
  * proven is not granted. `uid` is a seam for a test that must model another
@@ -1084,10 +1139,11 @@ export function ownedByCurrentUser(st, uid = currentUid()) {
  * Whether `st` (an lstat result) is a directory no untrusted uid can change: a
  * real directory (lstat, so a planted symlink is not one), owned by this uid —
  * or by root where `rootMayOwn` — with no group/other write bit. THE trust test
- * for every private directory these hooks keep in $TMPDIR. Write is the
- * property because creating, unlinking or replacing an entry needs write on its
- * parent: a co-tenant holding it can delete the finding a gate needs, swap a
- * reveal file, or rebind the redactor socket to a listener that redacts nothing.
+ * for every private directory these hooks keep, under STATE_ROOT or $TMPDIR.
+ * Write is the property because creating, unlinking or replacing an entry needs
+ * write on its parent: a co-tenant holding it can delete the finding a gate
+ * needs, swap a reveal file, or rebind the redactor socket to a listener that
+ * redacts nothing.
  * Root ownership is strictly stronger than ours, so a deployment may hand a dir
  * to root (`rootMayOwn`); with no uid model nothing is trusted, root included.
  * @param {{ isDirectory(): boolean, uid: number, mode: number }} st
@@ -1104,6 +1160,44 @@ export function isPrivateDir(
   return st.isDirectory() && owner && (st.mode & 0o022) === 0;
 }
 
+/**
+ * Whether `path` is a private directory of this uid ({@link isPrivateDir}) —
+ * the directory counterpart of markerIsTrusted. `lstat`, so a symlink planted at
+ * a predictable path is judged on ITSELF: followed, it would let a co-tenant aim
+ * a reader at unrelated files this uid owns (the alert gate splices those bytes
+ * into a permission prompt). An absent path is simply not one.
+ * @param {string} path
+ * @param {{ uid?: number | null }} [opts]  as in {@link isPrivateDir}
+ * @returns {boolean}
+ */
+export function privateDirAt(path, opts) {
+  let st;
+  try {
+    st = lstatSync(path);
+  } catch {
+    return false;
+  }
+  return isPrivateDir(st, opts);
+}
+
+/**
+ * Stamp a state file the caller has just trusted as used now, so a live
+ * session's state never looks idle to an age-based sweep — another session's
+ * {@link STATE_ROOT} sweep (mtime) or an OS temp cleaner (atime). `lutimes`, so
+ * a symlink swapped in after the caller's check is stamped itself, never its
+ * target. A path a parallel sweep removed after that check is simply gone.
+ * @param {string} path
+ * @returns {void}
+ */
+export function touchLiveState(path) {
+  const now = new Date();
+  try {
+    lutimesSync(path, now, now);
+  } catch (err) {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code !== "ENOENT") throw err;
+  }
+}
+
 /**
  * Create a presence sentinel at `path` without following a symlink a co-tenant
  * may have pre-planted there. These sentinels live at predictable, world-visible

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

@@ -19,18 +19,24 @@ 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, tmpdir } from "node:os";
+import { homedir } from "node:os";
 import {
+  DISABLED_HOOKS_ENV,
+  disabledHooks,
   hookgateMarkerPath,
   lazyImport,
   markerIsTrusted,
-  isPrivateDir,
+  ownedByCurrentUser,
+  privateDirAt,
   probeSetupAlive,
   PROJECT_DIR,
   PROJECT_HASH,
   scrubUntrustedText,
+  STATE_ROOT,
+  touchLiveState,
   writeFileNoFollow,
   writeSentinelFile,
 } from "./hook-io.mjs";
@@ -59,15 +65,28 @@ const { applyLayer1WellFormed } =
     await lazyImport("agent-sanitizer")
   );
 
+/** Every alert artifact name's start, less the project hash that follows it. */
+const ALERT_STEM = ".claude-invisible-char-alert-";
+
 /**
  * The path prefix every alert artifact of this PROJECT shares. Never a file
  * itself — only {@link sessionPrefix} and the sweep read it — so that one
- * `startsWith` covers every artifact the sweep must age out.
+ * `startsWith` covers every artifact the sweep must age out. Under STATE_ROOT,
+ * not $TMPDIR itself: an OS temp cleaner deleting a live session's marker would
+ * read as the InstructionsLoaded scan never having run, and deleting its
+ * findings would lift the gate mid-session.
+ */
+export const ALERT_BASE = join(STATE_ROOT, `${ALERT_STEM}${PROJECT_HASH}`);
+
+/**
+ * Whether `name` is a session artifact of ANY project: {@link ALERT_BASE}'s
+ * name, whatever its project hash, then `.s-`.
+ * @param {string} name
+ * @returns {boolean}
  */
-export const ALERT_BASE = join(
-  tmpdir(),
-  `.claude-invisible-char-alert-${PROJECT_HASH}`,
-);
+const isAnyProjectSessionEntry = (name) =>
+  name.startsWith(ALERT_STEM) &&
+  /^[0-9a-f]{8}\.s-/u.test(name.slice(ALERT_STEM.length));
 
 /**
  * The path prefix every alert artifact of ONE session under this project shares.
@@ -86,7 +105,7 @@ export const ALERT_BASE = join(
 export function sessionPrefix(sessionId) {
   // The id becomes a path component, so anything outside this class — a `/` in
   // a hostile session id above all — is folded away rather than escaping
-  // $TMPDIR. A host that exports no session id falls back to one shared name,
+  // STATE_ROOT. A host that exports no session id falls back to one shared name,
   // whose findings and ack are bounded by FALLBACK_TTL_MS instead.
   const key =
     (sessionId ?? "").replace(/[^A-Za-z0-9._-]/gu, "_") || "no-session";
@@ -138,12 +157,20 @@ export function instructionsLoadedNoticeFile(sessionId) {
  * lazily-loaded instruction files are being scanned at all. Ownership-validated
  * like every other marker here: a co-tenant could otherwise plant the
  * predictable path and suppress the notice below, which is the whole signal that
- * nested files are going unscanned.
+ * nested files are going unscanned. A marker that is seen is stamped as used:
+ * it is written once at launch, so otherwise a session outliving
+ * MARKER_TTL_MS would have it swept by another session's SessionStart and read
+ * its absence as the event never having fired.
  * @param {string} [sessionId]
  * @returns {boolean}
  */
 export function instructionsLoadedSeen(sessionId) {
-  return markerIsTrusted(instructionsLoadedFile(sessionId));
+  const marker = instructionsLoadedFile(sessionId);
+  if (!markerIsTrusted(marker)) return false;
+  // Not the shared no-session marker: every session-less host would refresh
+  // it, and MARKER_TTL_MS is what keeps it from silencing every later session.
+  if (sessionPrefix(sessionId) !== sessionPrefix()) touchLiveState(marker);
+  return true;
 }
 
 /** How long a past session's artifacts are kept before a later session sweeps. */
@@ -182,8 +209,8 @@ const FALLBACK_TTL_MS = 30 * 60 * 1000;
  * this `lstat` reads as expired, which is what every caller wants of a file that
  * is no longer there: the sweep's unlink becomes a no-op, the gate's reader skips
  * it, and an ack that vanished stops suppressing the ask. Propagating instead
- * would abort recordInstructionsLoaded on a benign $TMPDIR race and render the
- * false "instruction file was NOT scanned" fault.
+ * would abort recordInstructionsLoaded on a benign STATE_ROOT race and render
+ * the false "instruction file was NOT scanned" fault.
  *
  * `lstat`, so a planted symlink is judged on itself.
  * @param {string} path
@@ -206,30 +233,12 @@ function withinTtl(path, ttlMs) {
 const withinFallbackTtl = (path) => withinTtl(path, FALLBACK_TTL_MS);
 
 /**
- * Whether `path` is a private directory of this uid ({@link isPrivateDir}) —
- * the directory counterpart of markerIsTrusted. `lstat`, so a symlink planted
- * at the predictable alert-dir path is judged on ITSELF: followed, it would let
- * a co-tenant aim the gate's reader at a directory of unrelated files this uid
- * owns and splice their bytes into a permission prompt. A group/other-writable
- * one is refused too: a co-tenant could unlink the finding the gate needs.
- * @param {string} path
- * @returns {boolean}
- */
-function dirIsTrusted(path) {
-  let st;
-  try {
-    st = lstatSync(path);
-  } catch {
-    return false;
-  }
-  return isPrivateDir(st);
-}
-
-/**
- * Delete this project's artifacts from OTHER sessions once they are older than
+ * Delete OTHER sessions' artifacts, of every project, once they are older than
  * the TTL. The current session's own prefix is skipped, so the sweep can never
  * answer its own question wrong; every other session's files are past history
- * that nothing reads.
+ * that nothing reads — a live one keeps its marker and findings fresh on read.
+ * Every project, because STATE_ROOT may be persistent: a project never reopened
+ * would otherwise keep its artifacts for good.
  *
  * This replaces the destructive SessionStart clear: with the store session-keyed
  * there is nothing to reset, only old state to age out.
@@ -237,28 +246,28 @@ function dirIsTrusted(path) {
  * @returns {void}
  */
 export function sweepStaleSessions(sessionId) {
-  const dir = tmpdir();
-  const prefix = `${basename(ALERT_BASE)}.s-`;
+  const dir = STATE_ROOT;
   const keep = basename(sessionPrefix(sessionId));
   const cutoff = Date.now() - MARKER_TTL_MS;
   for (const name of readdirSync(dir)) {
-    if (!name.startsWith(prefix)) continue;
+    if (!isAnyProjectSessionEntry(name)) continue;
     // Whole-segment match on the keep prefix, not a bare startsWith: session key
     // "abc" must not claim (and so preserve) session key "abc2"'s artifacts.
     if (name === keep || name.startsWith(`${keep}.`)) continue;
     const path = join(dir, name);
     try {
-      // lstat, not stat: a squatted symlink at a predictable $TMPDIR path must
-      // be judged on ITSELF, not on whatever it points at.
-      if (lstatSync(path).mtimeMs >= cutoff) continue;
+      // lstat, not stat: a squatted symlink at a predictable path is judged on
+      // ITSELF. Ownership first: in a shared /tmp another uid's entry is not
+      // ours to remove, and an rmSync on its file fails ENOTDIR, not EPERM.
+      const st = lstatSync(path);
+      if (!ownedByCurrentUser(st) || st.mtimeMs >= cutoff) continue;
       rmSync(path, { recursive: true, force: true });
     } catch (err) {
       // ENOENT: a parallel session swept this entry between readdir and lstat.
-      // EPERM/EACCES: a co-tenant's entry sharing the prefix, which is not ours
-      // to remove. Both are benign races on a shared $TMPDIR, and a throw here
-      // would abort recordInstructionsLoaded and render the "instruction file
-      // was NOT scanned" fault on a session that WAS scanned. Anything else is
-      // a bug in this sweep and propagates.
+      // EPERM/EACCES: an entry of ours a co-tenant's directory shields. A throw
+      // here would abort recordInstructionsLoaded and render the "instruction
+      // file was NOT scanned" fault on a session that WAS scanned. Anything else
+      // is a bug in this sweep and propagates.
       const code = /** @type {NodeJS.ErrnoException} */ (err).code;
       if (code !== "ENOENT" && code !== "EPERM" && code !== "EACCES") throw err;
     }
@@ -268,7 +277,7 @@ export function sweepStaleSessions(sessionId) {
 
 /**
  * Remove the shared-prefix artifacts the reader has stopped honouring, so they
- * stop occupying $TMPDIR too. The loop above cannot: it skips the current
+ * stop occupying STATE_ROOT too. The loop above cannot: it skips the current
  * session's prefix, which on a host with no session id IS this one.
  *
  * Mirrors what {@link invisibleCharAlert} and {@link alertAcknowledged} read.
@@ -281,14 +290,14 @@ export function sweepStaleSessions(sessionId) {
  * 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.
+ * and would otherwise leave a session-less host's markers in STATE_ROOT
+ * forever, with the gap notice suppressed on every later session.
  * @param {string} [sessionId]
  * @returns {void}
  */
 function sweepStaleFallback(sessionId) {
   const dir = alertDir();
-  const inherited = alertDir(sessionId) !== dir && dirIsTrusted(dir);
+  const inherited = alertDir(sessionId) !== dir && privateDirAt(dir);
   const entries = inherited
     ? readdirSync(dir).map((name) => join(dir, name))
     : [];
@@ -311,7 +320,7 @@ function sweepStaleFallback(sessionId) {
 
 /**
  * Record that the InstructionsLoaded scanner engaged. Symlink-safe presence
- * write (see writeSentinelFile) at a predictable $TMPDIR path.
+ * write (see writeSentinelFile) at a predictable STATE_ROOT path.
  *
  * The event fires once per instruction file loaded, so the already-recorded case
  * returns without a write — and the stale-session sweep rides the FIRST fire of
@@ -334,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}
  */
@@ -449,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;
@@ -491,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)}`
   );
 }
 
@@ -534,14 +603,14 @@ export function recordInstructionsLoadedNotice(sessionId) {
  * The alert findings if invisible-char injection was detected in instruction
  * files and couldn't be auto-cleaned, else null.
  *
- * The store is a DIRECTORY of one file per finding, all at predictable,
- * world-visible $TMPDIR paths, so both the directory and every entry in it are
- * attacker-plantable: trust the directory only when it is a real directory this
- * uid owns (a symlink would let a co-tenant aim this reader at unrelated files),
- * each entry only when markerIsTrusted confirms a regular file this uid owns,
- * then scrub the bytes through Layer-1 before any caller splices them into a
- * reason — the report would otherwise carry ANSI/invisible spoofing into the
- * model's context.
+ * The store is a DIRECTORY of one file per finding, all at predictable
+ * STATE_ROOT paths (world-visible in the $TMPDIR fallback), so both the
+ * directory and every entry in it are attacker-plantable: trust the directory
+ * only when it is a real directory this uid owns (a symlink would let a
+ * co-tenant aim this reader at unrelated files), each entry only when
+ * markerIsTrusted confirms a regular file this uid owns, then scrub the bytes
+ * through Layer-1 before any caller splices them into a reason — the report
+ * would otherwise carry ANSI/invisible spoofing into the model's context.
  * This session's store AND the shared `no-session` fallback, because a hook that
  * faults BEFORE it can parse its payload has no session identity to key by: its
  * finding lands in the fallback, and a strictly session-keyed read would leave
@@ -560,7 +629,10 @@ export function invisibleCharAlert(sessionId) {
   const dirs = own === alertDir() ? [own] : [own, alertDir()];
   const parts = [];
   for (const dir of dirs) {
-    if (!dirIsTrusted(dir)) continue;
+    if (!privateDirAt(dir)) continue;
+    // A live session's findings must outlast any sweep that ages the store by
+    // its directory's timestamp: losing them lifts the gate mid-session.
+    if (dir === own) touchLiveState(dir);
     // Sorted so a multi-finding report reads the same on every call; the names
     // are random, so the order carries no meaning beyond being stable.
     for (const name of readdirSync(dir).sort()) {
@@ -583,7 +655,7 @@ export function invisibleCharAlert(sessionId) {
  * 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.
+ * predictable STATE_ROOT path, world-visible in the $TMPDIR fallback.
  * @param {string} text
  * @param {string} [sessionId]
  * @returns {boolean} whether the finding was recorded
@@ -597,7 +669,7 @@ export function appendAlert(text, sessionId) {
   let usable;
   try {
     mkdirSync(dir, { recursive: true, mode: 0o700 });
-    usable = dirIsTrusted(dir);
+    usable = privateDirAt(dir);
   } catch {
     usable = false;
   }
@@ -612,9 +684,10 @@ export function appendAlert(text, sessionId) {
 /**
  * True once the gate has surfaced its blocking ask this session. Validates
  * ownership (not mere existence): a co-tenant could pre-create the ack at its
- * predictable $TMPDIR path to permanently suppress the one-time blocking ask down
- * to the passive reminder, so trust the marker only when it is a regular file
- * this uid wrote (markerIsTrusted), mirroring how acknowledgeAlert writes it.
+ * predictable STATE_ROOT path to permanently suppress the one-time blocking ask
+ * down to the passive reminder, so trust the marker only when it is a regular
+ * file this uid wrote (markerIsTrusted), mirroring how acknowledgeAlert writes
+ * it.
  *
  * On a host that exports no session id every session shares the fallback prefix,
  * so the ack has no session to end with and would suppress the one-time blocking
@@ -638,8 +711,8 @@ export function alertAcknowledged(sessionId) {
  * @returns {void}
  */
 export function acknowledgeAlert(sessionId) {
-  // Symlink-safe presence write: the ack sits at a predictable $TMPDIR path a
-  // co-tenant could pre-plant a symlink at (see writeSentinelFile).
+  // Symlink-safe presence write: the ack sits at a predictable STATE_ROOT path
+  // a co-tenant could pre-plant a symlink at (see writeSentinelFile).
   writeSentinelFile(alertAckFile(sessionId));
 }
 

package/claude-hooks/lib/redactor-client.mjs

@@ -35,7 +35,12 @@ import {
   encodeFrame,
   isPlainObject,
 } from "./redactor-wire.mjs";
-import { currentUid, isPrivateDir, ownedByCurrentUser } from "./hook-io.mjs";
+import {
+  currentUid,
+  isPrivateDir,
+  ownedByCurrentUser,
+  privateDirAt,
+} from "./hook-io.mjs";
 import { readKnob } from "./knobs.mjs";
 
 export { FRAME_CAP };
@@ -54,25 +59,6 @@ export { positiveMsOr } from "./knobs.mjs";
 const SOCKET_PATH_MAX = 103;
 const TEMP_BIND_NAME_LENGTH = 17;
 
-/**
- * Whether `root` is a real directory this uid owns that no group/other can
- * write. lstat, so a symlinked root is refused rather than followed. An absent
- * root is just not a candidate: this runs at module load, where a throw would
- * stop the hook loading at all.
- * @param {string} root
- * @param {number | null} uid
- * @returns {boolean}
- */
-function isPrivateRoot(root, uid) {
-  let st;
-  try {
-    st = lstatSync(root);
-  } catch {
-    return false;
-  }
-  return isPrivateDir(st, { uid });
-}
-
 /**
  * The redactor socket path: one per user, shared by every session of that user
  * (the daemon redacts each REQUESTER's env secrets). The daemon binds it 0600
@@ -81,7 +67,7 @@ function isPrivateRoot(root, uid) {
  * 1. `_AGENT_SANITIZER_REDACTOR_SOCKET` — explicit override.
  * 2. `$XDG_RUNTIME_DIR`, then `$CLAUDE_PLUGIN_DATA` — per-user directories no
  *    other uid can write, so a co-tenant cannot pre-create the socket dir under
- *    them. Taken only if isPrivateRoot passes and the path fits sun_path.
+ *    them. Taken only if privateDirAt passes and the path fits sun_path.
  * 3. `<tmpdir>/agent-sanitizer-redactor-<uid>` — on a shared /tmp a co-tenant
  *    can still pre-create it; the daemon then refuses to serve and the client
  *    refuses to connect (classifySocket), costing availability, never a secret.
@@ -94,7 +80,7 @@ export function resolveSocketPath(env, uid) {
   const override = readKnob("_AGENT_SANITIZER_REDACTOR_SOCKET", env);
   if (override) return override;
   for (const root of [env.XDG_RUNTIME_DIR, env.CLAUDE_PLUGIN_DATA]) {
-    if (!root || !isPrivateRoot(root, uid)) continue;
+    if (!root || !privateDirAt(root, { uid })) continue;
     const dir = join(root, "agent-sanitizer-redactor");
     if (Buffer.byteLength(dir) + 1 + TEMP_BIND_NAME_LENGTH <= SOCKET_PATH_MAX)
       return join(dir, "redactor.sock");

package/claude-hooks/lib/reveal.mjs

@@ -9,8 +9,8 @@
  * instructions" envelope (REVEAL_READ_ENVELOPE) re-attached when that file is read.
  * Read is not untrusted ingress, so a Read of the sidecar already bypasses
  * Layer 2 (no re-splice); the carve-out's job is to mark the bytes untrusted.
- * The store is content-addressed (identical output dedupes) and lives under a
- * throwaway tmp dir; _AGENT_SANITIZER_REVEAL_DIR overrides the location.
+ * The store is content-addressed (identical output dedupes) and lives under
+ * STATE_ROOT; _AGENT_SANITIZER_REVEAL_DIR overrides the location.
  *
  * The same dir also holds the per-splice SPAN files (`span-<key>.txt`): each
  * Layer-2 splice's (redacted) original, keyed by its placeholder's
@@ -25,17 +25,26 @@ import {
   mkdirSync,
   lstatSync,
   readdirSync,
+  rmSync,
   unlinkSync,
   openSync,
   readFileSync,
   closeSync,
   constants,
 } from "node:fs";
-import { tmpdir } from "node:os";
 import { join, resolve, sep } from "node:path";
-import { PROJECT_HASH, isPrivateDir, writeFileNoFollow } from "./hook-io.mjs";
+import {
+  PROJECT_HASH,
+  STATE_ROOT,
+  privateDirAt,
+  writeFileNoFollow,
+} from "./hook-io.mjs";
 import { readKnob } from "./knobs.mjs";
 
+/** The default reveal store's name, less the project hash that completes it. */
+const REVEAL_STORE_STEM = "agent-sanitizer-layer2-reveal-";
+const ANY_PROJECT_HASH = /^[0-9a-f]{8}$/u;
+
 /**
  * Where reveal sidecars are stored. Exported so the PreToolUse placeholder
  * advisory can name the directory a spliced original was saved under without
@@ -43,14 +52,13 @@ import { readKnob } from "./knobs.mjs";
  * @returns {string}
  */
 export function revealDir() {
-  // Project-keyed like every other $TMPDIR store: one unkeyed directory is shared
-  // by every project on the machine, so one project's sweep ages out another's
-  // spans and a rehydration that should have restored a placeholder fails closed
-  // instead. The 12-hex span KEY inside the directory is untouched — it is the
-  // published placeholder grammar, not a path detail.
+  // Under STATE_ROOT, so an OS temp cleaner cannot empty it under a live session.
+  // Project-keyed, so one project's sweep cannot age out another's spans — either
+  // loss fails a rehydration closed. The 12-hex span KEY inside is untouched: it
+  // is the published placeholder grammar, not a path detail.
   return (
     readKnob("_AGENT_SANITIZER_REVEAL_DIR") ??
-    join(tmpdir(), `agent-sanitizer-layer2-reveal-${PROJECT_HASH}`)
+    join(STATE_ROOT, `${REVEAL_STORE_STEM}${PROJECT_HASH}`)
   );
 }
 
@@ -63,7 +71,8 @@ export function revealDir() {
 export const REVEAL_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 
 /**
- * Delete this project's reveal sidecars and spans older than {@link REVEAL_TTL_MS}.
+ * Delete this project's reveal sidecars and spans older than {@link REVEAL_TTL_MS},
+ * and every other project's default store that holds nothing younger.
  *
  * Nothing else removes them: every entry is content-addressed, so a store that is
  * never swept grows for the life of the machine. Called from SessionStart, the one
@@ -71,6 +80,7 @@ export const REVEAL_TTL_MS = 7 * 24 * 60 * 60 * 1000;
  * @returns {void}
  */
 export function sweepStaleReveals() {
+  sweepAbandonedRevealStores();
   const dir = revealDir();
   // existsSync first: revealDirIsSafe CREATES the directory, and a sweep run on
   // every session start must not leave an empty store behind for a project that
@@ -93,6 +103,37 @@ export function sweepStaleReveals() {
   }
 }
 
+/**
+ * Remove OTHER projects' default reveal stores under STATE_ROOT once they are
+ * older than {@link REVEAL_TTL_MS}. Each project sweeps only its own store's
+ * files, and STATE_ROOT is persistent when it is the plugin data dir, so a
+ * project never reopened would keep its spans — tool output — for good. A
+ * store's mtime moves with every entry written or swept, and entries are
+ * write-once, so a store past the cutoff holds only files past it too.
+ * @returns {void}
+ */
+function sweepAbandonedRevealStores() {
+  const cutoff = Date.now() - REVEAL_TTL_MS;
+  for (const name of readdirSync(STATE_ROOT)) {
+    const path = join(STATE_ROOT, name);
+    const isStore =
+      name.startsWith(REVEAL_STORE_STEM) &&
+      ANY_PROJECT_HASH.test(name.slice(REVEAL_STORE_STEM.length));
+    if (!isStore || path === revealDir()) continue;
+    // privateDirAt: a co-tenant's store, or a symlink planted at the name, is
+    // not this uid's to remove.
+    if (!privateDirAt(path)) continue;
+    try {
+      if (lstatSync(path).mtimeMs < cutoff)
+        rmSync(path, { recursive: true, force: true });
+    } catch (err) {
+      // ENOENT: a parallel session swept this store between readdir and lstat.
+      if (/** @type {NodeJS.ErrnoException} */ (err).code !== "ENOENT")
+        throw err;
+    }
+  }
+}
+
 /**
  * Content-addressed path the pre-splice text of `content` is stored at.
  * @param {string} content
@@ -120,19 +161,7 @@ function revealDirIsSafe(dir) {
   } catch {
     return false;
   }
-  let st;
-  try {
-    st = lstatSync(dir);
-    /* c8 ignore start -- TOCTOU-race defense: after the mkdirSync above succeeds, dir
-       exists with accessible parents, so lstatSync can only throw if a co-tenant removes
-       or replaces it in the window between the two syscalls — unreachable in a
-       single-threaded test, yet load-bearing to keep persistReveal fail-closed on that
-       race rather than crashing. */
-  } catch {
-    return false;
-  }
-  /* c8 ignore stop */
-  return isPrivateDir(st);
+  return privateDirAt(dir);
 }
 
 /**

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/claude-hooks/scan-invisible-chars.mjs

@@ -495,10 +495,10 @@ async function runScanCli({ trace: sink, scan: runScan, sessionId }) {
   // sessions left instead — SessionStart is the once-per-session touchpoint the
   // sweep belongs on.
   sweepStaleSessions(sessionId);
-  // The other two $TMPDIR stores these hooks own. Both are content- or
-  // fingerprint-addressed with no natural owner to delete them, so without a
-  // sweep they grow for the life of the machine; SessionStart is the only
-  // touchpoint that runs once per session rather than once per tool call.
+  // The other two stores these hooks own (reveal under STATE_ROOT, confirm in
+  // $TMPDIR). Both are content- or fingerprint-addressed with no natural owner
+  // to delete them, so without a sweep they grow for the life of the machine;
+  // SessionStart is the only touchpoint that runs once per session.
   sweepStaleReveals();
   sweepStaleConfirms();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.66.3",
+  "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/hook-io.d.mts

@@ -294,6 +294,27 @@ export function safeErrMessage(err: unknown, cap?: number): string;
  * @returns {void}
  */
 export function emitHookResponse(hookEventName: string, fields: Record<string, unknown>): void;
+/**
+ * The directory the session-lifetime stores live under: the alert markers and
+ * findings (invisible-alert.mjs) and the reveal sidecars (reveal.mjs). They must
+ * outlive the longest session, which $TMPDIR does not promise — macOS's daily
+ * dirhelper job deletes anything in the per-user `/var/folders/.../T/` not
+ * accessed for 3 days, and a marker written at launch and only ever `lstat`ed
+ * then vanishes from a session still running, its absence read as "never ran".
+ *
+ * `$CLAUDE_PLUGIN_DATA/session-state` when both levels are private to this uid
+ * ({@link privateDirAt}): write on the plugin data dir alone is enough to swap
+ * `session-state` out. Each level is created 0700 when absent — so the
+ * launch-time InstructionsLoaded event and the first tool call resolve the same
+ * root whichever runs first — and checked BEFORE the next is created inside it,
+ * so a symlinked or shared plugin data dir never gets a directory planted in
+ * its target. A root this process cannot write — a read-only mount, an owner
+ * bit removed — is no root: every marker write would fail and read as "the
+ * event never fired". Otherwise $TMPDIR, where the stores' squat checks apply.
+ * @param {Record<string, string | undefined>} env
+ * @returns {string}
+ */
+export function resolveStateRoot(env: Record<string, string | undefined>): string;
 /**
  * Adopt a host's own cold-start marker path in place of the derived one, so a
  * host whose setup script already writes a marker under its own convention can
@@ -441,7 +462,7 @@ export function markerIsTrusted(path: string | null): boolean;
 export function currentUid(): number | null;
 /**
  * Whether `st` (an lstat result) is owned by this process's uid. THE ownership
- * predicate for every $TMPDIR store these hooks trust — a second spelling is how
+ * predicate for every state store these hooks trust — a second spelling is how
  * four call sites came to share the passwd-lookup crash {@link currentUid}
  * documents. False when the platform has no uid model: ownership that cannot be
  * proven is not granted. `uid` is a seam for a test that must model another
@@ -457,10 +478,11 @@ export function ownedByCurrentUser(st: {
  * Whether `st` (an lstat result) is a directory no untrusted uid can change: a
  * real directory (lstat, so a planted symlink is not one), owned by this uid —
  * or by root where `rootMayOwn` — with no group/other write bit. THE trust test
- * for every private directory these hooks keep in $TMPDIR. Write is the
- * property because creating, unlinking or replacing an entry needs write on its
- * parent: a co-tenant holding it can delete the finding a gate needs, swap a
- * reveal file, or rebind the redactor socket to a listener that redacts nothing.
+ * for every private directory these hooks keep, under STATE_ROOT or $TMPDIR.
+ * Write is the property because creating, unlinking or replacing an entry needs
+ * write on its parent: a co-tenant holding it can delete the finding a gate
+ * needs, swap a reveal file, or rebind the redactor socket to a listener that
+ * redacts nothing.
  * Root ownership is strictly stronger than ours, so a deployment may hand a dir
  * to root (`rootMayOwn`); with no uid model nothing is trusted, root included.
  * @param {{ isDirectory(): boolean, uid: number, mode: number }} st
@@ -476,6 +498,29 @@ export function isPrivateDir(st: {
     uid?: number | null;
     rootMayOwn?: boolean;
 }): boolean;
+/**
+ * Whether `path` is a private directory of this uid ({@link isPrivateDir}) —
+ * the directory counterpart of markerIsTrusted. `lstat`, so a symlink planted at
+ * a predictable path is judged on ITSELF: followed, it would let a co-tenant aim
+ * a reader at unrelated files this uid owns (the alert gate splices those bytes
+ * into a permission prompt). An absent path is simply not one.
+ * @param {string} path
+ * @param {{ uid?: number | null }} [opts]  as in {@link isPrivateDir}
+ * @returns {boolean}
+ */
+export function privateDirAt(path: string, opts?: {
+    uid?: number | null;
+}): boolean;
+/**
+ * Stamp a state file the caller has just trusted as used now, so a live
+ * session's state never looks idle to an age-based sweep — another session's
+ * {@link STATE_ROOT} sweep (mtime) or an OS temp cleaner (atime). `lutimes`, so
+ * a symlink swapped in after the caller's check is stamped itself, never its
+ * target. A path a parallel sweep removed after that check is simply gone.
+ * @param {string} path
+ * @returns {void}
+ */
+export function touchLiveState(path: string): void;
 /**
  * Create a presence sentinel at `path` without following a symlink a co-tenant
  * may have pre-planted there. These sentinels live at predictable, world-visible
@@ -585,6 +630,8 @@ export const DEFAULT_MISSING_PACKAGE_REMEDY: "reinstall the hook dependencies (p
 export const PROJECT_DIR: string;
 /** Short project digest keying this project's $TMPDIR store names. */
 export const PROJECT_HASH: string;
+/** {@link resolveStateRoot} for this process, resolved once at load. */
+export const STATE_ROOT: string;
 /**
  * The line a cold-start marker carries on its own to declare that its writer holds
  * an exclusive `flock` on the marker file for the whole install.

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

@@ -46,16 +46,21 @@ export function instructionsLoadedNoticeFile(sessionId?: string): string;
  * lazily-loaded instruction files are being scanned at all. Ownership-validated
  * like every other marker here: a co-tenant could otherwise plant the
  * predictable path and suppress the notice below, which is the whole signal that
- * nested files are going unscanned.
+ * nested files are going unscanned. A marker that is seen is stamped as used:
+ * it is written once at launch, so otherwise a session outliving
+ * MARKER_TTL_MS would have it swept by another session's SessionStart and read
+ * its absence as the event never having fired.
  * @param {string} [sessionId]
  * @returns {boolean}
  */
 export function instructionsLoadedSeen(sessionId?: string): boolean;
 /**
- * Delete this project's artifacts from OTHER sessions once they are older than
+ * Delete OTHER sessions' artifacts, of every project, once they are older than
  * the TTL. The current session's own prefix is skipped, so the sweep can never
  * answer its own question wrong; every other session's files are past history
- * that nothing reads.
+ * that nothing reads — a live one keeps its marker and findings fresh on read.
+ * Every project, because STATE_ROOT may be persistent: a project never reopened
+ * would otherwise keep its artifacts for good.
  *
  * This replaces the destructive SessionStart clear: with the store session-keyed
  * there is nothing to reset, only old state to age out.
@@ -65,7 +70,7 @@ export function instructionsLoadedSeen(sessionId?: string): boolean;
 export function sweepStaleSessions(sessionId?: string): void;
 /**
  * Record that the InstructionsLoaded scanner engaged. Symlink-safe presence
- * write (see writeSentinelFile) at a predictable $TMPDIR path.
+ * write (see writeSentinelFile) at a predictable STATE_ROOT path.
  *
  * The event fires once per instruction file loaded, so the already-recorded case
  * returns without a write — and the stale-session sweep rides the FIRST fire of
@@ -77,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}
  */
@@ -100,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.
@@ -136,14 +141,14 @@ export function recordInstructionsLoadedNotice(sessionId?: string): void;
  * The alert findings if invisible-char injection was detected in instruction
  * files and couldn't be auto-cleaned, else null.
  *
- * The store is a DIRECTORY of one file per finding, all at predictable,
- * world-visible $TMPDIR paths, so both the directory and every entry in it are
- * attacker-plantable: trust the directory only when it is a real directory this
- * uid owns (a symlink would let a co-tenant aim this reader at unrelated files),
- * each entry only when markerIsTrusted confirms a regular file this uid owns,
- * then scrub the bytes through Layer-1 before any caller splices them into a
- * reason — the report would otherwise carry ANSI/invisible spoofing into the
- * model's context.
+ * The store is a DIRECTORY of one file per finding, all at predictable
+ * STATE_ROOT paths (world-visible in the $TMPDIR fallback), so both the
+ * directory and every entry in it are attacker-plantable: trust the directory
+ * only when it is a real directory this uid owns (a symlink would let a
+ * co-tenant aim this reader at unrelated files), each entry only when
+ * markerIsTrusted confirms a regular file this uid owns, then scrub the bytes
+ * through Layer-1 before any caller splices them into a reason — the report
+ * would otherwise carry ANSI/invisible spoofing into the model's context.
  * This session's store AND the shared `no-session` fallback, because a hook that
  * faults BEFORE it can parse its payload has no session identity to key by: its
  * finding lands in the fallback, and a strictly session-keyed read would leave
@@ -163,7 +168,7 @@ export function invisibleCharAlert(sessionId?: string): string | null;
  * 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.
+ * predictable STATE_ROOT path, world-visible in the $TMPDIR fallback.
  * @param {string} text
  * @param {string} [sessionId]
  * @returns {boolean} whether the finding was recorded
@@ -172,9 +177,10 @@ export function appendAlert(text: string, sessionId?: string): boolean;
 /**
  * True once the gate has surfaced its blocking ask this session. Validates
  * ownership (not mere existence): a co-tenant could pre-create the ack at its
- * predictable $TMPDIR path to permanently suppress the one-time blocking ask down
- * to the passive reminder, so trust the marker only when it is a regular file
- * this uid wrote (markerIsTrusted), mirroring how acknowledgeAlert writes it.
+ * predictable STATE_ROOT path to permanently suppress the one-time blocking ask
+ * down to the passive reminder, so trust the marker only when it is a regular
+ * file this uid wrote (markerIsTrusted), mirroring how acknowledgeAlert writes
+ * it.
  *
  * On a host that exports no session id every session shares the fallback prefix,
  * so the ack has no session to end with and would suppress the one-time blocking
@@ -211,6 +217,9 @@ export function gateReminderContext(): string;
 /**
  * The path prefix every alert artifact of this PROJECT shares. Never a file
  * itself — only {@link sessionPrefix} and the sweep read it — so that one
- * `startsWith` covers every artifact the sweep must age out.
+ * `startsWith` covers every artifact the sweep must age out. Under STATE_ROOT,
+ * not $TMPDIR itself: an OS temp cleaner deleting a live session's marker would
+ * read as the InstructionsLoaded scan never having run, and deleting its
+ * findings would lift the gate mid-session.
  */
 export const ALERT_BASE: string;

package/types/claude-hooks/lib/redactor-client.d.mts

@@ -6,7 +6,7 @@
  * 1. `_AGENT_SANITIZER_REDACTOR_SOCKET` — explicit override.
  * 2. `$XDG_RUNTIME_DIR`, then `$CLAUDE_PLUGIN_DATA` — per-user directories no
  *    other uid can write, so a co-tenant cannot pre-create the socket dir under
- *    them. Taken only if isPrivateRoot passes and the path fits sun_path.
+ *    them. Taken only if privateDirAt passes and the path fits sun_path.
  * 3. `<tmpdir>/agent-sanitizer-redactor-<uid>` — on a shared /tmp a co-tenant
  *    can still pre-create it; the daemon then refuses to serve and the client
  *    refuses to connect (classifySocket), costing availability, never a secret.

package/types/claude-hooks/lib/reveal.d.mts

@@ -6,7 +6,8 @@
  */
 export function revealDir(): string;
 /**
- * Delete this project's reveal sidecars and spans older than {@link REVEAL_TTL_MS}.
+ * Delete this project's reveal sidecars and spans older than {@link REVEAL_TTL_MS},
+ * and every other project's default store that holds nothing younger.
  *
  * Nothing else removes them: every entry is content-addressed, so a store that is
  * never swept grows for the life of the machine. Called from SessionStart, the one