agent-sanitizer 2.25.0 → 2.26.1

package/src/view-map.mjs

@@ -12,9 +12,19 @@
  *             placeholder (`pairs` from the injected redactor’s map mode)
  *
  * The view is carried by {@link makeFileView}, the ONLY constructor the
- * consumers of this module may use: it owns the code-point → UTF-16 offset
- * conversion and brands the result, so the conversion happens exactly once per
- * view and every function below can assert it happened.
+ * consumers of this module may use: it brands the result, and the brand carries
+ * the coordinate SPACE the pair offsets live in — `"codePoint"` as the injected
+ * redactor emits them, `"utf16"` as every function below indexes by. Conversion
+ * is a separate, one-way door ({@link toUtf16View}) that accepts only a
+ * `"codePoint"` view and returns a new `"utf16"` one, so converting twice throws
+ * instead of shifting every astral-preceded offset a second time. Each consumer
+ * asserts the space it needs, so a wrongly-spaced view fails at the boundary
+ * rather than resolving onto the wrong bytes.
+ *
+ * The space is part of the value rather than a convention in a comment because
+ * the two spaces are otherwise indistinguishable — bare numbers in a bare
+ * object — which is exactly why the original double-conversion bug was silently
+ * accepted.
  */
 
 /**
@@ -28,57 +38,123 @@ const FILE_VIEW = Symbol("agent-sanitizer:file-view");
 
 /**
  * @typedef {{ placeholder: string, original: string, start: number }} RedactionPair
- * @typedef {{ text: string, pairs: readonly RedactionPair[] }} FileView
- *   A branded, frozen carrier from {@link makeFileView}. `pairs` are in UTF-16
- *   offsets, sorted and non-overlapping — both enforced at construction.
+ * @typedef {"codePoint" | "utf16"} OffsetSpace
+ *   Units a {@link FileView}'s pair offsets are expressed in. `codePoint` is
+ *   what the redactor's map mode emits (Python indexes strings by code point);
+ *   `utf16` is what every function in this module indexes by (JS
+ *   `indexOf`/`slice`/`.length` count UTF-16 code units).
+ */
+
+/**
+ * A branded, frozen carrier from {@link makeFileView}, tagged with the space its
+ * `pairs` offsets live in. Its own JSDoc block: a `@template` applies to every
+ * typedef in the comment it sits in, so sharing one with the two above would
+ * make `RedactionPair` and `OffsetSpace` generic too.
+ * @template {OffsetSpace} S
+ * @typedef {{ readonly space: S, readonly text: string,
+ *   readonly pairs: readonly RedactionPair[] }} FileView
  */
 
 /**
- * Build the branded file view from a redactor's map-mode result.
+ * Wrap a redactor's map-mode result in a frozen, branded view tagged with the
+ * space its offsets are in.
  *
  * The redactor's own object is never touched. It used to be: the caller did
  * `view.pairs = pairsToUtf16(view.text, view.pairs)`, an in-place mutation of a
  * value returned from an INJECTED seam. A redactor that memoizes its map result
  * (a reasonable thing for a caller to build) hands back the same object on the
- * second identical call, which then gets converted a SECOND time — every
+ * second identical call, which then got converted a SECOND time — every
  * placeholder preceded by an astral character shifts again and the same input
- * yields a different verdict. Converting into a fresh frozen carrier removes
- * that: the conversion is part of construction, the redactor's value is left
- * alone, and every consumer asserts the brand rather than accepting a
- * hand-assembled `{text, pairs}` whose offsets may or may not be converted.
+ * yields a different verdict.
  *
- * It does NOT make double conversion impossible — `makeFileView(v.text,
- * v.pairs)` on an existing view would convert again. Nothing does that, and a
- * guard would have to reject legitimately-frozen caller input to catch it, so
- * the defence here is that there is exactly one construction site and it takes
- * the redactor's result directly.
+ * Construction no longer converts. It brands and records the space, and
+ * {@link toUtf16View} does the conversion behind a check that the input is
+ * still in code-point space — so `toUtf16View(alreadyConverted)` throws where
+ * `makeFileView(v.text, v.pairs)` on an existing view used to silently convert
+ * a second time. That was the one door this carrier left open.
  *
- * The frozen `pairs` array is likewise a copy — `pairsToUtf16` returns its
- * argument unchanged for the empty case, and freezing the redactor's array
- * would reach back into the seam's memoized value.
+ * Both the array AND each pair object are copied before freezing, so nothing
+ * here reaches back into the seam's (possibly memoized) value, and a caller that
+ * later mutates its own pairs cannot change what this view resolves.
+ * @template {OffsetSpace} S
  * @param {string} text redacted view text
- * @param {RedactionPair[]} pairs redactor pairs, in CODE-POINT offsets
- * @returns {FileView}
+ * @param {readonly RedactionPair[]} pairs redactor pairs, offsets in `space`
+ * @param {S} space
+ * @returns {FileView<S>}
  */
