agent-sanitizer 2.66.2 → 2.66.4

package/THREAT-MODEL.md

@@ -797,7 +797,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 +927,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

@@ -21,16 +21,19 @@ import {
 } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { basename, join } from "node:path";
-import { homedir, tmpdir } from "node:os";
+import { homedir } from "node:os";
 import {
   hookgateMarkerPath,
   lazyImport,
   markerIsTrusted,
-  isPrivateDir,
+  ownedByCurrentUser,
+  privateDirAt,
   probeSetupAlive,
   PROJECT_DIR,
   PROJECT_HASH,
   scrubUntrustedText,
+  STATE_ROOT,
+  touchLiveState,
   writeFileNoFollow,
   writeSentinelFile,
 } from "./hook-io.mjs";
@@ -59,15 +62,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 +102,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 +154,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 +206,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 +230,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 +243,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 +274,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 +287,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 +317,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
@@ -534,14 +540,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 +566,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 +592,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 +606,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 +621,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 +648,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/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.2",
+  "version": "2.66.4",
   "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
@@ -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