agent-sanitizer 2.66.6 → 2.67.0

package/src/file-write-tools.mjs

@@ -0,0 +1,96 @@
+/**
+ * The file-editing tools whose input fields are the bytes persisted to disk, as
+ * ONE table, and the reader for the field specs it holds.
+ *
+ * PROBLEM CLASS — the set of file-writing tools restated per consumer. The
+ * fault carve-out that refuses a placeholder-bearing write, the advisories that
+ * stay silent on rehydrated tools, the authored-content sanitizer and the
+ * rehydration layer each kept their own list. A tool added to one list (a new
+ * write-shaped tool, or a renamed field) left the others silently stale, which
+ * is a placeholder persisted over a secret on disk. Every consumer reads this
+ * table instead.
+ *
+ * Package-free and dependency-free by construction: the PreToolUse fault path
+ * imports it relatively and must work exactly when the agent-sanitizer package
+ * failed to load.
+ *
+ * Each entry:
+ *   - `authored` — the fields the model writes, which Layer 3 sanitizes.
+ *   - `placeholders` — every field a redaction placeholder can sit in.
+ *   - `rehydrates` — whether the rehydration layer re-anchors the call onto
+ *     disk bytes (`false`: it refuses a placeholder-bearing call instead).
+ *
+ * A field spec is `key`, or `key[].sub` for `sub` on every element of the
+ * array at `key` (MultiEdit batches its writes as `edits[]`).
+ */
+
+/** @typedef {{ authored: readonly string[], placeholders: readonly string[], rehydrates: boolean }} FileWriteTool */
+
+/**
+ * Null-prototype: the tool name comes from an untrusted payload, and on a plain
+ * object literal `TABLE["constructor"]` answers a truthy inherited value.
+ * @type {Readonly<Record<string, FileWriteTool>>}
+ */
+export const FILE_WRITE_TOOLS = Object.freeze(
+  Object.assign(Object.create(null), {
+    Write: Object.freeze({
+      authored: Object.freeze(["content"]),
+      placeholders: Object.freeze(["content"]),
+      rehydrates: true,
+    }),
+    Edit: Object.freeze({
+      authored: Object.freeze(["new_string"]),
+      placeholders: Object.freeze(["old_string", "new_string"]),
+      rehydrates: true,
+    }),
+    MultiEdit: Object.freeze({
+      authored: Object.freeze(["edits[].new_string"]),
+      placeholders: Object.freeze(["edits[].old_string", "edits[].new_string"]),
+      rehydrates: true,
+    }),
+    NotebookEdit: Object.freeze({
+      authored: Object.freeze(["new_source"]),
+      placeholders: Object.freeze(["new_source"]),
+      rehydrates: false,
+    }),
+  }),
+);
+
+/**
+ * True when `tool` is one of {@link FILE_WRITE_TOOLS}.
+ * @param {unknown} tool
+ * @returns {boolean}
+ */
+export function isFileWriteTool(tool) {
+  return typeof tool === "string" && FILE_WRITE_TOOLS[tool] !== undefined;
+}
+
+const NESTED_SPEC = /^(?<arr>\w+)\[\]\.(?<sub>\w+)$/u;
+
+/**
+ * A field spec, parsed: `{ key }` for a top-level field, or `{ arr, sub }` for
+ * `sub` on every element of the array at `arr`.
+ * @param {string} spec
+ * @returns {{ key: string } | { arr: string, sub: string }}
+ */
+export function parseFieldSpec(spec) {
+  const nested = NESTED_SPEC.exec(spec);
+  if (!nested?.groups) return { key: spec };
+  return { arr: nested.groups.arr, sub: nested.groups.sub };
+}
+
+/**
+ * Every value the field `spec` addresses in `input`: one for a top-level
+ * field, one per array element for a nested one. `null` when the array a
+ * nested spec names is absent, not an array, or empty.
+ * @param {string} spec
+ * @param {any} input
+ * @returns {unknown[] | null}
+ */
+export function fieldValues(spec, input) {
+  const parsed = parseFieldSpec(spec);
+  if ("key" in parsed) return [input?.[parsed.key]];
+  const arr = input?.[parsed.arr];
+  if (!Array.isArray(arr) || arr.length === 0) return null;
+  return arr.map((/** @type {any} */ element) => element?.[parsed.sub]);
+}

