agent-sanitizer 2.23.1 → 2.24.0

package/README.md

@@ -55,7 +55,7 @@ the callback you inject for the agent-specific concern; `—` is a pure transfor
 | 3   | `/html`         | Detect exfil-shaped URLs (payloads in query/path, embedded creds, `data:`/`javascript:`, off-origin redirects). Reports only.                                               | —                           |
 | 4   | `/confusables`  | Fold look-alike glyphs in tool-call input (paths, commands) to ASCII, closing a cross-script deny-rule bypass. Gated per token, so non-Latin prose passes through unfolded. | `scan`                      |
 | 5   | `/instructions` | Scan/auto-clean `CLAUDE.md`, `AGENTS.md`, `SKILL.md`, etc., decoding Unicode-tag + zero-width-binary payloads.                                                              | `fs` (direct)               |
-| 6   | `/prompt`       | Classify a prompt pass / SGR-note / block on payload-capable invisible/ANSI content.                                                                                        | —                           |
+| 6   | `/prompt`       | Classify a prompt pass / note / block on payload-capable invisible/ANSI content (inert escapes get the note).                                                               | —                           |
 | 7   | `/output`       | Run Layers 1–4 over structured tool output, preserving shape. The Layer-5 slot takes a delete-only filter.                                                                  | `redact`, `filterInjection` |
 | 8   | `/rehydrate`    | Re-anchor a model Edit composed from the _sanitized_ view back onto real bytes; deny anything ambiguous or secret-exposing.                                                 | `io`                        |
 | —   | `/view-map`     | Pure offset/text machinery mapping a file's on-disk bytes ↔ the sanitized view (Layer-1 deletions, Layer-4 redactions). No I/O — consumed by `/rehydrate`.                  | —                           |
@@ -104,8 +104,11 @@ for a later span (overlapping spans resolve first-match-wins).
 Installing the plugin puts four hooks on every session, and this is what they
 buy you:
 
-1. Your `CLAUDE.md`, `AGENTS.md` and `.claude/` markdown are scanned at session
-   start for hidden-Unicode payloads and auto-cleaned where possible.
+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.
 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

package/THREAT-MODEL.md

@@ -35,6 +35,22 @@ table](./README.md#entry-points) maps each to its import.
   Sinhala) or inside an emoji ZWJ sequence. The carve-out fires only when **both**
   neighbors clearly belong to the context, and it is disabled once the total
   invisible count crosses a scatter floor—over-stripping beats under-stripping.
+- **Blank fillers doing real work in their own script**: the Braille blank
+  (U+2800) beside a real cell, a Hangul filler beside a real jamo/syllable. A
+  _run_ of fillers has only fillers for neighbors, so it fails the anchor and is
+  stripped. Because U+2800 _is_ the word space of Unicode Braille and a Hangul
+  filler completes a defective syllable, these are far denser in genuine text
+  than joiners are, so they carry their own document-wide allowance—one
+  preserved blank per two visible anchor-script characters, above a floor—rather
+  than drawing on the joiner/selector preserve budget. The allowance is counted
+  per script (a blank never anchors cross-script, so Korean prose must not fund
+  a Braille channel). Past that ratio no blank of that script is preserved
+  (never half-spaced) and all of them count as payload, which is the density an
+  alternating `syllable filler …` channel needs. Contracted (grade-2) Braille
+  sits closest to the boundary: alphabet wordsigns are single cells, so a
+  passage of mostly one-cell words approaches 1:1 and is stripped like the
+  channel—an accepted residual false positive inherent to a density rule, not a
+  gap, and not worth widening the ratio to reach.
 
 **Reassembly hardening.** The two passes feed each other in _both_ directions:
 stripping an invisible char can reconstitute an ANSI escape its split had
@@ -50,9 +66,18 @@ visible text; a final unconditional sweep after the loop keeps the
 no-raw-introducer guarantee independent of the iteration bound. The result
 carries no raw ANSI introducer for _any_ input, and re-cleaning it reproduces
 it exactly—the idempotence the Edit-repair rehydrator's soundness gate assumes.
