agent-sanitizer 2.61.3 → 2.62.1

package/src/instructions.mjs

@@ -22,21 +22,16 @@
  */
 import {
   readFileSync,
-  writeFileSync,
   globSync,
-  renameSync,
   lstatSync,
   fstatSync,
   realpathSync,
   openSync,
-  fsyncSync,
-  fchmodSync,
   closeSync,
-  unlinkSync,
   constants,
 } from "node:fs";
-import { randomBytes } from "node:crypto";
-import { join, relative, resolve, isAbsolute, dirname, sep } from "node:path";
+import { basename, join, relative, resolve, dirname, sep } from "node:path";
+import { atomicReplaceFile } from "./atomic-replace.mjs";
 import {
   findLongRuns,
   SCATTERED_THRESHOLD,
@@ -44,7 +39,8 @@ import {
   payloadVerdict,
   stripInvisible,
 } from "./invisible.mjs";
-import { excludeNodeModules } from "./claude-context.mjs";
+import { excludeNodeModules, isInsideDir } from "./claude-context.mjs";
+import { compatGlobs } from "./glob-compat.mjs";
 
 // The library's public door onto Claude Code's context scope. The definitions
 // live in a dependency-free data module because the SessionStart hook imports
@@ -269,21 +265,38 @@ export function scanText(content) {
 }
 
 /**
- * True when `realChild` is `realRoot` itself or lives beneath it. Both inputs
- * must already be realpath-resolved absolute paths. Containment is tested with
- * `relative(root, child)`: the result is "" when they are the same path, and
- * for a true descendant it is a forward path with no `..` segment and is not
- * itself absolute — so a sibling like `/proj-evil` (relative => `../proj-evil`)
- * is correctly rejected.
- * @param {string} realRoot
- * @param {string} realChild
+ * True when `child` is `root` itself or beneath it: {@link isInsideDir} widened
+ * by the root (a glob can match the scan root; a write never targets it).
+ * @param {string} root
+ * @param {string} child
  * @returns {boolean}
  */
-function isContained(realRoot, realChild) {
-  const rel = relative(realRoot, realChild);
-  return (
-    rel === "" ||
-    (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel))
+function isContained(root, child) {
+  return relative(root, child) === "" || isInsideDir(root, child);
+}
+
+/**
+ * The path a write to `absPath` may use, proven inside `root`: the realpath of
+ * its DIRECTORY joined with its own name, checked against the realpath of
+ * `root`. Resolving the directory catches a directory symlink in the tree
+ * (`.claude/rules -> ~/.claude/rules`); the final component stays unresolved so
+ * cleanFile's `O_NOFOLLOW` open still refuses a file symlink. Every later step
+ * of the write uses the returned path. Throws when it would land outside `root`.
+ * @param {string} absPath
+ * @param {string} root
+ * @returns {string}
+ */
+function containedWritePath(absPath, root) {
+  const realRoot = realpathSync(root);
+  const target = join(
+    realpathSync(dirname(resolve(absPath))),
+    basename(absPath),
+  );
+  if (isInsideDir(realRoot, target)) return target;
+  throw new Error(
+    `refusing to clean outside the root ${JSON.stringify(
+      realRoot,
+    )}: ${JSON.stringify(absPath)} resolves to ${JSON.stringify(target)}`,
   );
 }
 
@@ -347,9 +360,10 @@ function keepContained(absPath, realRoot, literalRoot, pattern) {
  * calls `exclude` once with an entry's bare name and again with its
  * root-relative path, so a predicate holding `build` cannot tell a top-level
  * `build/` from a tracked `src/build/` and prunes both; under an absolute
- * pattern it is handed absolute paths and matches neither. A Dirent carries an
- * absolute `parentPath`, which normalizes to exactly one root-relative,
- * `/`-separated entry per walked directory whatever shape the pattern has.
+ * pattern it is handed absolute paths and matches neither. A Dirent's
+ * `parentPath`, resolved against `cwd` (not the process's: a literal prefix's
+ * directories arrive RELATIVE to `cwd`, and a bare join would prune `.claude/`),
+ * normalizes to one root-relative, `/`-separated entry per walked directory.
  * @param {string[]} globs
  * @param {string} cwd
  * @param {(entry: string) => boolean} [exclude]
@@ -364,14 +378,35 @@ export function walkContextGlobs(globs, cwd, exclude) {
   // under a `.claude/worktrees/` checkout.
   /** @param {import("node:fs").Dirent} dirent @returns {string} */
   const absolute = (dirent) => resolve(root, dirent.parentPath, dirent.name);
-  return globSync(globs, {
-    cwd,
-    withFileTypes: true,
-    exclude: (dirent) => {
-      const entry = relative(root, absolute(dirent)).split(sep).join("/");
-      return excludeNodeModules(entry) || (exclude?.(entry) ?? false);
-    },
-  }).map(absolute);
+  /** @param {string} entry @returns {boolean} */
+  const excluded = (entry) =>
+    excludeNodeModules(entry) || (exclude?.(entry) ?? false);
+  return (
+    globSync(compatGlobs(globs), {
+      cwd,
+      withFileTypes: true,
+      exclude: (dirent) =>
+        excluded(relative(root, absolute(dirent)).split(sep).join("/")),
+    })
+      .map(absolute)
+      // Node never consults `exclude` on some literal segments (the `.claude`
+      // compatGlobs spells out on an affected Node is one), so a match under a
+      // directory the caller pruned is dropped here instead.
+      .filter((path) => !ancestorEntries(relative(root, path)).some(excluded))
+  );
+}
+
+/**
+ * Every directory above `rel` (a root-relative path), as `/`-separated
+ * entries outermost first: `a/b/c.md` gives `a` and `a/b`.
+ * @param {string} rel
+ * @returns {string[]}
+ */
+function ancestorEntries(rel) {
+  const segments = rel.split(sep);
+  return segments
+    .slice(0, -1)
+    .map((_, i) => segments.slice(0, i + 1).join("/"));
 }
 
 /**
@@ -439,81 +474,6 @@ export function scanInstructionFiles(
   return out;
 }
 
-/**
- * Atomically replace `absPath`'s contents with `data`, preserving `mode`.
- *
- * Writes to a sibling temp in the same directory, then `rename`s it over the
- * original (same dir => same filesystem => the rename is atomic, not a
- * cross-device copy). The temp name is UNPREDICTABLE (`tmpName()` defaults to
- * crypto-random) and the temp is created exclusively (O_CREAT|O_EXCL): if the
- * path already exists — including an attacker-planted symlink at a guessable
- * temp name — the open fails (EEXIST) and does NOT follow the link to clobber
- * its target. On the rare collision we fail loud rather than retry into a
- * different attacker-controlled path.
- *
- * Crash-safety (matching the doc claim): the temp fd is `fsync`ed before the
- * rename and the directory fd is `fsync`ed after it, so a power loss can't leave
- * the renamed name pointing at unflushed/empty data or lose the rename itself.
- * The EXACT `mode` is applied with `fchmod` (openSync's create mode is
- * umask-masked, so it alone would drop bits), and a failed write/sync `unlink`s
- * the temp before rethrowing so no partial temp leaks. `tmpName` and `remove`
- * are injectable fault-injection seams for tests (force a known temp path; drive
- * a cleanup-unlink failure); production callers never pass them.
- * @param {string} absPath
- * @param {string} data
- * @param {number} mode
- * @param {() => string} [tmpName]
- * @param {(path: string) => void} [remove]
- */
-export function atomicReplaceFile(
-  absPath,
-  data,
-  mode,
-  tmpName = () => `.${randomBytes(12).toString("hex")}.tmp`,
-  remove = unlinkSync,
-) {
-  const dir = dirname(absPath);
-  const tmp = join(dir, tmpName());
-  // Exclusive create: EEXIST (incl. a planted symlink at the temp name)
-  // propagates directly — no temp of ours exists yet, so nothing to clean up
-  // and we must never unlink the attacker's pre-existing path.
-  const fd = openSync(
-    tmp,
-    constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL,
-    mode,
-  );
-  try {
-    // writeFileSync(fd, …) loops until every byte is written (a bare writeSync
-    // can short-write a large payload); it does not close the caller's fd.
-    writeFileSync(fd, data);
-    // Preserve the EXACT mode: openSync's create mode is umask-masked, fchmod is
-    // not, so this restores bits (e.g. group-write) the umask would have dropped.
-    fchmodSync(fd, mode);
-    // Flush the temp's bytes before the rename, else a crash can expose the
-    // renamed name pointing at empty/partial content.
-    fsyncSync(fd);
-  } catch (err) {
-    closeSync(fd);
-    try {
-      remove(tmp);
-    } catch {
-      // Best-effort cleanup only: rethrow the ORIGINAL failure below, not a
-      // secondary unlink error, so the real cause stays loud.
-    }
-    throw err;
-  }
-  closeSync(fd);
-  renameSync(tmp, absPath);
-  // fsync the DIRECTORY so the rename (a directory metadata change) is durable
-  // across a crash, not just the file's data blocks.
-  const dirFd = openSync(dir, constants.O_RDONLY);
-  try {
-    fsyncSync(dirFd);
-  } finally {
-    closeSync(dirFd);
-  }
-}
-
 /**
  * Strip payload-capable invisible characters from `absPath` in place. Returns
  * `true` when the file's bytes actually changed (a payload {@link scanText}
@@ -554,20 +514,32 @@ export function atomicReplaceFile(
  * a temp file in the same directory which is then `rename`d over the original
  * (preserving the original file mode), fsync'd for crash-safety.
  *
- * Throws if the file cannot be read or written (the caller decides whether an
- * unwritable contaminated file is fatal or falls back to alerting).
+ * The rewrite must land strictly inside `root`, judged on realpaths (see
+ * {@link containedWritePath}): `O_NOFOLLOW` guards only the final component, so
+ * a directory symlink would otherwise carry it outside. `root` is required so
+ * no caller writes unbounded.
+ *
+ * Throws if the file cannot be read or written, or lies outside `root`.
  * @param {string} absPath
- * @param {(path: string) => import("node:fs").Stats} [lstat] injectable
- *   pre-rename recheck stat (fault-injection seam, mirrors
- *   {@link atomicReplaceFile}'s `tmpName`): lets a test drive the concurrent
- *   write/symlink-swap that the TOCTOU guard exists to catch, which is otherwise
- *   unreachable from this fully-synchronous path. Defaults to `lstatSync`.
+ * @param {{ root: string,
+ *   lstat?: (path: string) => import("node:fs").Stats }} options
+ *   `root` bounds the write. `lstat` is the injectable pre-rename recheck stat
+ *   (fault-injection seam) that lets a test drive the TOCTOU guard.
  * @returns {boolean}
  */
-export function cleanFile(absPath, lstat = lstatSync) {
+export function cleanFile(
+  absPath,
+  { root, lstat = lstatSync } = /** @type {any} */ ({}),
+) {
+  // The `{}` default routes a bare `cleanFile(path)` to the TypeError below.
+  if (typeof root !== "string")
+    throw new TypeError(
+      "cleanFile requires options.root, the directory the rewrite must stay inside",
+    );
+  const path = containedWritePath(absPath, root);
   let fd;
   try {
-    fd = openSync(absPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
   } catch (err) {
     // O_NOFOLLOW on a symlink fails ELOOP (some libc report EMLINK); surface
     // the same "regular files only" contract the old lstat check did. Other
@@ -609,7 +581,7 @@ export function cleanFile(absPath, lstat = lstatSync) {
     // Re-verify the on-path file against the open-time snapshot before writing:
     // an inode/size/mtime change (or a swap to a symlink) means someone modified
     // it under us, so fail loud rather than clobber their write (lost update).
-    const after = lstat(absPath);
+    const after = lstat(path);
     if (
       after.isSymbolicLink() ||
       after.ino !== before.ino ||
@@ -623,7 +595,7 @@ export function cleanFile(absPath, lstat = lstatSync) {
       );
     // `before.mode` is the opened regular file's mode. A crash before the rename
     // leaves the original intact; after it the new content is fully present.
-    atomicReplaceFile(absPath, stripped, before.mode);
+    atomicReplaceFile(path, stripped, before.mode);
     return true;
   } finally {
     closeSync(fd);

package/src/rehydrate.mjs

@@ -195,31 +195,24 @@ async function rehydrateEdit(
       // (the model supplied the secret's real bytes itself, e.g. a rotation)
       // extracts nothing and is left to the literal resolver below.
       const diskSpans = pairDiskSpans(view, deletions);
-      let intrusion = null;
-      for (const matchStart of occurrences(content, oldS)) {
+      const intrudes = occurrences(content, oldS).some((matchStart) => {
         const matchEnd = matchStart + oldS.length;
-        const secret = diskSpans.find(
+        return diskSpans.some(
           (span) =>
             matchStart < span.end &&
             span.start < matchEnd &&
             !(matchStart <= span.start && span.end <= matchEnd),
         );
-        if (secret) {
-          intrusion = { matchStart, matchEnd, secret };
-          break;
-        }
-      }
-      // Report both byte ranges. The refusal is conservative — it fires on an
-      // overlap with the redacted span the caller cannot see — so the caller
-      // needs the ranges to tell a true overlap from a mis-sized redaction.
-      if (intrusion)
+      });
+      // No offsets: a span is the secret's length, and the match's position
+      // against it says how much of the secret the probe covered.
+      if (intrudes)
         return {
           deny:
             `old_string does not appear in the sanitized view of ${ti.file_path}; on disk ` +
-            `it matches bytes ${intrusion.matchStart}-${intrusion.matchEnd}, which fall ` +
-            `inside a ${hint}…] redacted secret at bytes ${intrusion.secret.start}-` +
-            `${intrusion.secret.end} that are hidden from your view; edit only text you ` +
-            `can see (include each placeholder whole), or ask the user to make this change`,
+            `it matches text inside a ${hint}…] redacted secret that is hidden from your ` +
+            `view; edit only text you can see (include each placeholder whole), or ask ` +
+            `the user to make this change`,
         };
       const literalRes = rehydrateNewString(
         oldS,
@@ -351,11 +344,12 @@ async function rehydrateEdit(
     if (exposed > 0) return { deny: exposureDeny(exposed) };
   }
 
+  const stripped = strippedChars(span.diskText, span.cleanedText);
   const notes = [
     span.pairs.length > 0 &&
       `${hint}…] placeholders were resolved to the file's real secret values (still hidden from you)`,
-    span.invisibleBytes > 0 &&
-      `the matched region carries ${span.invisibleBytes} invisible/control character(s) stripped from your view; they are replaced along with it`,
+    stripped.n > 0 &&
+      `the matched region carries ${strippedPhrase(stripped)} stripped from your view; they are replaced along with it`,
   ].filter(Boolean);
   return {
     updatedInput: { ...ti, old_string: span.diskText, new_string: newRes.text },
@@ -438,17 +432,17 @@ function foreignPlaceholders(out, hint, viewText, secretSpans) {
  * region reaches that edge — re-attach those explicitly, since `diskOffset`
  * keeps boundary runs outside the span in both directions.
  *
- * `restoredChars` counts UTF-16 code units, matching the "character(s)" prose
- * in {@link writeContext}.
+ * `restoredChars` is a code-point {@link SpacedCount} ({@link strippedChars}).
  * @param {WriteRestoreContext} ctx per-Write invariants shared by both regions
  * @param {number} viewStart
  * @param {number} viewEnd
  * @param {string} fallback the model's own bytes for this region
- * @returns {{text: string, pairs: readonly {placeholder: string, original: string, start: number}[], restoredChars: number} | {deny: string}}
+ * @returns {{text: string, pairs: readonly {placeholder: string, original: string, start: number}[], restoredChars: SpacedCount<"codePoint">} | {deny: string}}
  */
 function restoreWriteRegion(ctx, viewStart, viewEnd, fallback) {
   const { content, cleaned, view, deletions } = ctx;
-  if (viewStart >= viewEnd) return { text: "", pairs: [], restoredChars: 0 };
+  if (viewStart >= viewEnd)
+    return { text: "", pairs: [], restoredChars: NO_STRIPS };
   const span = resolveSpan(
     content,
     cleaned,
@@ -478,15 +472,54 @@ function restoreWriteRegion(ctx, viewStart, viewEnd, fallback) {
         ctx.filePath,
         "use Edit for the changed region",
       );
-    return { text: fallback, pairs: [], restoredChars: 0 };
+    return { text: fallback, pairs: [], restoredChars: NO_STRIPS };
   }
   return {
     text: diskText,
     pairs: span.pairs,
-    restoredChars: diskText.length - span.cleanedText.length,
+    restoredChars: strippedChars(diskText, span.cleanedText),
+  };
+}
+
+/**
+ * A count tagged with the {@link import("./view-map.mjs").OffsetSpace} it was
+ * measured in, so the prose that renders it takes its unit from the value.
+ * @template {import("./view-map.mjs").OffsetSpace} S
+ * @typedef {{ readonly n: number, readonly space: S }} SpacedCount
+ */
+
+/** @type {SpacedCount<"codePoint">} */
+const NO_STRIPS = Object.freeze({ n: 0, space: "codePoint" });
+
+// The noun each count space renders as; only code points have one, so a count
+// in another space fails the type check at {@link strippedPhrase}.
+const STRIPPED_NOUN = Object.freeze({
+  codePoint: "invisible/control character(s)",
+});
+
+/**
+ * How many characters Layer 1 stripped from `diskText` to leave `cleanedText`,
+ * in code points (a UTF-16 difference double-counts every astral strip).
+ * @param {string} diskText on-disk bytes of a region
+ * @param {string} cleanedText that region's Layer-1 view
+ * @returns {SpacedCount<"codePoint">}
+ */
+function strippedChars(diskText, cleanedText) {
+  return {
+    n: [...diskText].length - [...cleanedText].length,
+    space: "codePoint",
   };
 }
 
+/**
+ * `count` as the prose names it, the unit read from its space.
+ * @param {SpacedCount<"codePoint">} count
+ * @returns {string}
+ */
+function strippedPhrase(count) {
+  return `${count.n} ${STRIPPED_NOUN[count.space]}`;
+}
+
 /**
  * The per-Write invariants `restoreWriteRegion` needs for both regions,
  * bundled once in {@link rehydrateWrite} instead of threaded as positional
@@ -537,7 +570,7 @@ async function rehydrateWrite(ti, content, cleaned, view, deletions, io, hint) {
       updatedInput: { ...ti, content },
       context: writeContext(
         ti.file_path,
-        content.length - cleaned.length,
+        strippedChars(content, cleaned),
         view.pairs.length,
         hint,
       ),
@@ -669,25 +702,36 @@ async function rehydrateWrite(ti, content, cleaned, view, deletions, io, hint) {
     updatedInput: { ...ti, content: out },
     context: writeContext(
       ti.file_path,
-      prefix.restoredChars + suffix.restoredChars,
+      addCounts(prefix.restoredChars, suffix.restoredChars),
       middleSpans.length + prefix.pairs.length + suffix.pairs.length,
       hint,
     ),
   };
 }
 
+/**
+ * Sum of two counts in one space; two spaces do not type-check.
+ * @template {import("./view-map.mjs").OffsetSpace} S
+ * @param {SpacedCount<S>} a
+ * @param {SpacedCount<S>} b
+ * @returns {SpacedCount<S>}
+ */
+function addCounts(a, b) {
+  return { n: a.n + b.n, space: a.space };
+}
+
 /**
  * Model-facing context line for a rewritten Write input.
  * @param {string} filePath
- * @param {number} restoredChars UTF-16 code units of stripped characters restored with the unchanged regions
+ * @param {SpacedCount<"codePoint">} restored stripped characters restored with the unchanged regions
  * @param {number} secretCount placeholders resolved (spliced or restored)
  * @param {string} hint placeholder prefix
  */
-function writeContext(filePath, restoredChars, secretCount, hint) {
+function writeContext(filePath, restored, secretCount, hint) {
   const parts = [];
-  if (restoredChars > 0)
+  if (restored.n > 0)
     parts.push(
-      `${restoredChars} invisible/control character(s) stripped from your view of ` +
+      `${strippedPhrase(restored)} stripped from your view of ` +
         `${filePath} were restored from disk in the regions your Write left unchanged.`,
     );
   if (secretCount > 0)

package/src/view-map.mjs

@@ -346,9 +346,9 @@ function mapViewOffset(pairs, offset) {
  * Resolve view span [viewStart, viewEnd) to its on-disk text and the redaction
  * pairs it wholly contains, mapping across placeholder expansion (view →
  * cleaned) and stripped invisible runs (cleaned → disk). Null when a boundary
- * cuts through a placeholder. `invisibleBytes` counts stripped characters
- * inside the span (replaced along with it); runs at the boundaries stay
- * outside and are preserved. `cleanedText` is the span's Layer-1 view — the
+ * cuts through a placeholder. Stripped runs inside the span are replaced along
+ * with it; runs at the boundaries stay outside and are preserved. `cleanedText`
+ * is the span's Layer-1 view — the
  * caller MUST verify that re-cleaning `diskText` reproduces it before acting:
  * greedy alignment is ambiguous when a deleted run's edge character equals the
  * adjacent kept character (an ANSI sequence ending in `m` before a kept `m`),
@@ -379,7 +379,6 @@ export function resolveSpan(
   return {
     diskText,
     cleanedText: cleaned.slice(cleanedStart, cleanedEnd),
-    invisibleBytes: diskText.length - (cleanedEnd - cleanedStart),
     pairs: view.pairs.filter(
       (pair) =>
         pair.start >= viewStart &&

package/src/warnings.mjs

@@ -14,8 +14,11 @@
  *
  * Every function returns COUNTS and reasons, never the removed content itself:
  * echoing what Layer 2 just spliced out would re-inject the payload into the
- * very context the splice removed it from. This module imports nothing.
+ * very context the splice removed it from. The target `describeExfil` names is
+ * not removed content but is still scanned-input text, so it goes through
+ * {@link displayUntrusted}.
  */
+import { displayUntrusted } from "./claude-context.mjs";
 
 /**
  * Layer 1's lone-surrogate warning. A bare constant rather than a literal at
@@ -93,7 +96,7 @@ export function describeExfil(threats) {
     ...new Set(
       threats.map(
         (threat) =>
-          `${threat.isImage ? "image" : "link"} to ${threat.target}: ${threat.reason}`,
+          `${threat.isImage ? "image" : "link"} to ${displayUntrusted(threat.target)}: ${threat.reason}`,
       ),
     ),
   ];

package/types/atomic-replace.d.mts

@@ -0,0 +1,14 @@
+/**
+ * Atomically replace `absPath`'s contents with `data`, preserving `mode`: write
+ * an exclusively created (O_EXCL, unpredictable-name) sibling temp, fsync it,
+ * `rename` it over the original, fsync the directory. O_EXCL means a planted
+ * symlink at the temp name fails EEXIST instead of being followed. A failed
+ * write unlinks the temp before rethrowing. `tmpName` and `remove` are
+ * fault-injection seams for tests.
+ * @param {string} absPath
+ * @param {string} data
+ * @param {number} mode
+ * @param {() => string} [tmpName]
+ * @param {(path: string) => void} [remove]
+ */
+export function atomicReplaceFile(absPath: string, data: string, mode: number, tmpName?: () => string, remove?: (path: string) => void): void;

package/types/claude-context.d.mts

@@ -14,21 +14,29 @@
  */
 export function ancestorInstructionFiles(dir: string): string[];
 /**
- * Whether `file` lives inside `dir`. Lexical, on already-absolute paths, and the
- * bound on where an instruction-file scanner may REWRITE: a file above the scan
- * root is shared with every other project beneath that root, so it is reported
- * rather than silently edited. Both scanners ask this — one for a target it
- * globbed, one for a path an event handed it — and a copy each is a copy that
- * can drift into rewriting a file the other would not.
- *
- * Symlinks are deliberately not resolved: the guard that stops a link from
- * redirecting the write has to live at the write itself (cleanFile opens
- * O_NOFOLLOW), and resolving here would only duplicate it a check too early.
+ * Whether `file` lives strictly inside `dir` — the ONE containment predicate:
+ * both scanners gate their auto-clean on it, the glob walk keeps a match by it,
+ * and cleanFile refuses a write it rejects. A file above the scan root is
+ * shared with other projects, so it is reported rather than edited.
+ *
+ * Lexical; cleanFile hands it realpaths, which stops a directory symlink from
+ * redirecting a rewrite. `..` is tested as a whole SEGMENT, so `..notes.md` is
+ * inside and `../x` is not.
  * @param {string} dir
  * @param {string} file
  * @returns {boolean}
  */
 export function isInsideDir(dir: string, file: string): boolean;
+/**
+ * Untrusted text made safe to render into a report, stderr or model context:
+ * every {@link DISPLAY_UNSAFE} code point becomes a visible `\u{XXXX}` escape,
+ * everything else is kept. Scanners pass every path from a possibly hostile
+ * tree and every reason that may quote one through it. Display only — the
+ * result never opens a file.
+ * @param {string} text
+ * @returns {string}
+ */
+export function displayUntrusted(text: string): string;
 /**
  * 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

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

@@ -1,13 +1,3 @@
-/**
- * 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,

package/types/glob-compat.d.mts

@@ -0,0 +1,28 @@
+/**
+ * Whether the globSync of Node `version` (`process.versions.node`'s shape)
+ * misses a dot-named segment after a `**`.
+ * @param {string} version
+ * @returns {boolean}
+ */
+export function globstarSkipsDotSegments(version: string): boolean;
+/**
+ * `pattern` as patterns the broken globSync answers.
+ *
+ * Each `**\/` before a dot segment spans zero directories or one or more:
+ * dropping it is the first case and `**\/*\/` the second, and neither puts a
+ * dot segment straight after a `**`. A `*` never matches a dot-named directory,
+ * so the halves can match less than a fixed Node does (which enters a dot
+ * directory named like the segment after `**`), never more. A dot segment the
+ * rewrite cannot reach throws rather than silently matching nothing.
+ * @param {string} pattern
+ * @returns {string[]}
+ */
+export function expandDotGlobstar(pattern: string): string[];
+/**
+ * `patterns` ready for this runtime's globSync: rewritten by
+ * {@link expandDotGlobstar} on an affected Node, untouched otherwise.
+ * @param {string[]} patterns
+ * @param {string} [version]  defaults to the running Node
+ * @returns {string[]}
+ */
+export function compatGlobs(patterns: string[], version?: string): string[];