package/src/gates.mjs

@@ -5,13 +5,14 @@
  * These are pulled out of `html.mjs` so the package root can re-export them
  * without dragging in the heavy remark/rehype/unified graph: a static
  * `export … from "./html.mjs"` would eagerly evaluate that ~200ms module on
- * every root import, defeating the lazy-load design. This module imports
- * nothing, so re-exporting it is free.
+ * every root import, defeating the lazy-load design. This module imports only
+ * the dependency-free credential vocabulary, so re-exporting it is free.
  *
  * INVARIANT: every gate is a SUPERSET of its parser (a narrower one silently
  * turns its layer off; a needless fire only costs a parse), checked by
  * test/gates-superset.test.mjs.
  */
+import { credentialNames } from "./credential-names.mjs";
 
 // ─── Cheap pre-gates ─────────────────────────────────────────────────────────
 
@@ -117,17 +118,43 @@ export const SECRET_HINT =
 export const SECRET_HINT_EXT =
   /(?:AC|SK)[a-z0-9]{32}|SG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}|sq0csp-[0-9A-Za-z_-]{43}|(?<![0-9])[0-9]{8,10}:[0-9A-Za-z_-]{35}|(?<![0-9a-z])[0-9a-z]{32}-us[0-9]{1,2}|(?<![A-Za-z0-9_-])[MNO][A-Za-z0-9_-]{23,25}\.[A-Za-z0-9_-]{6}\.[A-Za-z0-9_-]{27}|T3BlbkFJ|pypi-AgE|(?<![A-Za-z0-9])AKC[A-Za-z0-9]{10}|(?<![A-Za-z0-9])AP[0-9A-Fa-f][A-Za-z0-9]{8}|:\/\/[^\s:/@]{1,64}:[^\s:/@]{1,64}@|(?:key|pw|pass)["']?[\s:=>]+["']?[A-Za-z0-9_/+-]{20}/i;
 
+/** @type {RegExp | undefined} */
+let _fieldNameHint;
 /**
- * Either alternation against `text` exactly as written.
+ * Every noun the redactor cuts as `<noun> = <value>`, rendered from the same
+ * vocabulary the redactor reads.
+ *
+ * PROBLEM CLASS — a secret pre-gate narrower than the redactor behind it. A
+ * hand-written keyword list misses each noun added to the vocabulary later
+ * (`passphrase = …` reached the model unredacted), so this arm is generated
+ * from credential-names.json and is a superset of the field-value redactor by
+ * construction. Each part is `[a-z0-9]+`, so the alternation holds only
+ * bounded literals and stays linear. Built on first use, never at load: a
+ * malformed vocabulary then throws inside the caller's fail-closed catch.
+ * @returns {RegExp}
+ */
+function fieldNameHint() {
+  return (_fieldNameHint ??= new RegExp(
+    credentialNames().fieldNamePatterns.join("|"),
+    "i",
+  ));
+}
+
+/**
+ * Any hint arm against `text` exactly as written.
  * @param {string} text
  * @returns {boolean}
  */
 function hintMatchesView(text) {
-  return SECRET_HINT.test(text) || SECRET_HINT_EXT.test(text);
+  return (
+    SECRET_HINT.test(text) ||
+    SECRET_HINT_EXT.test(text) ||
+    fieldNameHint().test(text)
+  );
 }
 
 /**
- * True when either pre-gate alternation shape-matches `text`, or the same text
+ * True when any pre-gate arm shape-matches `text`, or the same text
  * with every `\n` removed (the view the engine's `_redact_cross_line` scans, so
  * this stays a superset of the redactor). Two literals OR'd so neither grows
  * into a polynomial-backtracking shape (see SECRET_HINT).

package/src/instructions.mjs

@@ -39,7 +39,11 @@ import {
   payloadVerdict,
   stripInvisible,
 } from "./invisible.mjs";
-import { excludeNodeModules, isInsideDir } from "./claude-context.mjs";
+import {
+  classifyReadFailure,
+  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
@@ -56,6 +60,7 @@ export {
   CLAUDE_INSTRUCTION_GLOBS,
   CLAUDE_LAUNCH_GLOBS,
   CLAUDE_MEMORY_FILES,
+  classifyReadFailure,
   contextScopeContradiction,
   excludeFromContextScan,
   USER_GLOBAL_EVENT_NAMED_GLOBS,
@@ -310,47 +315,26 @@ function containedWritePath(absPath, root) {
 }
 
 /**
- * Classify a glob match for containment: resolve it to a real (symlink-
- * followed) path and decide whether to keep, drop, or reject it. Three
- * outcomes are kept distinct:
- *
- *   - The realpath is contained in `realRoot` → KEEP.
- *   - The match is contained LEXICALLY (the glob pattern itself, followed
- *     literally with no symlink resolution, never leaves `literalRoot`) but its
- *     REALPATH escapes `realRoot` — an in-tree symlink (e.g. a planted
- *     `CLAUDE.md -> /etc/passwd`) whose target lives outside the tree → SKIP.
- *     One planted symlink must not abort scanning every other instruction
- *     file; treat it like the existing dangling-symlink case.
- *   - The match ESCAPES LEXICALLY — the glob pattern itself reaches outside
- *     `literalRoot` via `..` or an absolute path outside the tree, with no
- *     symlink involved → THROW. That is a caller misconfiguration (a scanner
- *     pointed outside its own tree) that must surface loudly, not be silently
- *     skipped.
- *   - The path cannot be resolved at all (ENOENT/EACCES — a dangling symlink or
- *     unreadable entry that still lives inside the tree) → return false to SKIP
- *     it, matching scanInstructionFiles' existing skip-on-unreadable behavior.
+ * Refuse a glob match the caller's PATTERN carried outside the scan root.
  *
- * A genuine resolution failure is never allowed to masquerade as a
- * containment pass: an unresolvable path is skipped, only a successfully
- * resolved path is classified as kept/skipped/thrown above.
+ * A match whose literal path stays inside `literalRoot` is kept whatever it
+ * resolves to: an in-tree symlink to a file outside the tree (a planted
+ * `CLAUDE.md -> /tmp/payload.md`), or a dangling one. The host loads such a
+ * file through the same path, so dropping it reported an unscanned file as
+ * clean. Scanning it is a read; {@link cleanFile} still refuses to write
+ * through it. A match that ESCAPES LEXICALLY — `..` or an absolute glob outside
+ * the tree, no symlink involved — is a caller misconfiguration and throws.
  * @param {string} absPath  absolute path to a glob match
  * @param {string} realRoot  realpath of the scan root
  * @param {string} literalRoot  `cwd`, resolved but NOT symlink-followed
  * @param {string} pattern  the glob that produced this match
- * @returns {boolean} true to keep the match, false to skip it
  */
-function keepContained(absPath, realRoot, literalRoot, pattern) {
-  let real;
-  try {
-    real = realpathSync(absPath);
-  } catch {
-    return false; // dangling/unreadable in-cwd match: skip, do not abort
-  }
-  if (isContained(realRoot, real)) return true;
-  // The glob pattern itself never left the scan root lexically, so the escape
-  // is caused by an in-tree symlink resolving outside the tree, not by the
-  // caller's glob configuration. Skip this one match, do not abort the scan.
-  if (isContained(literalRoot, absPath)) return false;
+function assertContained(absPath, realRoot, literalRoot, pattern) {
+  if (isContained(literalRoot, absPath)) return;
+  // A match outside the tree that resolves to nothing throws its own errno:
+  // still loud, and still refused.
+  const real = realpathSync(absPath);
+  if (isContained(realRoot, real)) return;
   throw new Error(
     `instruction-file path escapes scan root: pattern ${JSON.stringify(
       pattern,
@@ -422,14 +406,12 @@ function ancestorEntries(rel) {
  * Expand `globs` (relative to `cwd`) to absolute file paths, skipping
  * `node_modules`. The glob set is the caller's instruction-file convention.
  *
- * Containment is enforced per match (see {@link keepContained}): a match whose
- * glob pattern itself escapes `cwd` — via `..` or an absolute-path glob
+ * Containment is enforced per match (see {@link assertContained}): a match
+ * whose glob pattern itself escapes `cwd` — via `..` or an absolute-path glob
  * outside the tree — THROWS, since reaching outside the tree is a caller
- * misconfiguration. A match that lexically stays inside `cwd` but resolves
- * (via an in-tree symlink) to a target outside the tree, or that simply
- * cannot be resolved (a dangling symlink or unreadable entry inside the
- * tree), is SKIPPED, so one bad symlink never aborts scanning the rest of the
- * project.
+ * misconfiguration. A match that lexically stays inside `cwd` is RETURNED even
+ * when an in-tree symlink resolves it outside the tree or to nothing, so the
+ * reader decides what an unreadable one means.
  *
  * `exclude` prunes the walk via {@link walkContextGlobs}, so it is handed one
  * root-relative, `/`-separated path per entry. It is composed with, never
@@ -450,37 +432,53 @@ export function findInstructionFiles(
   // One pattern at a time, so a containment failure can name the glob that
   // reached outside the tree.
   for (const pattern of globs)
-    for (const absPath of walkContextGlobs([pattern], cwd, exclude))
-      if (keepContained(absPath, realRoot, literalRoot, pattern))
-        seen.add(absPath);
+    for (const absPath of walkContextGlobs([pattern], cwd, exclude)) {
+      assertContained(absPath, realRoot, literalRoot, pattern);
+      seen.add(absPath);
+    }
   return [...seen];
 }
 
 /**
- * Scan every instruction file matched by `globs` and return only those with
- * findings, each path reported relative to `cwd`. Unreadable/missing files are
- * skipped. Pure scan — no mutation; pair with {@link cleanFile} to strip.
+ * Scan every instruction file matched by `globs`. `findings` lists only the
+ * files with findings; `skipped` lists every file that exists but could not be
+ * read, so a caller never reports an unread file as clean. A missing file
+ * (ENOENT, a dangling symlink) is in neither: no bytes of it can load. Paths
+ * are relative to `cwd`. Pure scan — no mutation; pair with {@link cleanFile}.
  * @param {string[]} globs
  * @param {{ cwd?: string, exclude?: (entry: string) => boolean }} [options]
  *   `exclude` is forwarded to {@link findInstructionFiles}
- * @returns {Array<{ file: string, findings: ReturnType<typeof scanText> }>}
+ * @returns {{
+ *   findings: Array<{ file: string, findings: ReturnType<typeof scanText> }>,
+ *   skipped: Array<{ file: string, reason: string }>,
+ * }}
  */
 export function scanInstructionFiles(
   globs,
   { cwd = process.cwd(), exclude } = {},
 ) {
-  const out = [];
+  const findings = [];
+  const skipped = [];
   for (const file of findInstructionFiles(globs, { cwd, exclude })) {
     let content;
     try {
       content = readFileSync(file, "utf-8");
-    } catch {
-      continue; // missing or unreadable
+    } catch (err) {
+      if (classifyReadFailure(err) === "skipped")
+        skipped.push({
+          file: relative(cwd, file),
+          // classifyReadFailure returns only for an errno, so `code` is set.
+          reason: /** @type {string} */ (
+            /** @type {NodeJS.ErrnoException} */ (err).code
+          ),
+        });
+      continue;
     }
-    const findings = scanText(content);
-    if (findings.length > 0) out.push({ file: relative(cwd, file), findings });
+    const fileFindings = scanText(content);
+    if (fileFindings.length > 0)
+      findings.push({ file: relative(cwd, file), findings: fileFindings });
   }
-  return out;
+  return { findings, skipped };
 }
 
 /**

package/src/output.mjs

@@ -54,6 +54,7 @@ import {
   warningMessages,
 } from "./severity.mjs";
 import { orderedMatches, spliceOrdered } from "./view-map.mjs";
+import { errMessage } from "./err-message.mjs";
 
 /**
  * Closed enum of LIBRARY-OWNED Layer-5 warning codes — the ONLY warning values
@@ -120,18 +121,6 @@ function mapFilterWarning(code) {
   return label;
 }
 
-/**
- * Message from a caught value (`unknown` under strict mode), with one level of
- * cause chain appended so a wrapped failure reads "outer: root".
- * @param {unknown} err
- * @returns {string}
- */
-function errMessage(err) {
-  if (!(err instanceof Error)) return String(err);
-  const cause = err.cause instanceof Error ? `: ${err.cause.message}` : "";
-  return err.message + cause;
-}
-
 /**
  * @typedef {{ text: string, found: string[], note?: string }} RedactResult
  *   Layer-4 result: the redacted text, the category labels redacted, and an

package/src/rehydrate.mjs

@@ -55,6 +55,7 @@
  * {@link rehydrateRedacted}).
  */
 import { applyLayer1, normalizeLoneSurrogates } from "./layer1.mjs";
+import { FILE_WRITE_TOOLS, fieldValues } from "./file-write-tools.mjs";
 import {
   occurrences,
   overlapAwareCount,
@@ -771,42 +772,45 @@ function multiEditDeny(filePath) {
   };
 }
 
+/**
+ * Every string a placeholder can sit in, per one {@link FILE_WRITE_TOOLS}
+ * entry, or null when the input is not well-formed for it: a placeholder field
+ * that is not a string, or a nested field over an absent or empty array.
+ * @param {import("./file-write-tools.mjs").FileWriteTool} entry
+ * @param {any} ti
+ * @returns {string[] | null}
+ */
+function placeholderFields(entry, ti) {
+  const values = [];
+  for (const spec of entry.placeholders) {
+    const found = fieldValues(spec, ti);
+    if (found === null || found.some((v) => typeof v !== "string")) return null;
+    values.push(.../** @type {string[]} */ (found));
+  }
+  return values;
+}
+
 /**
  * True when this tool call could need re-anchoring against the target file's
- * sanitized view: any well-formed Edit or Write (the view may differ from
- * disk even without placeholders, via stripped invisible characters — a
- * hint-free whole-file Write of such a file would silently persist the
- * stripped bytes), and any well-formed MultiEdit (gated on the same
- * grounds).
+ * sanitized view: any well-formed call to a tool whose table entry
+ * `rehydrates`. An Edit or Write qualifies even without placeholders: the view
+ * may differ from disk via stripped invisible characters, and a hint-free
+ * whole-file Write of such a file would silently persist the stripped bytes.
+ *
+ * MultiEdit applies its edits SEQUENTIALLY, each against the result of the
+ * previous, so the span machinery below (which maps one old_string against
+ * one static view) cannot re-anchor it. It is still a candidate: on a
+ * divergent file an unguarded pass-through is both a silent clobber and the
+ * same char-extraction oracle R1 closes for Edit. The dispatch at the bottom
+ * passes the clean-file case through and denies the divergent one.
  * @param {string} tool
  * @param {any} ti
  */
 function isCandidate(tool, ti) {
   if (typeof ti?.file_path !== "string") return false;
-  if (tool === "Edit")
-    return (
-      typeof ti.old_string === "string" && typeof ti.new_string === "string"
-    );
-  if (tool === "Write") return typeof ti.content === "string";
-  // MultiEdit applies its edits SEQUENTIALLY, each against the result of the
-  // previous, so the span machinery below (which maps one old_string against
-  // one static view) cannot re-anchor it. It is still a candidate: on a
-  // divergent file an unguarded pass-through is both a silent clobber (a
-  // placeholder in new_string persisted verbatim) and the same char-extraction
-  // oracle R1 closes for Edit (an old_string matching bytes inside a redacted
-  // span). The dispatch at the bottom pass-throughs the clean-file case and
-  // denies the divergent one with use-single-Edit guidance.
-  if (tool === "MultiEdit")
-    return (
-      Array.isArray(ti.edits) &&
-      ti.edits.length > 0 &&
-      ti.edits.every(
-        (/** @type {any} */ edit) =>
-          typeof edit?.old_string === "string" &&
-          typeof edit?.new_string === "string",
-      )
-    );
-  return false;
+  const entry = FILE_WRITE_TOOLS[tool];
+  if (!entry?.rehydrates) return false;
+  return placeholderFields(entry, ti) !== null;
 }
 
 /**
@@ -838,8 +842,9 @@ export async function rehydrateRedacted(
   // secret; mapping .ipynb JSON is not supported, so refuse with guidance.
   if (
     tool === "NotebookEdit" &&
-    typeof toolInput?.new_source === "string" &&
-    toolInput.new_source.includes(hint)
+    placeholderFields(FILE_WRITE_TOOLS.NotebookEdit, toolInput)?.some((v) =>
+      v.includes(hint),
+    )
   )
     return {
       deny:
@@ -848,16 +853,9 @@ export async function rehydrateRedacted(
         `the secret-bearing cell unchanged, or ask the user to edit it.`,
     };
   if (!isCandidate(tool, toolInput)) return null;
-  const hinted =
-    tool === "Write"
-      ? toolInput.content.includes(hint)
-      : tool === "MultiEdit"
-        ? toolInput.edits.some(
-            (/** @type {{old_string: string, new_string: string}} */ edit) =>
-              edit.old_string.includes(hint) || edit.new_string.includes(hint),
-          )
-        : toolInput.old_string.includes(hint) ||
-          toolInput.new_string.includes(hint);
+  const hinted = /** @type {string[]} */ (
+    placeholderFields(FILE_WRITE_TOOLS[tool], toolInput)
+  ).some((v) => v.includes(hint));
 
   let content;
   try {

package/types/claude-context.d.mts

@@ -37,6 +37,23 @@ export function isInsideDir(dir: string, file: string): boolean;
  * @returns {string}
  */
 export function displayUntrusted(text: string): string;
+/**
+ * PROBLEM CLASS — how a failed instruction-file read is classified. Every
+ * scanner reads this one bucketing; nothing re-derives it from an errno.
+ *
+ * A read failure is never swallowed into an empty findings list — that turns
+ * "we could not read this file" into "this file is fine". Three buckets:
+ *
+ *   - SKIPPED — the file exists and this uid cannot read it (EACCES, EISDIR,
+ *     ELOOP…). Unvetted context, which the caller must report.
+ *   - ABSENT — ENOENT. The path resolves to nothing, and the host loads
+ *     instruction files through the same open, so no bytes can reach the model.
+ *   - THROWN — no errno at all, i.e. a bug. Nothing can be trusted, so the
+ *     error propagates to the caller's failure posture.
+ * @param {unknown} err
+ * @returns {"absent" | "skipped"}  never returns for a non-errno throw
+ */
+export function classifyReadFailure(err: unknown): "absent" | "skipped";
 /**
  * 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/authored-content.d.mts

@@ -8,11 +8,11 @@
  * fatigue, and the doctrine here is precision over recall. The signal is the
  * partition test, which reads this function.
  * @param {string} tool
- * @returns {{ kind: "covered", fields: string[] } | { kind: "exempt", reason: string } | { kind: "undeclared" }}
+ * @returns {{ kind: "covered", fields: readonly string[] } | { kind: "exempt", reason: string } | { kind: "undeclared" }}
  */
 export function authoredScopeDecision(tool: string): {
     kind: "covered";
-    fields: string[];
+    fields: readonly string[];
 } | {
     kind: "exempt";
     reason: string;
@@ -34,8 +34,8 @@ export function sanitizeAuthoredContent(tool: string, toolInput: any): {
     updatedInput: any;
     changed: string[];
 } | null;
-/** @type {Record<string, string[]>} */
-export const AUTHORED_FIELDS: Record<string, string[]>;
+/** @type {Readonly<Record<string, readonly string[]>>} */
+export const AUTHORED_FIELDS: Readonly<Record<string, readonly string[]>>;
 /** @type {Record<string, string>} */
 export const EXEMPT_TOOLS: Record<string, string>;
 /** @type {ReadonlyArray<{ pattern: RegExp, reason: string }>} */

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

@@ -264,14 +264,6 @@ export function makeDeadline(budgetMs: number, now?: () => number): {
 export function scrubUntrustedText(raw: unknown, layer1: (text: string) => {
     cleaned: string;
 }, cap?: number): string;
-/**
- * Message from a caught value, which is `unknown` under strict mode. Appends
- * the cause chain (one level) when the cause is itself an Error so callers
- * get "outer: root" instead of just "outer" when an error wraps another.
- * @param {unknown} err
- * @returns {string}
- */
-export function errMessage(err: unknown): string;
 /**
  * errMessage() for an error whose message may embed attacker-chosen bytes: V8
  * quotes a snippet of the offending input in a JSON.parse SyntaxError, so a hook
@@ -622,6 +614,7 @@ export class EmptyStdinError extends Error {
  * command the reader should actually run.
  */
 export const DEFAULT_MISSING_PACKAGE_REMEDY: "reinstall the hook dependencies (pnpm install) and retry.";
+export { errMessage };
 /**
  * The project the hooks are guarding. Every per-project $TMPDIR store is keyed to
  * it, so it lives here — beside the other shared identity these hooks agree on —
@@ -668,3 +661,4 @@ export type HookIoSharedState = {
     hookgateMarker: string | null;
     hookgateMarkerResolved: boolean;
 };
+import { errMessage } from "../../src/err-message.mjs";

package/types/claude-hooks/lib/placeholder-grammar.d.mts

@@ -94,7 +94,6 @@ export const PLACEHOLDER_LABEL_CHARS: "A-Za-z0-9 ()._-";
  * `grep "\[REDACTED"`) is not mistaken for a placeholder.
  */
 export const PLACEHOLDER_RE: RegExp;
-export const REHYDRATED_TOOLS: Set<string>;
 /**
  * One found token: the exact placeholder text and the dotted field path of the
  * FIRST input field carrying it (empty for a bare string input).

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

@@ -154,8 +154,13 @@ export function failClosedFields(parsedOk: boolean, err: unknown, opts?: {
  * view; with the sanitizer down, rehydration cannot translate it back, so
  * letting the call through would persist the literal placeholder text over the
  * real secret on disk — a destructive clobber, not a missed scan.
- * Package-free by construction (a Set lookup and a walk of the already-parsed
+ * Package-free by construction (a table lookup and a walk of the already-parsed
  * payload), so it holds when the failure IS the missing package.
+ *
+ * Deliberately NOT exhaustive over every clobber path: Bash can also write a
+ * placeholder to disk (`>`, `tee`, `sed -i`, a heredoc), but command strings
+ * mention "[REDACTED" benignly far too often for an ask to hold precision
+ * there. That is an accepted gap, named in THREAT-MODEL.md's carve-out.
  * @param {unknown} input raw parsed PreToolUse payload (undefined if unparsed)
  * @returns {boolean}
  */
@@ -234,7 +239,6 @@ export const PRE_TOOL_USE_MESSAGES: Readonly<{
     remedy: string;
 }>;
 export const REDACTION_HINT: "[REDACTED";
-export const WRITE_SHAPED_TOOLS: Set<string>;
 /**
  * A host-supplied deny gate: given the PreToolUse input, the reason this call
  * must be blocked, or null to let the pipeline continue. Hosts use these for

package/types/credential-names.d.mts

@@ -10,10 +10,11 @@
 export function parseCredentialNames(spec: Record<string, unknown>): CredentialNames;
 /** The validated renderings of the packaged vocabulary, memoized.
  *
- * Read lazily, never at module load: a static importer that crashed at LOAD would
- * abort before its own fail-closed catch installs, and a guardrail that fails to
- * load is a guardrail that fails OPEN. Deferring to first use routes a missing or
- * corrupt data file into the caller's catch instead.
+ * The data arrives with the module (the one static import above, so bundles
+ * carry it), but it is VALIDATED lazily, never at module load: a malformed
+ * vocabulary then throws on first use, inside the caller's fail-closed catch. A
+ * throw at load would abort before that catch installs, and a guardrail that
+ * fails to load is a guardrail that fails OPEN.
  * @returns {CredentialNames} */
 export function credentialNames(): CredentialNames;
 /** @typedef {"trailing" | "any-segment"} CredentialNameScope */

package/types/err-message.d.mts

@@ -0,0 +1,16 @@
+/**
+ * The message of a caught value, which is `unknown` under strict mode.
+ *
+ * PROBLEM CLASS — rendering a caught error as text. The library's warnings and
+ * every hook's failure reason read this one definition, so a wrapped failure
+ * reads "outer: root" everywhere rather than "outer" in some copies.
+ * Dependency-free: the hooks import it relatively and must keep it when the
+ * agent-sanitizer package failed to load.
+ */
+/**
+ * Message from a caught value, with one level of cause chain appended when the
+ * cause is itself an Error.
+ * @param {unknown} err
+ * @returns {string}
+ */
+export function errMessage(err: unknown): string;