-export function makeFileView(text, pairs) {
+export function makeFileView(text, pairs, space) {
+  assertPairsOrdered(text, pairs, space);
   return Object.freeze({
     [FILE_VIEW]: true,
+    space,
     text,
-    pairs: Object.freeze([...pairsToUtf16(text, pairs)]),
+    pairs: Object.freeze(pairs.map((pair) => Object.freeze({ ...pair }))),
   });
 }
 
 /**
- * Throw unless `view` came from {@link makeFileView}. Every offset function
- * here reads `view.pairs` as UTF-16 offsets; a hand-rolled `{text, pairs}` whose
- * pairs are still in code-point space mis-anchors an edit onto the wrong bytes
- * whenever an astral character precedes a placeholder — silently, and only for
+ * Offsets counted the way `space` counts them: UTF-16 code units, or code
+ * points as the Python redactor emits them.
+ * @param {string} text
+ * @param {OffsetSpace} space
+ * @returns {number}
+ */
+function unitLength(text, space) {
+  return space === "utf16" ? text.length : Array.from(text).length;
+}
+
+/**
+ * Throw unless `pairs` is in range, sorted by `start` and non-overlapping, with
+ * every offset read in `space`.
+ *
+ * Every consumer here — `mapViewOffset`'s `else break`, `pairDiskSpans`'s
+ * sequential walk — assumes exactly this. An out-of-range start indexes past
+ * the text and silently yields `undefined`, which then poisons every downstream
+ * offset comparison (`undefined < n` is always false); an out-of-order or
+ * overlapping pair stops the scan early and mis-maps an offset onto the wrong
+ * bytes. Enforced at CONSTRUCTION so no view can exist in that state, rather
+ * than at each read.
+ * @param {string} text the view text the offsets index into
+ * @param {readonly RedactionPair[]} pairs
+ * @param {OffsetSpace} space
+ * @returns {void}
+ */
+function assertPairsOrdered(text, pairs, space) {
+  // The no-secrets rehydration is the common case, and the loop below has
+  // nothing to check there. Return before `unitLength`, which for "codePoint"
+  // materializes a code-point array over the whole file on every Edit/Write.
+  if (pairs.length === 0) return;
+  const total = unitLength(text, space);
+  // The previous pair's placeholder end. `start < prevEnd` catches an
+  // out-of-order start and an overlap in one comparison.
+  let prevEnd = 0;
+  for (const pair of pairs) {
+    if (!Number.isInteger(pair.start) || pair.start < 0 || pair.start > total)
+      throw new Error(
+        `redaction pair start ${pair.start} is out of range [0, ${total}]`,
+      );
+    if (pair.start < prevEnd)
+      throw new Error(
+        `redaction pairs must be sorted and non-overlapping: pair start ${pair.start} precedes previous pair end ${prevEnd}`,
+      );
+    prevEnd = pair.start + unitLength(pair.placeholder, space);
+  }
+}
+
+/**
+ * Throw unless `view` came from {@link makeFileView} AND carries `space`.
+ *
+ * Two failures, one gate. A hand-rolled `{text, pairs}` has offsets that may or
+ * may not have been converted; a real view in the WRONG space has offsets that
+ * definitely have not. Either mis-anchors an edit onto the wrong bytes whenever
+ * an astral character precedes a placeholder — silently, and only for
  * emoji-bearing files. Fail loudly at the boundary instead.
  * @param {unknown} view
+ * @param {OffsetSpace} space  the space the calling function indexes by
  * @param {string} fn name of the calling function, for the error
  * @returns {void}
  */
-function assertFileView(view, fn) {
+function assertFileView(view, space, fn) {
   if (
     view === null ||
     typeof view !== "object" ||
@@ -88,6 +164,11 @@ function assertFileView(view, fn) {
       `${fn} requires a view built by makeFileView(); got a raw object whose ` +
         `pair offsets have not been normalized to UTF-16`,
     );
+  const actual = /** @type {FileView<OffsetSpace>} */ (view).space;
+  if (actual !== space)
+    throw new Error(
+      `${fn} requires a view with ${space} pair offsets, got ${actual}`,
+    );
 }
 
 /**
@@ -195,53 +276,52 @@ function diskOffset(deletions, cleanedOffset, isEnd) {
  * placeholder mis-anchors the edit onto the wrong bytes.
  *
  * Exactly once, though: applying it to its own output shifts every
- * astral-preceded placeholder a second time. Prefer {@link makeFileView}, which
- * runs it as part of construction and hands back a branded carrier the rest of
- * this module accepts; this stays exported (it is public API on the
- * `./view-map` subpath) for callers doing their own offset bookkeeping, who own
- * the once-only discipline themselves.
+ * astral-preceded placeholder a second time, and bare arrays of numbers give
+ * nothing to check that against. Prefer {@link toUtf16View}, which runs this
+ * behind a space check so the second application throws instead. This stays
+ * exported — it is public API on the `./view-map` subpath, and removing it
+ * would be a breaking change the release workflow cannot express (it caps
+ * automated bumps at minor) — for callers doing their own offset bookkeeping,
+ * who own the once-only discipline themselves.
  * @param {string} text the redacted view text the offsets index into
- * @param {{placeholder: string, original: string, start: number}[]} pairs
- * @returns {{placeholder: string, original: string, start: number}[]}
+ * @param {RedactionPair[]} pairs
+ * @returns {RedactionPair[]}
  */
 export function pairsToUtf16(text, pairs) {
   if (pairs.length === 0) return pairs;
+  assertPairsOrdered(text, pairs, "codePoint");
   const codePoints = Array.from(text);
   // prefix[i] = UTF-16 length of the first i code points of `text`.
   const prefix = new Array(codePoints.length + 1);
   prefix[0] = 0;
   for (let i = 0; i < codePoints.length; i++)
     prefix[i + 1] = prefix[i] + codePoints[i].length;
-  // Code-point end of the previous pair's placeholder span. mapViewOffset's
-  // `else break` (and pairDiskSpans) assume pairs are sorted by start and never
-  // overlap; an out-of-order or overlapping pair would make the scan stop early
-  // and mis-map an offset onto the wrong bytes. Enforce the contract here.
-  let prevEnd = 0;
-  return pairs.map((pair) => {
-    // A redactor offset outside [0, codePoints.length] indexes `prefix` out of
-    // range and would silently yield `start: undefined`, which then poisons
-    // every downstream offset comparison (undefined < n is always false) and
-    // mis-anchors or corrupts the edit. Fail loudly instead — an out-of-range
-    // pair means the injected redactor's map contract was violated.
-    if (
-      !Number.isInteger(pair.start) ||
-      pair.start < 0 ||
-      pair.start > codePoints.length
-    )
-      throw new Error(
-        `redaction pair start ${pair.start} is out of range [0, ${codePoints.length}]`,
-      );
-    // Sorted + non-overlapping: `start` must be monotonically non-decreasing and
-    // each pair's placeholder span must end at or before the next pair's start.
-    // `prevEnd` already encodes the previous end, so `start < prevEnd` catches
-    // both an out-of-order start and an overlap in one comparison. Fail closed.
-    if (pair.start < prevEnd)
-      throw new Error(
-        `redaction pairs must be sorted and non-overlapping: pair start ${pair.start} precedes previous pair end ${prevEnd}`,
-      );
-    prevEnd = pair.start + Array.from(pair.placeholder).length;
-    return { ...pair, start: prefix[pair.start] };
-  });
+  return pairs.map((pair) => ({ ...pair, start: prefix[pair.start] }));
+}
+
+/**
+ * The same view with its pair offsets re-expressed in UTF-16 code units — a NEW
+ * frozen carrier; `view` is untouched.
+ *
+ * The one-way door. Only a `"codePoint"` view is accepted, so converting an
+ * already-converted view throws rather than shifting every astral-preceded
+ * offset a second time — which either mis-anchors the edit or rejects it as
+ * cutting a placeholder, both from an input that was fine the first time it was
+ * seen. Offset range/sort/overlap validity is not this door's job — every
+ * carrier is checked at construction (see {@link assertPairsOrdered}), in
+ * whichever space it declares.
+ * @param {FileView<"codePoint">} view
+ * @returns {FileView<"utf16">}
+ */
+export function toUtf16View(view) {
+  assertFileView(view, "codePoint", "toUtf16View");
+  // Copied because `view.pairs` is readonly and `pairsToUtf16` keeps the
+  // published mutable signature; makeFileView copies again on the way in.
+  return makeFileView(
+    view.text,
+    pairsToUtf16(view.text, [...view.pairs]),
+    "utf16",
+  );
 }
 
 /**
@@ -275,7 +355,7 @@ function mapViewOffset(pairs, offset) {
  * and a mis-attributed run would mis-anchor the edit.
  * @param {string} content disk file content
  * @param {string} cleaned Layer-1 view of `content`
- * @param {FileView} view
+ * @param {FileView<"utf16">} view
  * @param {{start: number, deleted: string}[]} deletions
  * @param {number} viewStart
  * @param {number} viewEnd
@@ -288,7 +368,7 @@ export function resolveSpan(
   viewStart,
   viewEnd,
 ) {
-  assertFileView(view, "resolveSpan");
+  assertFileView(view, "utf16", "resolveSpan");
   const cleanedStart = mapViewOffset(view.pairs, viewStart);
   const cleanedEnd = mapViewOffset(view.pairs, viewEnd);
   if (cleanedStart === null || cleanedEnd === null) return null;
@@ -378,15 +458,15 @@ export function spliceOrdered(text, matches, replacementFor) {
  * was never part of the secret); interior runs are included. Callers use these
  * to detect an edit whose on-disk footprint intrudes into bytes the model was
  * never shown.
- * @param {FileView} view
+ * @param {FileView<"utf16">} view
  * @param {{start: number, deleted: string}[]} deletions
  * @returns {{start: number, end: number}[]}
  */
 export function pairDiskSpans(view, deletions) {
-  assertFileView(view, "pairDiskSpans");
+  assertFileView(view, "utf16", "pairDiskSpans");
   return view.pairs.map((pair) => {
     // pair.start is a placeholder boundary, and makeFileView rejected any pair
-    // set that is out of order or overlapping (see pairsToUtf16), so it is never
+    // set out of order or overlapping (see assertPairsOrdered), so it is never
     // strictly interior to another placeholder: mapViewOffset always resolves.
     // The throw is kept anyway, and is NOT dead weight — it is the difference
     // between crashing and corrupting. `null + pair.original.length` is a
@@ -395,9 +475,9 @@ export function pairDiskSpans(view, deletions) {
     // i.e. an edit footprint pointing at the wrong bytes.
     const cleanedStart = mapViewOffset(view.pairs, pair.start);
     /* c8 ignore start -- unreachable through makeFileView, which rejects the
-       overlapping pair set that is the only way to produce null here (see the
-       constructor test in test/view-map.test.mjs); kept as a fail-loud guard
-       against a future regression in that ordering check. `ignore next N` does
+       overlapping pair set that is the only way to produce null here (see
+       assertPairsOrdered and the constructor test in test/view-map.test.mjs);
+       kept as a fail-loud guard against a future regression in that check. `ignore next N` does
        NOT suppress the branch here — only the statement — so the range form is
        required to keep the src branch floor at 100%. */
     if (cleanedStart === null)

package/types/claude-context.d.mts

@@ -0,0 +1,88 @@
+/**
+ * The one directory no instruction-file walk ever descends into. Its own
+ * function so the name is spelled once, and so the two predicates that need it
+ * (a plain glob walk, and {@link excludeFromContextScan}) cannot disagree.
+ * @param {string} entry  a bare entry name or a path relative to the scan root
+ * @returns {boolean}
+ */
+export function excludeNodeModules(entry: string): boolean;
+/**
+ * Entries a context scan must not descend into or return: `node_modules`, and
+ * every child of a `.claude` directory that is not whitelisted context.
+ *
+ * The globs alone would already refuse to MATCH those files, but a glob walker
+ * 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).
+ *
+ * A walker calls this with both bare names and root-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}
+ */
+export function excludeFromContextScan(entry: string): boolean;
+/**
+ * WHICH files an agent loads as model context, as data: the glob set and the
+ * walk-pruning predicate that together define "everything Claude Code reads as
+ * instructions, and nothing else".
+ *
+ * This is the SINGLE SOURCE for that scope. It used to live inside
+ * `claude-hooks/scan-invisible-chars.mjs`, which meant the SessionStart hook
+ * knew the answer and nobody else did: `src/instructions.mjs` takes
+ * caller-supplied globs by design (no agent's convention is baked into the
+ * engine), so the CLI, the Python port and every downstream fork spelled their
+ * own approximation of this list — and an approximation that drifts either
+ * scans bulk data that can never reach the model (the 30-second session start
+ * this whitelist exists to fix) or MISSES a context directory entirely, which
+ * is a silent hole in the one scan standing between a poisoned instruction file
+ * and a session that loads it.
+ *
+ * It is a standalone, dependency-free DATA module (like ./cf-charset.mjs) for
+ * two reasons: `src/instructions.mjs` re-exports it as the library's public
+ * door, and the hook imports it RELATIVELY — deliberately not through the
+ * `agent-sanitizer` specifier the plugin bundle pins to a published engine.
+ * This scope is hook POLICY, not engine behavior: it must ship and move with the
+ * hook that walks it, or a plugin built against an older pin would prune the
+ * wrong directories while believing it had scanned everything.
+ */
+/**
+ * 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 nobody 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: readonly string[];
+/**
+ * Every glob whose matches Claude Code loads as model context: the
+ * per-directory instruction files (CLAUDE.md, CLAUDE.local.md, AGENTS.md) and
+ * the whitelisted `.claude/` markdown. 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 something scans it here.
+ *
+ * `**` does not descend into dot directories, so NESTED `.claude/` trees need
+ * 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 matched. That same rule is why the root `.claude` needs
+ * no separate entry: a leading doubled star matches zero segments, so the
+ * nested patterns cover the root tree too.
+ *
+ * Pair with {@link excludeFromContextScan}: the patterns alone already refuse to
+ * MATCH a bulk directory, but only pruning the WALK avoids paying to read it.
+ */
+export const CLAUDE_INSTRUCTION_GLOBS: readonly string[];

package/types/claude-hooks/lib/hook-timing.d.mts

@@ -1,3 +1,17 @@
+/**
+ * Milliseconds as the seconds string every notice below prints.
+ *
+ * Rounds tenths half-UP from an exact integer count of hundredths, rather than
+ * `(ms / 1000).toFixed(1)`: the shell port of this module
+ * (plugin/scripts/lib/hook-timing.sh) has to produce the byte-identical string
+ * with integer arithmetic, and `toFixed` rounds the underlying double — so 1150
+ * would print "1.1" here (1.15 is below its decimal value as a double) and "1.2"
+ * there. `ms / 100` lands exactly on a half only when `ms` ends in 50, and every
+ * such quotient is dyadic, so this rounding is exact for every input.
+ * @param {number} ms
+ * @returns {string}
+ */
+export function formatSeconds(ms: number): string;
 /**
  * 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
@@ -37,6 +51,43 @@ export function startHookTimer(now?: () => number): () => number;
  * @returns {string | null}
  */
 export function slowHookNotice(hookName: string, elapsedMs: number, thresholdMs?: number): string | null;
+/**
+ * The line for a ONE-TIME provisioning step that overran
+ * {@link SLOW_PROVISION_THRESHOLD_MS}, or null when it did not.
+ *
+ * Deliberately NOT {@link slowHookNotice} with a bigger threshold: that message
+ * says "every affected call pays it", which is false here and would send the
+ * reader hunting a per-call cost that does not exist. What is actionable about a
+ * slow install is the installer (uv resolves in a fraction of pip's time) and
+ * the fact that a repeat means the idempotence check is broken — so this asks
+ * for a report only on the repeat, which is the version of this that is a bug.
+ *
+ * The one caller is the shell provisioner, whose port of this module
+ * (plugin/scripts/lib/hook-timing.sh) must emit this exact string; that port and
+ * this definition are pinned to each other by a contract test rather than left
+ * as two independently-worded copies.
+ * @param {string} stepName
+ * @param {number} elapsedMs
+ * @param {number} [thresholdMs]
+ * @returns {string | null}
+ */
+export function slowProvisionNotice(stepName: string, elapsedMs: number, thresholdMs?: number): string | null;
+/**
+ * Write the slow-hook notice to stderr and return it, or return null when the
+ * run was within budget (writing nothing, so the quiet path stays quiet).
+ *
+ * The one place the notice reaches stderr: every reporter below needs the
+ * transcript copy, and a hook whose run ENDED IN AN ERROR has nothing but this —
+ * its verdict is the fail-closed one its `onError` composed, and diluting that
+ * message with a performance aside would bury the fault. A judge that spent
+ * thirty seconds and then threw is exactly the case the timing exists to name,
+ * so the error path measures and reports; it just reports on the human channel.
+ * @param {string} hookName
+ * @param {number} elapsedMs
+ * @param {(chunk: string) => void} [writeErr]  injectable stderr sink, for tests
+ * @returns {string | null}
+ */
+export function writeSlowHookNotice(hookName: string, elapsedMs: number, writeErr?: (chunk: string) => void): string | null;
 /**
  * `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
@@ -104,3 +155,16 @@ export function reportSlowHook(hookName: string, elapsedMs: number, hookEventNam
  * means something is actually wrong, not that the machine is busy.
  */
 export const SLOW_HOOK_THRESHOLD_MS: 1000;
+/**
+ * Wall-clock a ONE-TIME provisioning step may spend before it is reported.
+ *
+ * Two orders of magnitude above {@link SLOW_HOOK_THRESHOLD_MS}, because it
+ * measures something categorically different: a dependency install that a
+ * session pays once, not a cost every tool call repeats. A cold `uv` install of
+ * the redactor engine is seconds and a cold `pip` one can be tens of them, so a
+ * budget anywhere near a second would report every first session — the alert
+ * fatigue this whole module exists to avoid. Past a minute, something is
+ * actually wrong (a serial pip resolve, a wedged mirror, or an idempotence bug
+ * re-provisioning every session), which is worth saying out loud.
+ */
+export const SLOW_PROVISION_THRESHOLD_MS: 60000;

package/types/claude-hooks/sanitize-output.d.mts

@@ -56,13 +56,14 @@
  * @param {{remainingMs: () => number}} [deadline] shared wall-clock budget across
  *   all leaves of one hook run; a direct caller gets a fresh full budget
  * @param {SanitizeExtensions} [ext]
- * @returns {Promise<{ cleaned: string, warnings: string[], modified: boolean, sgrNote: boolean, reveal?: string }>}
+ * @returns {Promise<{ cleaned: string, warnings: string[], notes: string[], modified: boolean, sgrNote: boolean, reveal?: string }>}
  */
 export function sanitizeText(text: string, toolName: string, deadline?: {
     remainingMs: () => number;
 }, ext?: SanitizeExtensions): Promise<{
     cleaned: string;
     warnings: string[];
+    notes: string[];
     modified: boolean;
     sgrNote: boolean;
     reveal?: string;
@@ -77,10 +78,10 @@ export function sanitizeText(text: string, toolName: string, deadline?: {
  * too (a connector can hide a secret in a field name); non-string leaves
  * (booleans, numbers, null) pass through untouched, and `warnings` accumulates
  * across leaves.
- * `sgrNote` is the OR across leaves: true when some leaf was an SGR-only strip.
+ * `sgrNote` is the OR across leaves: true when some leaf came back note-only.
  * `reveals` accumulates each leaf's pre-Layer-2 text (when the HTML splice
- * removed something) for the orchestrator to persist — same mutated-accumulator
- * shape as `warnings`.
+ * removed something) for the orchestrator to persist, and `notes` the leaves'
+ * NOTE-severity findings — same mutated-accumulator shape as `warnings`.
  * @param {any} value
  * @param {string} toolName
  * @param {string[]} warnings
@@ -88,11 +89,13 @@ export function sanitizeText(text: string, toolName: string, deadline?: {
  * @param {{remainingMs: () => number}} [deadline] shared wall-clock budget across
  *   every leaf of this value (created once by the top-level caller)
  * @param {SanitizeExtensions} [ext]
+ * @param {string[]} [notes]  appended last so an existing caller's positional
+ *   arguments keep their meaning
  * @returns {Promise<{ value: any, modified: boolean, sgrNote: boolean }>}
  */
 export function sanitizeValue(value: any, toolName: string, warnings: string[], reveals?: string[], deadline?: {
     remainingMs: () => number;
-}, ext?: SanitizeExtensions): Promise<{
+}, ext?: SanitizeExtensions, notes?: string[]): Promise<{
     value: any;
     modified: boolean;
     sgrNote: boolean;

package/types/claude-hooks/scan-invisible-chars.d.mts

@@ -71,24 +71,6 @@ export function cliMain(opts?: {
     trace?: import("./lib/trace.mjs").TraceFn;
     scan?: () => ReturnType<typeof scanProject>;
 }): Promise<void>;
-/**
- * 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: readonly string[];
 /**
  * @param {string} filePath
  * @returns {Array<{ line: number, charCount: number, method: string, decoded: string }>}
@@ -99,6 +81,8 @@ export function scanFile(filePath: string): Array<{
     method: string;
     decoded: string;
 }>;
+import { CLAUDE_CONTEXT_SUBDIRS } from "../src/claude-context.mjs";
+import { CLAUDE_INSTRUCTION_GLOBS } from "../src/claude-context.mjs";
 /**
  * @param {string} run
  * @returns {{ method: string, decoded: string }}
@@ -109,19 +93,17 @@ export function decodeRun(run: string): {
 };
 /**
  * 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.
+ * per-directory instruction files (CLAUDE.md, CLAUDE.local.md, AGENTS.md) and
+ * the whitelisted `.claude/` markdown. 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.
  *
- * `**` does not descend into dot directories, so NESTED `.claude/` trees need
- * 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.
+ * The scope itself — which globs, and which directories the walk must prune —
+ * is the library's {@link CLAUDE_INSTRUCTION_GLOBS} /
+ * {@link excludeFromContextScan}, so this hook and every other consumer read one
+ * list (see src/claude-context.mjs for why it is imported relatively rather than
+ * through the `agent-sanitizer` specifier the plugin bundle pins).
  * @param {string} dir
  * @returns {string[]}
  */
@@ -147,4 +129,4 @@ export function formatReport(allFindings: Array<{
         decoded: string;
     }>;
 }>): string;
-export { ALERT_FILE, ALERT_ACK_FILE };
+export { CLAUDE_CONTEXT_SUBDIRS, CLAUDE_INSTRUCTION_GLOBS, ALERT_FILE, ALERT_ACK_FILE };

package/types/html.d.mts

@@ -93,11 +93,17 @@ export function urlHost(url: string): string;
  * and HTML attributes (src/href/background/srcset/ping, form action/formaction,
  * meta-refresh). Detection only — the text is never modified; the caller
  * surfaces the threats as a warning.
+ *
+ * `autoFetched` marks a threat that needs no deliberate act to fire — a
+ * rendered image, a stylesheet, a form target, a meta refresh — as opposed to a
+ * link somebody has to follow. Both are reported; the caller uses it to decide
+ * how loudly (see the exfil tier in ./output.mjs).
  * @param {string} text
- * @returns {Array<{ isImage: boolean, reason: string, target: string }> | null}
+ * @returns {Array<{ isImage: boolean, autoFetched: boolean, reason: string, target: string }> | null}
  */
 export function detectExfil(text: string): Array<{
     isImage: boolean;
+    autoFetched: boolean;
     reason: string;
     target: string;
 }> | null;