agent-sanitizer 2.35.1 → 2.37.0

package/README.md

@@ -151,14 +151,20 @@ Per-vector detail in [`THREAT-MODEL.md`](./THREAT-MODEL.md).
 
 ## What installing entails
 
-Installing the plugin puts four hooks on every session, and this is what they
+Installing the plugin puts five hooks on every session, and this is what they
 buy you:
 
 1. Your `CLAUDE.md`, `AGENTS.md` and the context markdown under `.claude/` are
-   scanned at session start for hidden-Unicode payloads and auto-cleaned where
-   possible. Only the subdirectories Claude Code loads as context are walked, so
-   bulk data parked under `.claude/` (`worktrees/`, caches, transcripts) does not
-   slow startup.
+   scanned for hidden-Unicode payloads and auto-cleaned where possible. Session
+   start covers what Claude Code loads at launch — the project root's own
+   instruction files, the `CLAUDE.md` chain above it, and the root `.claude/`
+   context subdirectories (rules, skills, agents), never bulk data parked there
+   (`worktrees/`, caches, transcripts). Everything else Claude Code loads — a
+   subdirectory's `CLAUDE.md`, a path-scoped rule, an `@import`, your
+   user-global `~/.claude/CLAUDE.md` and global rules — is scanned from the
+   bytes the load event carries, at the moment it loads, so startup costs no
+   tree walk at all. Only files inside the project are rewritten: one shared
+   with every other project on the machine is reported, not edited.
 2. Prompts carrying payload-capable invisible or ANSI characters are blocked
    before they reach the model; pasted terminal color passes with a note.
 3. Look-alike glyphs in tool inputs are folded to ASCII, so a Cyrillic `а` can't