-One tokenizer answers every ANSI question (what to splice, and whether the only
-escape content is display-only SGR colour), so the stripper and the operator
-warning cannot disagree about what a sequence is. OSC strings (titles,
+One tokenizer answers every ANSI question (what to splice, and whether what was
+removed was INERT—display-only SGR colour, or a lone 7-bit `ESC` that opened
+nothing at all), so the stripper and the operator warning cannot disagree about
+what a sequence is. That inert/injection-shaped split is what keeps the warning
+worth reading: a stray `ESC` sitting in a file is reported as a terse note, while
+a cursor move, an erase, an OSC string, or a raw C1 introducer (which no
+legitimate UTF-8 text carries, and which includes the DCS/SOS/PM/APC string
+introducers) keeps the WARNING. An `ESC` that _opened_ a CSI it never completed
+stays loud too: a terminal's CSI parser is stateful and keeps consuming what
+follows until a final byte arrives, so `ESC[12 world` shows the human `orld`
+while the model reads every word—the same model-sees/human-sees divergence a
+complete sequence buys. OSC strings (titles,
 clickable-hyperlink URLs) are consumed as a
 whole, for every terminator form—ST (`ESC\` or 8-bit C1 ST U+009C) and the
 legacy BEL—and for the 8-bit C1 OSC introducer (U+009D); an _unterminated_ OSC
@@ -164,13 +189,15 @@ if a contaminated file cannot be rewritten.
 `./prompt` classifies a submitted prompt as **pass / pass-with-note / block** on
 payload-capable invisible Unicode and ANSI. A prompt-submission channel usually
 cannot rewrite the prompt in place, so the only neutralization is to block.
-One carve-out: a prompt whose only escape content is display-only SGR color
-passes with a note (pasting colored terminal output is the common case, and SGR
-cannot move the cursor, erase, or carry an OSC payload). The SGR-only test
-gates on both the 7-bit ESC (`U+001B`) introducer and the whole 8-bit C1
-control block (U+0080–U+009F)—not just the CSI byte (`U+009B`)—so a
-C1-introduced cursor-move, erase, or OSC/DCS/SOS/PM/APC string is never
-mistaken for benign color.
+One carve-out: a prompt whose only escape content is INERT passes with a note —
+display-only SGR color, and/or a 7-bit `ESC` that completes no sequence (a log
+line cut mid-escape). Pasting colored terminal output is the common case, and
+neither form can move the cursor, erase, or carry an OSC payload. The test gates
+on both the 7-bit ESC (`U+001B`) introducer and the whole 8-bit C1 control block
+(U+0080–U+009F)—not just the CSI byte (`U+009B`)—so a C1-introduced cursor-move,
+erase, or OSC/DCS/SOS/PM/APC string is never mistaken for benign color; and it
+judges from what the Layer-1 strip actually removed, so a sequence that only
+RECONSTITUTES during stripping is judged as the sequence it becomes.
 
 ## Tool-output pipeline & Layer 5
 

package/claude-hooks/lib/control-plane.mjs

@@ -17,6 +17,7 @@ import {
   probeSetupAlive,
   readStdinJson,
 } from "./hook-io.mjs";
+import { startHookTimer, withSlowHookNotice } from "./hook-timing.mjs";
 
 // Loaded via a *caught* dynamic import — never a bare static `import … from`.
 // A static npm import resolves before any try/catch, so a missing node_modules
@@ -128,7 +129,12 @@ export function nativeStdout(response) {
  * unparsable stdin, missing package, a judge error — is reported on stderr and
  * routed to `onError(err, input)` (`input` undefined when stdin never parsed),
  * where the hook applies its declared fail posture.
- * @param {string} hookName  prefix for the stderr diagnostic
+ *
+ * It is also where every judge hook is TIMED: the verdict picks up a
+ * performance note when the judge overran the hook budget (see
+ * lib/hook-timing.mjs), so no hook has to remember to measure itself.
+ * @param {string} hookName  prefix for the stderr diagnostic, and the hook name
+ *   a slow-run notice reports
  * @param {(event: import("agent-control-plane-core").ToolCallEvent) =>
  *   import("agent-control-plane-core").Verdict |
  *   Promise<import("agent-control-plane-core").Verdict>} judge
@@ -152,9 +158,18 @@ export async function runJudgeCli(
   let input;
   try {
     input = await readInput();
+    // Timed from HERE, not from process start: the wait for the harness to hand
+    // over stdin is not this hook's cost, and blaming it for one would send
+    // operators chasing a bug report that is not theirs to fix.
+    const elapsed = startHookTimer();
     const { claudeAdapter: adapter } = controlPlane();
     const event = adapter.parse(transformInput(input));
-    const out = nativeStdout(adapter.render(await judge(event), event));
+    // Awaited into its own binding first: as an inline argument, `elapsed()`
+    // would be evaluated BEFORE the judge it is supposed to be timing.
+    const judged = await judge(event);
+    const out = nativeStdout(
+      adapter.render(withSlowHookNotice(hookName, elapsed(), judged), event),
+    );
     if (out !== null) write(out);
   } catch (err) {
     process.stderr.write(`${hookName} hook error: ${errMessage(err)}\n`);

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

@@ -11,6 +11,7 @@ import {
 import { userInfo } from "node:os";
 import { createHash } from "node:crypto";
 import { pathToFileURL } from "node:url";
+import { excludeProvisioning } from "./hook-timing.mjs";
 
 /**
  * EVERY process-wide slot these helpers keep — the four a host can observe or
@@ -742,6 +743,44 @@ export async function awaitLazyDependency({
   settleMs = 1000,
   ceilingMs = 900000,
   intervalMs = 250,
+}) {
+  // The whole wait is PROVISIONING, not this hook's own cost: it is time the
+  // container spends installing dependencies, and on a cold start it can run to
+  // minutes. Charging it to the hook would make the slow-hook notice fire on
+  // every cold session with a number that names the wrong culprit.
+  return excludeProvisioning(
+    () =>
+      pollForDependency({
+        tryImport,
+        markerPresent,
+        setupAlive,
+        now,
+        sleep,
+        graceMs,
+        settleMs,
+        ceilingMs,
+        intervalMs,
+      }),
+    now,
+  );
+}
+
+/**
+ * The poll loop {@link awaitLazyDependency} wraps. Split out so the
+ * provisioning charge brackets every exit — including the give-up arms.
+ * @param {Required<Parameters<typeof awaitLazyDependency>[0]>} opts
+ * @returns {Promise<Record<string, any> | null>}
+ */
+async function pollForDependency({
+  tryImport,
+  markerPresent,
+  setupAlive,
+  now,
+  sleep,
+  graceMs,
+  settleMs,
+  ceilingMs,
+  intervalMs,
 }) {
   const start = now();
   let sawInstalling = false;

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

@@ -0,0 +1,170 @@
+/**
+ * The one place a hook's own wall-clock cost is measured and reported.
+ *
+ * These hooks sit on the critical path of every tool call, every prompt and
+ * every session start: whatever they spend, the user waits. That cost is also
+ * the hardest kind of bug to notice from inside — a hook that got slow looks
+ * exactly like an agent that got slow, so it goes unreported for weeks (one
+ * SessionStart scan blocked startup for 30 SECONDS before anyone traced it back
+ * here). A hook past the budget therefore says so IN BAND, in the model's
+ * context, where it cannot be missed and can be relayed to the operator.
+ *
+ * One threshold, one message, one merge rule, shared by every hook — the
+ * measurement is worthless if each hook words it differently or picks its own
+ * bar for "slow".
+ *
+ * What it deliberately does NOT count is ONE-TIME PROVISIONING (see
+ * {@link excludeProvisioning}). A dependency-install wait or a cold redactor
+ * spawn is wall-clock the user really waits, but it is not a cost this hook
+ * pays per call and it is not a bug worth a report — charging it would make the
+ * FIRST call of every session cry wolf, which is precisely the alert fatigue
+ * this notice exists to avoid.
+ *
+ * Dependency-free on purpose: everything imports this, including hook-io, so a
+ * back-import would close a cycle. The one emitter it needs is passed in.
+ */
+
+/**
+ * Wall-clock a single hook invocation may spend before it is reported as slow.
+ *
+ * A second is far above anything these hooks do when healthy (Layer 1 is a few
+ * regex passes; the redactor daemon answers in tens of milliseconds once warm)
+ * and far below the point where a human is merely impatient — so crossing it
+ * means something is actually wrong, not that the machine is busy.
+ */
+export const SLOW_HOOK_THRESHOLD_MS = 1000;
+
+/** Where a reader is asked to send the timing. */
+const ISSUE_URL =
+  "https://github.com/AlexanderMattTurner/agent-sanitizer/issues/new";
+
+// Process-wide total of milliseconds spent in one-time provisioning. A running
+// total rather than a flag because a single hook run can pay more than one (a
+// dependency wait AND a cold daemon spawn), and they may not nest.
+let provisioningMs = 0;
+
+/**
+ * Run `work`, charging its whole duration to provisioning so no timer running
+ * across it counts that time. Charged in a `finally`, so a provisioning step
+ * that FAILS is still excluded — the wait happened either way, and a hook that
+ * then fails is reported through its fault posture, not as "slow".
+ *
+ * Wrap only genuinely one-time, per-session setup: waiting out a dependency
+ * install, waiting for a cold redactor daemon to bind. Never wrap the hook's
+ * actual work — that is exactly what this measurement is for.
+ * @template T
+ * @param {() => Promise<T>} work
+ * @param {() => number} [now]  injectable clock, for tests
+ * @returns {Promise<T>}
+ */
+export async function excludeProvisioning(work, now = Date.now) {
+  const started = now();
+  try {
+    return await work();
+  } finally {
+    provisioningMs += Math.max(0, now() - started);
+  }
+}
+
+/**
+ * Start measuring; the returned function reports the milliseconds elapsed so
+ * far MINUS any provisioning charged in the meantime, and may be called more
+ * than once.
+ *
+ * Only provisioning charged since this timer started is subtracted, so an
+ * earlier run's cold start cannot pay down a later run's real cost. A
+ * provisioning window that straddles the timer's start would otherwise be able
+ * to subtract more than the timer has measured, so the result is floored at 0.
+ * @param {() => number} [now]  injectable clock, for tests
+ * @returns {() => number}
+ */
+export function startHookTimer(now = Date.now) {
+  const started = now();
+  const provisionedBefore = provisioningMs;
+  return () =>
+    Math.max(0, now() - started - (provisioningMs - provisionedBefore));
+}
+
+/**
+ * The model-facing line for a hook that overran the budget, or null when it did
+ * not. Addressed to the model because the model is the only party that reliably
+ * reads this channel — stderr from a non-blocking hook is easy to miss — and it
+ * is asked to relay the number, since the operator is the one who can file it.
+ * @param {string} hookName
+ * @param {number} elapsedMs
+ * @param {number} [thresholdMs]
+ * @returns {string | null}
+ */
+export function slowHookNotice(
+  hookName,
+  elapsedMs,
+  thresholdMs = SLOW_HOOK_THRESHOLD_MS,
+) {
+  if (elapsedMs <= thresholdMs) return null;
+  return (
+    `agent-sanitizer PERFORMANCE: the ${hookName} hook took ` +
+    `${(elapsedMs / 1000).toFixed(1)}s, over its ${(thresholdMs / 1000).toFixed(1)}s budget — ` +
+    "this delay is the sanitizer's, not the model's, and every affected call pays it. " +
+    `Tell the user, and suggest they report it at ${ISSUE_URL} with the hook name and timing.`
+  );
+}
+
+/**
+ * `verdict` with the slow-hook notice folded into its `additional_context`, or
+ * the verdict untouched when the run was within budget. Also writes the notice
+ * to stderr, so the timing survives in the transcript even for a hook whose
+ * verdict carries no context channel to the model.
+ *
+ * Appended, never substituted: the context slot is how a hook reports a REDACTED
+ * secret or a stripped payload, and a timing note must not displace that.
+ * @template {{ additional_context?: string }} V
+ * @param {string} hookName
+ * @param {number} elapsedMs
+ * @param {V} verdict
+ * @param {(chunk: string) => void} [writeErr]  injectable stderr sink, for tests
+ * @returns {V}
+ */
+export function withSlowHookNotice(
+  hookName,
+  elapsedMs,
+  verdict,
+  writeErr = (chunk) => process.stderr.write(chunk),
+) {
+  const notice = slowHookNotice(hookName, elapsedMs);
+  if (notice === null) return verdict;
+  writeErr(notice + "\n");
+  return {
+    ...verdict,
+    additional_context: verdict.additional_context
+      ? `${verdict.additional_context} ${notice}`
+      : notice,
+  };
+}
+
+/**
+ * Report a slow run for a hook that answers with a bare `hookSpecificOutput`
+ * envelope rather than a control-plane verdict — SessionStart, which has no
+ * verdict channel at all. A within-budget run emits nothing, so the quiet path
+ * stays quiet (and the hook's silent-success contract is unchanged).
+ * @param {string} hookName
+ * @param {number} elapsedMs
+ * @param {string} hookEventName
+ * @param {(event: string, fields: Record<string, unknown>) => void} emit  the
+ *   stdout envelope writer (hook-io's emitHookResponse); passed in rather than
+ *   imported so this module stays dependency-free — see the module doc
+ * @param {(chunk: string) => void} [writeErr]  injectable stderr sink, for tests
+ * @returns {boolean}  whether a notice was emitted
+ */
+export function reportSlowHook(
+  hookName,
+  elapsedMs,
+  hookEventName,
+  emit,
+  writeErr = (chunk) => process.stderr.write(chunk),
+) {
+  const notice = slowHookNotice(hookName, elapsedMs);
+  if (notice === null) return false;
+  writeErr(notice + "\n");
+  emit(hookEventName, { additionalContext: notice });
+  return true;
+}

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

@@ -18,6 +18,7 @@
  * daemon could not vet input.
  */
 import { spawn } from "node:child_process";
+import { excludeProvisioning } from "./hook-timing.mjs";
 import { existsSync, lstatSync } from "node:fs";
 import { createConnection } from "node:net";
 import { tmpdir, userInfo } from "node:os";
@@ -422,7 +423,7 @@ function canConnect(socketPath) {
  * @param {{map?: boolean, webIngress?: boolean, socketPath?: string,
  *   deadline?: {remainingMs: () => number},
  *   connect?: typeof connectAndRequest, spawn?: typeof spawnDaemon,
- *   waitForSocket?: typeof waitForSocket}} [opts]
+ *   waitForSocket?: typeof waitForSocket, now?: () => number}} [opts]
  * @returns {Promise<RedactResponse|null>}
  */
 export async function redactViaDaemon(text, opts = {}) {
@@ -434,6 +435,10 @@ export async function redactViaDaemon(text, opts = {}) {
     connect = connectAndRequest,
     spawn: spawnFn = spawnDaemon,
     waitForSocket: waitFn = waitForSocket,
+    // The clock the provisioning charge is measured on; injectable alongside the
+    // waitForSocket seam it brackets, since a stubbed wait advances a test clock
+    // rather than real time.
+    now = Date.now,
   } = opts;
   // Remaining shared budget in ms, or undefined when no budget was threaded (the
   // standalone default). Re-read per step so the respawn path cannot overshoot.
@@ -502,7 +507,11 @@ export async function redactViaDaemon(text, opts = {}) {
       budgetMs === undefined
         ? undefined
         : { deadlineMs: Math.min(WAIT_DEADLINE_MS, budgetMs) };
-    if (!(await waitFn(socketPath, waitOpts)))
+    // The cold-start wait is PROVISIONING — a one-time detect-secrets import and
+    // plugin prime (~1-3s, see WAIT_DEADLINE_MS), paid by whichever tool call
+    // happens to be first and by no other. Charging it to this hook would make
+    // the slow-hook notice fire once per session on a healthy install.
+    if (!(await excludeProvisioning(() => waitFn(socketPath, waitOpts), now)))
       throw failClosed(
         new Error(`redactor daemon did not start within ${WAIT_DEADLINE_MS}ms`),
       );

package/claude-hooks/sanitize-output.mjs

@@ -96,13 +96,18 @@ const SANITIZE_BUDGET_MS = positiveMsOr(
   120000,
 );
 
-// Non-WARNING note for a strip whose only change was display-only SGR color on a
-// local tool: cosmetic styling git/pytest/npm/etc. emit by default. It keeps the
-// "color was here, and here is how to see it" signal without the WARNING prefix,
-// whose constant firing on benign color would desensitize the reader to the
-// strips that matter (invisible-char payloads, redacted secrets).
+// Non-WARNING note for a strip whose only change was INERT ANSI on a local tool:
+// the display-only colour git/pytest/npm/etc. emit by default, and/or a stray
+// escape byte that formed no sequence at all (a truncated write, a log fragment,
+// a raw ESC sitting in a file the tool echoed back). Neither can move the cursor,
+// erase the screen, or open an OSC string — those need a complete CSI/OSC token,
+// which keeps the WARNING. The note keeps the "escapes were here, and here is how
+// to see them" signal without the WARNING prefix, whose constant firing on inert
+// bytes would desensitize the reader to the strips that matter (invisible-char
+// payloads, redacted secrets).
 const SGR_OUTPUT_NOTE =
-  "Display-only ANSI color stripped; pipe through cat -v to inspect raw escapes.";
+  "Inert ANSI stripped (display-only colour and/or a stray escape byte that " +
+  "formed no control sequence); pipe through cat -v to inspect raw escapes.";
 
 // Web-ingress tools always get the Layer 2 HTML rewrite; local tools — Read,
 // Bash, Grep, gh — never do. A local HTML/markdown pass either rewrites bytes the

package/claude-hooks/sanitize-user-prompt.mjs

@@ -65,7 +65,7 @@ export const USER_PROMPT_MESSAGES = Object.freeze({
   blockContext:
     "User prompt blocked: payload-capable invisible/ANSI characters detected.",
   sgrNote:
-    "The prompt contains ANSI SGR color codes (pasted terminal output). They are display-only formatting noise; read through them.",
+    "The prompt contains inert ANSI escapes (pasted terminal output): display-only SGR colour codes and/or a stray escape byte that forms no control sequence. They are formatting noise; read through them.",
   hookFailed: (cause) =>
     `sanitize-user-prompt hook failed (fail-closed): ${cause}`,
   // What a reader should run when the package itself is what is missing. It

package/claude-hooks/scan-invisible-chars.mjs

@@ -9,6 +9,7 @@ import { readFileSync, globSync, writeFileSync, unlinkSync } from "node:fs";
 import { join, relative } from "node:path";
 import {
   awaitLazyDependency,
+  emitHookResponse,
   safeErrMessage,
   hookgateMarkerPath,
   HookEvent,
@@ -29,6 +30,7 @@ import {
   PROJECT_DIR,
 } from "./lib/invisible-alert.mjs";
 import { bestEffortTrace, trace, TraceEvent } from "./lib/trace.mjs";
+import { reportSlowHook, startHookTimer } from "./lib/hook-timing.mjs";
 
 // Layer-1 primitives, bound via lazyImport (see its doc for the fail-OPEN
 // hazard of a bare static npm import — here the instruction files would load
@@ -191,27 +193,85 @@ function decodeRun(run) {
 }
 
 /**
- * @param {string} dir
- * @returns {string[]}
+ * The `.claude/` subdirectories whose markdown Claude Code loads as model
+ * context. This is a WHITELIST, and that is the point: `.claude/` is also where
+ * tooling parks bulk data that is never loaded as context — `worktrees/`
+ * (entire checked-out copies of the repo), plus caches, transcripts and
+ * snapshots — and globbing `.claude/**` swept all of it in. On a repo with a few
+ * populated worktrees that is thousands of files READ at every session start:
+ * one report put it at 30 seconds of blocked startup, paid for scanning files
+ * that cannot reach the model.
+ *
+ * A whitelist, not a `worktrees` denylist, because the failure modes are not
+ * symmetric: an unlisted context directory costs a scan this hook was never
+ * asked for anyway (the PostToolUse sanitizer still cleans those bytes when a
+ * tool reads them), while an unlisted BULK directory silently costs every future
+ * session its startup. Add an entry here when Claude Code starts loading a new
+ * `.claude/` subdirectory as context.
+ */
+export const CLAUDE_CONTEXT_SUBDIRS = Object.freeze([
+  "agents",
+  "commands",
+  "output-styles",
+  "skills",
+]);
+
+// The glob patterns for one `.claude` tree at `prefix` (empty for the project
+// root, a doubled-star segment for nested ones): its top-level markdown, plus the
+// whitelisted context subdirectories. Built once, from the one list above.
+/** @param {string} prefix @returns {string[]} */
+function claudeDirPatterns(prefix) {
+  return [
+    `${prefix}.claude/*.md`,
+    ...CLAUDE_CONTEXT_SUBDIRS.map((sub) => `${prefix}.claude/${sub}/**/*.md`),
+  ];
+}
+
+/**
+ * Entries the walk must not descend into or return: `node_modules`, and every
+ * child of a `.claude` directory that is not whitelisted context.
+ *
+ * The patterns alone would already refuse to MATCH those files, but globSync
+ * calls this on directories as it walks and prunes the ones it rejects — which
+ * is where the cost actually is. Without the prune, a `.claude/worktrees/`
+ * holding a few repo checkouts is walked in full on every session start (and,
+ * because a doubled-star segment does cross into a dot directory when the
+ * pattern names one, a `.claude` NESTED inside a worktree was matched and
+ * scanned as if it were this session's context).
+ *
+ * globSync calls this with both bare names and repo-relative paths, so it must
+ * answer for either; a bare name carries no `.claude` context and is judged only
+ * against `node_modules`.
+ * @param {string} entry  a bare entry name or a path relative to the scan root
+ * @returns {boolean}
  */
-function findMdFiles(dir) {
-  return globSync("**/*.md", {
-    cwd: dir,
-    exclude: (name) => name === "node_modules",
-  }).map((name) => join(dir, name));
+function excludeFromScan(entry) {
+  if (entry === "node_modules") return true;
+  const parts = entry.split(/[/\\]/);
+  const claudeIndex = parts.indexOf(".claude");
+  const tail = parts.slice(claudeIndex + 1);
+  if (claudeIndex === -1 || tail.length === 0) return false;
+  // `.claude/<file>.md` is context (a top-level note); anything else directly
+  // under `.claude` must be a whitelisted subdirectory to be walked at all.
+  if (tail.length === 1 && tail[0].endsWith(".md")) return false;
+  return !CLAUDE_CONTEXT_SUBDIRS.includes(tail[0]);
 }
 
 /**
- * Every subdirectory instruction file (CLAUDE.md, CLAUDE.local.md, AGENTS.md)
- * under `dir`. Claude Code loads these as project instructions on entry to their
- * containing directory — a load path that bypasses the PostToolUse sanitizer — so
- * a payload planted in e.g. `packages/foo/CLAUDE.md` reaches the model uncleaned
- * unless it is scanned here. Skips node_modules.
+ * Every file under `dir` that Claude Code loads as model context: the
+ * subdirectory instruction files (CLAUDE.md, CLAUDE.local.md, AGENTS.md) and the
+ * whitelisted `.claude/` markdown (see {@link CLAUDE_CONTEXT_SUBDIRS}). Claude
+ * Code loads these on entry to their containing directory — a load path that
+ * bypasses the PostToolUse sanitizer — so a payload planted in e.g.
+ * `packages/foo/CLAUDE.md` reaches the model uncleaned unless it is scanned
+ * here. Skips node_modules.
  *
  * `**` does not descend into dot directories, so NESTED `.claude/` trees need
- * their own pattern: the caller scans only the project-root `.claude`, which
- * would leave a directory-scoped skill at `packages/foo/.claude/skills/x/SKILL.md`
- * — model context by the same load path — never scanned.
+ * their own doubled-star-prefixed patterns: without them a directory-scoped skill at
+ * `packages/foo/.claude/skills/x/SKILL.md` — model context by the same load
+ * path — is never scanned. That same rule is why the root `.claude` needs no
+ * separate walk: a leading doubled star matches zero segments, so the nested
+ * patterns cover the root tree too.
  * @param {string} dir
  * @returns {string[]}
  */
@@ -221,12 +281,9 @@ function findInstructionFiles(dir) {
       "**/CLAUDE.md",
       "**/CLAUDE.local.md",
       "**/AGENTS.md",
-      "**/.claude/**/*.md",
+      ...claudeDirPatterns("**/"),
     ],
-    {
-      cwd: dir,
-      exclude: (name) => name === "node_modules",
-    },
+    { cwd: dir, exclude: excludeFromScan },
   ).map((name) => join(dir, name));
 }
 
@@ -268,7 +325,6 @@ function scanFile(filePath) {
 
 export {
   decodeRun,
-  findMdFiles,
   findInstructionFiles,
   scanFile,
   ALERT_FILE,
@@ -350,12 +406,7 @@ export { formatReport };
  * }}
  */
 export function scanProject(dir = PROJECT_DIR) {
-  const targets = [
-    ...new Set([
-      ...findInstructionFiles(dir),
-      ...findMdFiles(join(dir, ".claude")),
-    ]),
-  ];
+  const targets = [...new Set(findInstructionFiles(dir))];
   const findings = [];
   const skipped = [];
   let scanned = 0;
@@ -420,7 +471,35 @@ export function formatSkipped(skipped) {
  *   untested fault path is how a posture goes missing in the first place.
  * @returns {Promise<void>}
  */
-export async function cliMain({ trace: sink = trace, scan: runScan } = {}) {
+export async function cliMain(opts = {}) {
+  // The scan blocks session startup, and a slow one is invisible from the
+  // inside — it reads as "Claude is slow to start". Timing the whole body and
+  // reporting an overrun in band is what turned a 30-second scan from a rumor
+  // into a bug report (see lib/hook-timing.mjs).
+  const elapsed = startHookTimer();
+  try {
+    await runScanCli(opts);
+  } finally {
+    reportSlowHook(
+      HOOK_NAME,
+      elapsed(),
+      HookEvent.SESSION_START,
+      emitHookResponse,
+    );
+  }
+}
+
+/**
+ * The scan itself. Split from {@link cliMain} only so the timing wrapper above
+ * has a single call to bracket — every early return here is an exit the wrapper
+ * must still measure.
+ * @param {{
+ *   trace?: import("./lib/trace.mjs").TraceFn,
+ *   scan?: () => ReturnType<typeof scanProject>,
+ * }} opts  see {@link cliMain}
+ * @returns {Promise<void>}
+ */
+async function runScanCli({ trace: sink = trace, scan: runScan }) {
   // Bound best-effort: the announcements below run BEFORE the auto-clean and
   // the alert write, with no catch above them, so a throwing host sink would
   // abort the scan silently (see bestEffortTrace).

package/package.json

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