@@ -191,8 +197,9 @@ working one. Neither posture touches what a sanitizer that RAN decided (see
 
 ## Using it with Claude Code
 
-The plugin installed above puts four hooks on the tool stream: tool input, tool
-output, user prompts, and a session-start scan of the instruction files. It
+The plugin installed above puts five hooks on the tool stream: tool input, tool
+output, user prompts, a session-start scan of the instruction files that load at
+launch, and a per-file scan of every instruction file loaded after that. It
 needs only `python3` on PATH, for Layer 4 — the plugin ships the engine itself
 (see [What installing entails](#what-installing-entails)).
 
@@ -216,7 +223,7 @@ guessing if the marketplace was never added. To pull a release by hand instead:
 
 `plugin/README.md` has the managed-settings form for enabling it fleet-wide.
 
-To wire them yourself instead, one entry dispatches all four modes on `--hook=`:
+To wire them yourself instead, one entry dispatches every mode on `--hook=`:
 
 ```jsonc
 // settings.json — one entry per event; PreToolUse/PostToolUse also take "matcher": "*"
@@ -226,12 +233,13 @@ To wire them yourself instead, one entry dispatches all four modes on `--hook=`:
 }
 ```
 
-| Event              | `--hook=`              |
-| ------------------ | ---------------------- |
-| `UserPromptSubmit` | `sanitize-user-prompt` |
-| `PreToolUse`       | `pretooluse-sanitize`  |
-| `PostToolUse`      | `sanitize-output`      |
-| `SessionStart`     | `scan-invisible-chars` |
+| Event                | `--hook=`                  |
+| -------------------- | -------------------------- |
+| `UserPromptSubmit`   | `sanitize-user-prompt`     |
+| `PreToolUse`         | `pretooluse-sanitize`      |
+| `PostToolUse`        | `sanitize-output`          |
+| `SessionStart`       | `scan-invisible-chars`     |
+| `InstructionsLoaded` | `scan-loaded-instructions` |
 
 `require.resolve("agent-sanitizer/claude-hooks")` gives the path without
 hardcoding a layout. Importing the module rather than spawning it is a no-op.
@@ -259,22 +267,23 @@ singleton, and two copies in one bundle double-fire the inlined CLIs.
 
 <!-- exports-table: rows are asserted to equal package.json's ./claude-hooks* exports by test/claude-hooks-exports.test.mjs -->
 
-| Subpath                             | What it is                                                                                 |
-| ----------------------------------- | ------------------------------------------------------------------------------------------ |
-| `claude-hooks`                      | The `--hook=` CLI dispatcher all four hooks are spawned through                            |
-| `claude-hooks/pretooluse-sanitize`  | PreToolUse orchestrator: invisible-char gate, confusable folding, stego strip, rehydration |
-| `claude-hooks/sanitize-output`      | PostToolUse pipeline: Layers 1–4 over tool output, plus the host-extension bag             |
-| `claude-hooks/sanitize-user-prompt` | UserPromptSubmit verdict on payload-capable invisible/ANSI content                         |
-| `claude-hooks/scan-invisible-chars` | SessionStart scan of `CLAUDE.md` / `.claude/` markdown                                     |
-| `claude-hooks/lib/hook-io`          | Shared hook I/O: the lazy-module registry, the CLI slot, deadlines, the hookgate marker    |
-| `claude-hooks/lib/control-plane`    | Bridge to `agent-control-plane-core` and the shared judge-CLI transport                    |
-| `claude-hooks/lib/authored-content` | Stego + terminal-control stripping of the fields the MODEL authors                         |
-| `claude-hooks/lib/env-config`       | The env-bound secret vocabulary the Layer-4 pre-gate and the redactor client share         |
-| `claude-hooks/lib/invisible-alert`  | Cross-hook alert state for uncleanable invisible-char injection in instruction files       |
-| `claude-hooks/lib/redactor-client`  | Client for the long-lived `agent-secret-redactor-daemon` (Layer 4's transport)             |
-| `claude-hooks/lib/reveal`           | The Layer-2 sidecar that lets the model re-read what the HTML splice removed               |
-| `claude-hooks/lib/secret-annotate`  | The cheap deterministic Layer-4 pre-gate checks around the daemon call                     |
-| `claude-hooks/lib/trace`            | The opt-in structured trace channel every layer announces itself on                        |
+| Subpath                                 | What it is                                                                                 |
+| --------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `claude-hooks`                          | The `--hook=` CLI dispatcher every hook is spawned through                                 |
+| `claude-hooks/pretooluse-sanitize`      | PreToolUse orchestrator: invisible-char gate, confusable folding, stego strip, rehydration |
+| `claude-hooks/sanitize-output`          | PostToolUse pipeline: Layers 1–4 over tool output, plus the host-extension bag             |
+| `claude-hooks/sanitize-user-prompt`     | UserPromptSubmit verdict on payload-capable invisible/ANSI content                         |
+| `claude-hooks/scan-invisible-chars`     | SessionStart scan of the instruction files that load at launch                             |
+| `claude-hooks/scan-loaded-instructions` | InstructionsLoaded scan of each instruction file as Claude Code loads it                   |
+| `claude-hooks/lib/hook-io`              | Shared hook I/O: the lazy-module registry, the CLI slot, deadlines, the hookgate marker    |
+| `claude-hooks/lib/control-plane`        | Bridge to `agent-control-plane-core` and the shared judge-CLI transport                    |
+| `claude-hooks/lib/authored-content`     | Stego + terminal-control stripping of the fields the MODEL authors                         |
+| `claude-hooks/lib/env-config`           | The env-bound secret vocabulary the Layer-4 pre-gate and the redactor client share         |
+| `claude-hooks/lib/invisible-alert`      | Cross-hook alert state for uncleanable invisible-char injection in instruction files       |
+| `claude-hooks/lib/redactor-client`      | Client for the long-lived `agent-secret-redactor-daemon` (Layer 4's transport)             |
+| `claude-hooks/lib/reveal`               | The Layer-2 sidecar that lets the model re-read what the HTML splice removed               |
+| `claude-hooks/lib/secret-annotate`      | The cheap deterministic Layer-4 pre-gate checks around the daemon call                     |
+| `claude-hooks/lib/trace`                | The opt-in structured trace channel every layer announces itself on                        |
 
 Only `plugin-hooks` itself is unexported under its own name — it is reachable as
 the bare `claude-hooks` entry above.
@@ -334,7 +343,8 @@ await cliMain({ trace: (event, fields) => myChannel.emit(event, fields) });
 ```
 
 The sink rides each hook's options bag — `cliMain({trace})` on
-`scan-invisible-chars` and `pretooluse-sanitize`, the extension bag's `trace` on
+`scan-invisible-chars`, `scan-loaded-instructions` and `pretooluse-sanitize`,
+the extension bag's `trace` on
 `sanitize-output`, `main(read, write, {trace})` on `sanitize-user-prompt`. It
 receives the same `TraceEvent` names the default emits, and it **replaces** the
 default rather than running alongside it — the package channel goes silent, so

package/THREAT-MODEL.md

@@ -281,6 +281,22 @@ ASCII, zero-width **binary**), and catches scattered payloads below the long-run
 threshold. `cleanFile` strips the payload in place (Layer-1 strip), failing loud
 if a contaminated file cannot be rewritten.
 
+As Claude Code hooks the coverage is split to match how Claude Code loads these
+files. `scan-invisible-chars` (SessionStart) scans the launch set — the project
+root's own instruction files, the `CLAUDE.md` chain above it, and the root
+`.claude/` context subdirectories — and `scan-loaded-instructions`
+(InstructionsLoaded) scans every other instruction file — including the
+user-global `~/.claude` memory and rules, which load into every session on the
+machine — reading the one path the event names, at the moment it loads. The second cannot block: the file is already in
+context when it fires, so its neutralization is to strip the payload from disk
+(so no reload re-reads it) and tell the model to treat what it just read as
+untrusted data. Auto-cleaning is confined to `CLAUDE_PROJECT_DIR` in both — an
+ancestor file, or one under `~/.claude`, is shared with every other project on
+the machine, so it is reported through the cross-hook alert and never
+rewritten. A Claude Code build that emits
+no `InstructionsLoaded` event loses the lazy half entirely; the PreToolUse gate
+says so once per session rather than leaving the gap silent.
+
 ## User-prompt verdict
 
 `./prompt` classifies a submitted prompt as **pass / pass-with-note / block** on

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

@@ -45,6 +45,7 @@ export const FAULT_POLICY_HOOKS = Object.freeze([
   "sanitize-output",
   "sanitize-user-prompt",
   "scan-invisible-chars",
+  "scan-loaded-instructions",
 ]);
 
 /**

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

@@ -186,6 +186,7 @@ export const HookEvent = Object.freeze({
   POST_TOOL_USE: "PostToolUse",
   USER_PROMPT_SUBMIT: "UserPromptSubmit",
   SESSION_START: "SessionStart",
+  INSTRUCTIONS_LOADED: "InstructionsLoaded",
 });
 
 /** Claude Code permissionDecision verdicts. */

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

@@ -10,14 +10,15 @@
  * Both hooks reach the state through this module so the paths and the trust rule
  * have one definition.
  */
-import { readFileSync } from "node:fs";
+import { lstatSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
 import { createHash } from "node:crypto";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { tmpdir } from "node:os";
 import {
   lazyImport,
   markerIsTrusted,
   scrubUntrustedText,
+  writeFileNoFollow,
   writeSentinelFile,
 } from "./hook-io.mjs";
 
@@ -51,6 +52,128 @@ export const ALERT_FILE = join(
 // ALERT_FILE so each fresh session re-asks once.
 export const ALERT_ACK_FILE = `${ALERT_FILE}.acked`;
 
+/**
+ * Marker the InstructionsLoaded scanner writes on every fire, so another hook
+ * can tell whether that event is being scanned at all this session.
+ *
+ * Keyed by the SESSION, and never cleared at SessionStart like the alert pair
+ * above (a later session sweeps it once it is older than the TTL):
+ * nothing pins the order of SessionStart against the InstructionsLoaded events
+ * Claude Code fires for the files it loads at launch, so a clear could erase a
+ * marker written moments earlier and produce the notice on a session that IS
+ * covered. Session-keyed, the question each session asks is answered by that
+ * session's own file and no ordering matters. A host that exports no session id
+ * falls back to one shared name — where the marker can outlive its session, and
+ * a later session on a host that stopped emitting the event stays quiet.
+ * @param {string} [sessionId]
+ * @returns {string}
+ */
+export function instructionsLoadedFile(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.
+  const key =
+    (sessionId ?? "").replace(/[^A-Za-z0-9._-]/gu, "_") || "no-session";
+  return `${ALERT_FILE}.instructions-loaded.${key}`;
+}
+
+/**
+ * Companion marker: the notice below has been surfaced this session.
+ * @param {string} [sessionId]
+ * @returns {string}
+ */
+export function instructionsLoadedNoticeFile(sessionId) {
+  return `${instructionsLoadedFile(sessionId)}.noticed`;
+}
+
+/**
+ * Whether the InstructionsLoaded scanner has run this session — i.e. whether the
+ * 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.
+ * @param {string} [sessionId]
+ * @returns {boolean}
+ */
+export function instructionsLoadedSeen(sessionId) {
+  return markerIsTrusted(instructionsLoadedFile(sessionId));
+}
+
+/** How long a past session's marker is kept before the next session sweeps it. */
+const MARKER_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * Delete this project's session markers older than the TTL. Only PAST sessions'
+ * files are candidates — the current session's was just written, so the sweep
+ * cannot answer its own question wrong.
+ * @param {string} keep  the marker path this session owns
+ * @returns {void}
+ */
+function sweepStaleMarkers(keep) {
+  const dir = tmpdir();
+  const prefix = `${basename(ALERT_FILE)}.instructions-loaded.`;
+  const cutoff = Date.now() - MARKER_TTL_MS;
+  for (const name of readdirSync(dir)) {
+    if (!name.startsWith(prefix)) continue;
+    const path = join(dir, name);
+    if (path === keep || path === `${keep}.noticed`) continue;
+    // lstat, not stat: a squatted symlink at a predictable $TMPDIR path must be
+    // judged on ITSELF, not on whatever it points at. unlink removes the link.
+    if (lstatSync(path).mtimeMs < cutoff) unlinkSync(path);
+  }
+}
+
+/**
+ * Record that the InstructionsLoaded scanner engaged. Symlink-safe presence
+ * write (see writeSentinelFile) at a predictable $TMPDIR path.
+ *
+ * The event fires once per instruction file loaded, so the already-recorded case
+ * returns without a write — and the stale-marker sweep rides the FIRST fire of a
+ * session, where one readdir is paid once rather than per loaded file.
+ * @param {string} [sessionId]
+ * @returns {void}
+ */
+export function recordInstructionsLoaded(sessionId) {
+  const marker = instructionsLoadedFile(sessionId);
+  if (markerIsTrusted(marker)) return;
+  writeSentinelFile(marker);
+  sweepStaleMarkers(marker);
+}
+
+/**
+ * The one-time context line for a session where no InstructionsLoaded scan ran,
+ * or null when the scan has been seen or the notice was already surfaced this
+ * session. Records the notice as it hands it out, so it rides on ONE tool call
+ * rather than every one — the per-call repeat is what trains a reader to skip it.
+ *
+ * The loss it names is real and otherwise invisible: SessionStart scans the
+ * instruction files that load at launch, and everything a subdirectory loads
+ * later is scanned by the event. No scan, and nothing says so.
+ *
+ * The notice names the OBSERVABLE — no scan ran — and both of its causes, because
+ * the marker cannot tell a host that never emits the event from an operator who
+ * switched the hook off in AGENT_SANITIZER_DISABLED_HOOKS, and asserting the
+ * first would send an operator who chose the second to the wrong fix.
+ * @param {string} [sessionId]  the harness's session identity, so the answer
+ *   belongs to THIS session (see instructionsLoadedFile)
+ * @returns {string | null}
+ */
+export function instructionsLoadedGapNotice(sessionId) {
+  if (instructionsLoadedSeen(sessionId)) return null;
+  const noticeFile = instructionsLoadedNoticeFile(sessionId);
+  if (markerIsTrusted(noticeFile)) return null;
+  writeSentinelFile(noticeFile);
+  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 both causes: a Claude Code that does not emit " +
+    "the event (upgrading restores the coverage), or scan-loaded-instructions " +
+    "switched off in AGENT_SANITIZER_DISABLED_HOOKS."
+  );
+}
+
 /**
  * The alert findings if invisible-char injection was detected in instruction
  * files and couldn't be auto-cleaned, else null. ALERT_FILE lives at a predictable,
@@ -67,6 +190,27 @@ export function invisibleCharAlert() {
   return scrubUntrustedText(raw, applyLayer1);
 }
 
+/**
+ * Add `text` to the alert the PreToolUse gate surfaces, keeping whatever is
+ * already there.
+ *
+ * Appending, where the SessionStart scanner TRUNCATES: that scan runs once and
+ * owns the session's reset, while an instruction file loaded mid-session is one
+ * more finding on top of whatever the launch scan left — a truncating write here
+ * would silently drop the earlier report. Symlink-refusing (writeFileNoFollow)
+ * and ownership-checked on read, because ALERT_FILE sits at a predictable,
+ * world-visible $TMPDIR path; a foreign or squatted file reads as empty and is
+ * replaced rather than appended to.
+ * @param {string} text
+ * @returns {void}
+ */
+export function appendAlert(text) {
+  const existing = markerIsTrusted(ALERT_FILE)
+    ? readFileSync(ALERT_FILE, "utf-8")
+    : "";
+  writeFileNoFollow(ALERT_FILE, existing + text + "\n");
+}
+
 /**
  * True once the gate has surfaced its blocking ask this session. Validates
  * ownership (not mere existence): a co-tenant could pre-create ALERT_ACK_FILE at its

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

@@ -0,0 +1,51 @@
+/**
+ * The operator-facing report for hidden-Unicode findings in instruction files.
+ *
+ * Its own module because two hooks render it — the SessionStart scan of the
+ * files that load at launch, and the InstructionsLoaded scan of every file
+ * loaded after that — and a second copy would drift in exactly the way that
+ * matters: the framing that keeps a decoded payload from reading as an
+ * instruction (see decodeRun's `untrusted data` prefix) is part of the report,
+ * not decoration on it.
+ */
+
+/**
+ * @param {Array<{
+ *   file: string,
+ *   findings: Array<{ line: number | null, charCount: number, method: string, decoded: string }>,
+ * }>} allFindings
+ * @returns {string}
+ */
+export function formatReport(allFindings) {
+  const BAR = "━".repeat(52);
+  const lines = [
+    "",
+    `━━━ INVISIBLE CHARACTER INJECTION DETECTED ${BAR.slice(0, 11)}`,
+    "",
+    "Invisible Unicode in instruction files can hijack the model’s behavior",
+    "(skill invocation, tool use, instruction override). This commonly",
+    "happens when copy-pasting content from the internet.",
+    "",
+    "These files are loaded directly as context, bypassing PostToolUse",
+    "sanitization, so the invisible characters reach the model raw.",
+    "",
+  ];
+
+  for (const { file, findings } of allFindings) {
+    lines.push(`  ${file}:`);
+    for (const finding of findings) {
+      // `line` is null for the whole-file scattered-chars finding, which is
+      // not tied to any single line.
+      const where =
+        finding.line === null ? "Whole file" : `Line ${finding.line}`;
+      lines.push(
+        `    ${where}: ${finding.charCount} invisible chars (${finding.method})`,
+      );
+      lines.push(`    Decodes to: ${JSON.stringify(finding.decoded)}`);
+    }
+    lines.push("");
+  }
+
+  lines.push(BAR);
+  return lines.join("\n");
+}

package/claude-hooks/lib/trace.mjs

@@ -35,6 +35,7 @@ import { appendFileSync } from "node:fs";
 export const TraceEvent = Object.freeze({
   HOOK_RAN: "hook_ran",
   SCAN_INVISIBLE_CHARS_RAN: "scan_invisible_chars_ran",
+  SCAN_LOADED_INSTRUCTIONS_RAN: "scan_loaded_instructions_ran",
 });
 
 const LEVELS = Object.freeze({ off: 0, info: 1, debug: 2 });

package/claude-hooks/plugin-hooks.mjs

@@ -1,7 +1,7 @@
 /**
- * Entry point: ALL FOUR sanitization hooks behind one dispatch flag. The four
- * hooks share almost the entire package graph, so one bundle per hook would ship
- * four near-identical copies; a single entry with a `--hook=<name>` flag
+ * Entry point: EVERY sanitization hook behind one dispatch flag. The hooks
+ * share almost the entire package graph, so one bundle per hook would ship a
+ * near-identical copy per hook; a single entry with a `--hook=<name>` flag
  * selecting the hook ships the graph once (hooks.json passes the flag).
  *
  * The plugin's shipped artifact is the esbuild BUNDLE with every package inlined
@@ -33,7 +33,7 @@ import {
 const HOOK_NAME = "plugin-hooks";
 
 // The dispatcher's entry in the one posture table (lib/hook-fault.mjs). It
-// answers no single event — it is the binder in front of all four — so it
+// answers no single event — it is the binder in front of all of them — so it
 // carries no stdout envelope and both arms are process-level.
 //
 // BOTH ARMS BLOCK, and that is the declaration, not an oversight. The
@@ -41,7 +41,7 @@ const HOOK_NAME = "plugin-hooks";
 // mode is static wiring corruption, which means no hook runs at all, silently,
 // for the life of the install — there is no run to degrade. Stating it here (and
 // pinning it in plugin/test/plugin-bundle.test.mjs) is the point of the table:
-// the arm that ignores the knob does so on the record, next to the four that
+// the arm that ignores the knob does so on the record, next to the ones that
 // honor it, instead of by hard-exiting past the question.
 //
 // Exit 2 is the one non-zero code Claude Code treats as BLOCKING: it blocks
@@ -161,6 +161,16 @@ const HOOKS = {
       await cliMain();
     },
   },
+  "scan-loaded-instructions": {
+    event: HookEvent.INSTRUCTIONS_LOADED,
+    run: async () => {
+      const { cliMain } =
+        /** @type {typeof import("./scan-loaded-instructions.mjs")} */ (
+          await import("./scan-loaded-instructions.mjs")
+        );
+      await cliMain();
+    },
+  },
 };
 
 /** The dispatchable hook names, in hooks.json's spelling. */

package/claude-hooks/pretooluse-sanitize.mjs

@@ -55,6 +55,7 @@ import {
   gateReminderContext,
   alertAcknowledged,
   acknowledgeAlert,
+  instructionsLoadedGapNotice,
 } from "./lib/invisible-alert.mjs";
 import {
   sanitizeAuthoredContent,
@@ -460,6 +461,14 @@ export async function buildPreToolUseResponse(
 
   const { tool_name: tool, tool_input: toolInput } = input;
 
+  // Coverage notice, once per session: with no InstructionsLoaded scan running,
+  // every instruction file loaded from a subdirectory reaches the model
+  // unscanned, and the SessionStart scan — which covers only what loads at
+  // launch — cannot see the loss. Reported here because this is the first hook
+  // that runs after the loads would have happened.
+  const gapNotice = instructionsLoadedGapNotice(input.session_id);
+  if (gapNotice !== null) contexts.push(gapNotice);
+
   // Layers 2-4, run by the declared pipeline: the driver — not this call order —
   // is what keeps the confusable fold's soundness precondition true once an
   // erasing layer follows it (see lib/layer-pipeline.mjs).