agent-sanitizer 2.66.6 → 2.67.0

package/README.md

@@ -51,18 +51,20 @@ Split into subpaths so the heavy HTML dependency stays opt-in. **Seam** names
 the callback you inject for the agent-specific concern; `—` is a pure transform,
 `fs (direct)` does its own file I/O instead of taking one.
 
-| Layer | Import          | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Seam                        |
-| ----- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
-| 1     | `/invisible`    | Strip zero-width, bidi, variation-selector and tag chars + ANSI/SGR escapes. Preserves ZWNJ/ZWJ for Arabic/Indic/emoji. Zero deps.                                                                                                                                                                                                                                                                                                                                                                                                     | —                           |
-| 1     | `/layer1`       | Layer 1 in one call: the invisible-char and ANSI strips run to a FIXED POINT over each other (either removal can reconstitute what the other matches), then a residual control-introducer sweep closes it — not a two-step pipeline a caller can reproduce in a fixed order. `applyLayer1` leaves an unpaired UTF-16 surrogate in place; `applyLayer1WellFormed` also maps it to U+FFFD, which is the string `/output` shows a model — take that one when the result feeds a redactor, an offset calculation or a view map. Zero deps. | —                           |
-| 2     | `/html`         | Splice out HTML comments and elements hidden via `display:none`, off-screen, white-on-white, `hidden`. Each splice leaves a keyed, round-trippable placeholder.                                                                                                                                                                                                                                                                                                                                                                        | —                           |
-| 3     | `/html`         | Detect exfil-shaped URLs (payloads in query/path, embedded creds, `data:`/`javascript:`, off-origin redirects) and confusable HOSTS (`аpple.com`). Reports only — never rewrites.                                                                                                                                                                                                                                                                                                                                                      | —                           |
-| —     | `/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` (optional)           |
-| —     | `/instructions` | Scan/auto-clean `CLAUDE.md`, `AGENTS.md`, `SKILL.md`, etc., decoding Unicode-tag + zero-width-binary payloads.                                                                                                                                                                                                                                                                                                                                                                                                                         | `fs` (direct)               |
-| —     | `/prompt`       | Classify a prompt pass / note / block on payload-capable invisible/ANSI content (inert escapes get the note).                                                                                                                                                                                                                                                                                                                                                                                                                          | —                           |
-| 1–5   | `/output`       | Run Layers 1–4 over structured tool output, preserving shape. The Layer-5 slot takes a delete-only filter.                                                                                                                                                                                                                                                                                                                                                                                                                             | `redact`, `filterInjection` |
-| —     | `/rehydrate`    | Re-anchor a model Edit or whole-file Write composed from the _sanitized_ view back onto real bytes; gate MultiEdit on a verified view==disk; 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`.                                                                                                                                                                                                                                                                                                                                                                             | —                           |
+| Layer | Import                      | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Seam                        |
+| ----- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
+| 1     | `/invisible`                | Strip zero-width, bidi, variation-selector and tag chars + ANSI/SGR escapes. Preserves ZWNJ/ZWJ for Arabic/Indic/emoji. Zero deps.                                                                                                                                                                                                                                                                                                                                                                                                     | —                           |
+| 1     | `/layer1`                   | Layer 1 in one call: the invisible-char and ANSI strips run to a FIXED POINT over each other (either removal can reconstitute what the other matches), then a residual control-introducer sweep closes it — not a two-step pipeline a caller can reproduce in a fixed order. `applyLayer1` leaves an unpaired UTF-16 surrogate in place; `applyLayer1WellFormed` also maps it to U+FFFD, which is the string `/output` shows a model — take that one when the result feeds a redactor, an offset calculation or a view map. Zero deps. | —                           |
+| 2     | `/html`                     | Splice out HTML comments and elements hidden via `display:none`, off-screen, white-on-white, `hidden`. Each splice leaves a keyed, round-trippable placeholder.                                                                                                                                                                                                                                                                                                                                                                        | —                           |
+| 3     | `/html`                     | Detect exfil-shaped URLs (payloads in query/path, embedded creds, `data:`/`javascript:`, off-origin redirects) and confusable HOSTS (`аpple.com`). Reports only — never rewrites.                                                                                                                                                                                                                                                                                                                                                      | —                           |
+| —     | `/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` (optional)           |
+| —     | `/instructions`             | Scan/auto-clean `CLAUDE.md`, `AGENTS.md`, `SKILL.md`, etc., decoding Unicode-tag + zero-width-binary payloads.                                                                                                                                                                                                                                                                                                                                                                                                                         | `fs` (direct)               |
+| —     | `/prompt`                   | Classify a prompt pass / note / block on payload-capable invisible/ANSI content (inert escapes get the note).                                                                                                                                                                                                                                                                                                                                                                                                                          | —                           |
+| 1–5   | `/output`                   | Run Layers 1–4 over structured tool output, preserving shape. The Layer-5 slot takes a delete-only filter.                                                                                                                                                                                                                                                                                                                                                                                                                             | `redact`, `filterInjection` |
+| —     | `/rehydrate`                | Re-anchor a model Edit or whole-file Write composed from the _sanitized_ view back onto real bytes; gate MultiEdit on a verified view==disk; 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`.                                                                                                                                                                                                                                                                                                                                                                             | —                           |
+| —     | `/credential-names-matcher` | Build an env-var NAME matcher from the credential-noun vocabulary: `credentialNameMatcher({ scope })` for a redactor (`"trailing"`) or an env scrub (`"any-segment"`), linear in the name's length.                                                                                                                                                                                                                                                                                                                                    | —                           |
+| —     | `/credential-names`         | The credential-noun vocabulary itself, as JSON — the same file the Python package reads.                                                                                                                                                                                                                                                                                                                                                                                                                                               | —                           |
 
 See [`THREAT-MODEL.md`](./THREAT-MODEL.md) for per-vector detail.
 
@@ -471,12 +473,18 @@ import {
   scanInstructionFiles,
   cleanFile,
 } from "agent-sanitizer/instructions";
-const findings = scanInstructionFiles(["CLAUDE.md", "**/SKILL.md"], {
-  cwd: projectDir,
-  // Skip what git says is not this checkout's source: ignored directories and
-  // nested worktrees. Ignored FILES (CLAUDE.local.md) are still scanned.
-  exclude: contextScanExclude(projectDir),
-});
+const { findings, skipped } = scanInstructionFiles(
+  ["CLAUDE.md", "**/SKILL.md"],
+  {
+    cwd: projectDir,
+    // Skip what git says is not this checkout's source: ignored directories and
+    // nested worktrees. Ignored FILES (CLAUDE.local.md) are still scanned.
+    exclude: contextScanExclude(projectDir),
+  },
+);
+// `skipped` lists files that exist but could not be read ({ file, reason }).
+// Treat them as unvetted: they were never checked.
+if (skipped.length) console.warn("not scanned:", skipped);
 // `root` is required: a rewrite whose realpath leaves it throws instead.
 for (const { file } of findings)
   cleanFile(`${projectDir}/${file}`, { root: projectDir });

package/bin/sanitize-cli.mjs

@@ -17,7 +17,7 @@
  *   sanitize           { text, html? }            -> { cleaned, found, warnings, notes, splices? }
  *   sanitizeText       { text, html?, exfilScan?, flagDigestValues? } -> { cleaned, warnings, notes, modified, sgrNote }
  *   classifyPrompt     { text }                    -> { action, reason? }
- *   scanInstructionFiles { globs, cwd? }           -> { findings: [{ file, findings }] }
+ *   scanInstructionFiles { globs, cwd? }           -> { findings: [{ file, findings }], skipped: [{ file, reason }] }
  *     Skips `node_modules`, the directories git ignores wholesale, and any
  *     nested worktree — none of them is the scanned checkout's own source.
  *   cleanFile          { path, root? }             -> { changed }
@@ -166,12 +166,10 @@ export const OPS = {
     // Whole-tree scope: a gitignored build directory and a nested worktree are
     // not this checkout's source, so a finding from one names a file the caller
     // does not own — and `cleanFile` would rewrite it.
-    return {
-      findings: scanInstructionFiles(globs, {
-        cwd,
-        exclude: contextScanExclude(cwd),
-      }),
-    };
+    return scanInstructionFiles(globs, {
+      cwd,
+      exclude: contextScanExclude(cwd),
+    });
   },
 
   /** @param {Record<string, unknown>} req */

package/claude-hooks/lib/authored-content.mjs

@@ -53,6 +53,10 @@
  */
 import { lazyImport } from "./hook-io.mjs";
 import { readKnob } from "./knobs.mjs";
+import {
+  FILE_WRITE_TOOLS,
+  parseFieldSpec,
+} from "../../src/file-write-tools.mjs";
 
 // Bound via lazyImport (see its doc for the fail-OPEN hazard of a bare static
 // npm import — here the load crash would fire inside pretooluse-sanitize.mjs's
@@ -68,25 +72,24 @@ const { payloadVerdict, stripInvisibleWithReport } =
     await lazyImport("agent-sanitizer/invisible")
   );
 
-// Content fields the model authors, per tool. Paths and confusables are the
-// confusable layer's domain; here we target the free-text fields that carry
-// model-authored prose / code / data out into persisted or displayed artifacts.
-// A "key[].sub" entry addresses `sub` on every element of the array at `key`
-// (MultiEdit batches its writes as edits[].new_string), so the nested authored
-// content is sanitized too — not just the top-level fields.
-//
-// Null-prototype: `tool` comes from the payload, and on a plain object literal
-// `FIELDS["constructor"]` answers a truthy inherited value that the field loop
-// below would then try to iterate.
-/** @type {Record<string, string[]>} */
+// Content fields the model authors, per tool: every file-write tool's
+// `authored` fields from the one table, plus Bash's command. Paths and
+// confusables are the confusable layer's domain; here we target the free-text
+// fields that carry model-authored prose / code / data out into persisted or
+// displayed artifacts. Null-prototype: `tool` comes from the payload, and on a
+// plain object `FIELDS["constructor"]` answers a truthy inherited value.
+/** @type {Readonly<Record<string, readonly string[]>>} */
 export const AUTHORED_FIELDS = Object.freeze(
-  Object.assign(Object.create(null), {
-    Write: ["content"],
-    Edit: ["new_string"],
-    MultiEdit: ["edits[].new_string"],
-    NotebookEdit: ["new_source"],
-    Bash: ["command"],
-  }),
+  Object.assign(
+    Object.create(null),
+    Object.fromEntries(
+      Object.entries(FILE_WRITE_TOOLS).map(([tool, { authored }]) => [
+        tool,
+        authored,
+      ]),
+    ),
+    { Bash: Object.freeze(["command"]) },
+  ),
 );
 
 // The other half of the partition: tools this layer has LOOKED AT and decided
@@ -131,7 +134,7 @@ export const EXEMPT_TOOL_PATTERNS = Object.freeze([
  * 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) {
   const fields = AUTHORED_FIELDS[tool];
@@ -279,12 +282,9 @@ export function sanitizeAuthoredContent(tool, toolInput) {
   // every own field (including a literal `__proto__`) as a plain own property.
   const updatedInput = Object.assign(Object.create(null), toolInput);
   for (const k of keys) {
-    // Named groups satisfy prefer-named-capture-group; reading the numeric
-    // indices keeps the values typed as string (match.groups is optional).
-    const nested = k.match(/^(?<arr>\w+)\[\]\.(?<sub>\w+)$/);
-    if (nested) {
-      const arrKey = nested[1];
-      const subKey = nested[2];
+    const spec = parseFieldSpec(k);
+    if ("arr" in spec) {
+      const { arr: arrKey, sub: subKey } = spec;
       const arr = toolInput[arrKey];
       if (!Array.isArray(arr)) continue;
       let nestedChanged = false;

package/claude-hooks/lib/env-config.mjs

@@ -9,7 +9,9 @@
  * set of credential-bearing variable names. A rendered second copy is what let
  * this matcher fall twelve segments behind the engine.
  *
- * The JSON configs are imported as modules, not read from disk at call time:
+ * The vocabulary comes from `credentialNames()`, the package's one loader of
+ * that file. The JSON configs below are imported as modules, not read from disk
+ * at call time:
  * esbuild inlines them into the plugin bundle (which ships with no config
  * directory beside it) and Node resolves them natively from the package when the
  * hooks run from source. Their VALIDATION stays lazy — a malformed credential
@@ -21,7 +23,6 @@
 // engine alias and an external consumer resolves the same specifier.
 import { credentialNameMatcher } from "agent-sanitizer/credential-names-matcher";
 
-import credentialNames from "../../python/agent_sanitizer/secrets/data/credential-names.json" with { type: "json" };
 import redactionFloor from "../../python/agent_sanitizer/secrets/data/redaction-floor.json" with { type: "json" };
 import inferenceKeys from "../config/inference-key-vars.json" with { type: "json" };
 import scrubbed from "../config/scrubbed-env-vars.json" with { type: "json" };
@@ -155,7 +156,6 @@ let _credentialRule;
 function credentialRule() {
   if (_credentialRule !== undefined) return _credentialRule;
   return (_credentialRule = credentialNameMatcher({
-    spec: credentialNames,
     scope: "trailing",
     declineNonSecret: true,
   }));

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

@@ -17,6 +17,7 @@ import { createHash } from "node:crypto";
 import { tmpdir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { pathToFileURL } from "node:url";
+import { errMessage } from "../../src/err-message.mjs";
 import { excludeProvisioning } from "./hook-timing.mjs";
 import { readKnob } from "./knobs.mjs";
 
@@ -637,18 +638,9 @@ export function scrubUntrustedText(raw, layer1, cap = UNTRUSTED_TEXT_CAP) {
     : cleaned;
 }
 
-/**
- * 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) {
-  if (!(err instanceof Error)) return String(err);
-  const cause = err.cause instanceof Error ? `: ${err.cause.message}` : "";
-  return err.message + cause;
-}
+// Published from this module as part of the hooks' I/O surface; defined once
+// beside the library that renders the same failures.
+export { errMessage };
 
 /**
  * errMessage() for an error whose message may embed attacker-chosen bytes: V8

package/claude-hooks/lib/placeholder-grammar.mjs

@@ -15,6 +15,7 @@ import {
   UNPARSEABLE_PLACEHOLDER,
 } from "../../src/layer2-placeholder.mjs";
 import { spanPath, revealDir } from "./reveal.mjs";
+import { isFileWriteTool } from "../../src/file-write-tools.mjs";
 
 // Re-exported under this module's published names: consumers of the hooks
 // surface import the Layer-2 grammar from here.
@@ -70,16 +71,6 @@ export function layer2KeysIn(value, depth = 0) {
   return [...keys];
 }
 
-// Tools whose inputs the rehydration layer itself resolves (or, for
-// MultiEdit/NotebookEdit, refuses with guidance). Both advisories stay silent
-// on these: their placeholder handling is a verdict, not a note.
-export const REHYDRATED_TOOLS = new Set([
-  "Edit",
-  "Write",
-  "MultiEdit",
-  "NotebookEdit",
-]);
-
 /**
  * Depth-capped walk: does any string in `value` carry secret-placeholder-shaped
  * text? The cap fails OPEN (deeper content is unseen) — every caller feeds a
@@ -197,7 +188,9 @@ function tokenList(found) {
  * @returns {string | null}
  */
 export function placeholderNotice(tool, toolInput) {
-  if (REHYDRATED_TOOLS.has(tool)) return null;
+  // The rehydration layer resolves (or refuses) a file-write tool's
+  // placeholders itself: there the handling is a verdict, not a note.
+  if (isFileWriteTool(tool)) return null;
   const { secret } = collectPlaceholders(toolInput);
   if (secret.length === 0) return null;
   return (
@@ -233,7 +226,9 @@ export function placeholderNotice(tool, toolInput) {
  * @returns {string | null}
  */
 export function layer2PlaceholderNotice(tool, toolInput) {
-  if (REHYDRATED_TOOLS.has(tool)) return null;
+  // The rehydration layer resolves (or refuses) a file-write tool's
+  // placeholders itself: there the handling is a verdict, not a note.
+  if (isFileWriteTool(tool)) return null;
   const { layer2 } = collectPlaceholders(toolInput);
   if (layer2.length === 0) return null;
   // Both routes can be named at once: an input can mix keyed placeholders

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

@@ -37,6 +37,7 @@ import {
 } from "./redactor-wire.mjs";
 import {
   currentUid,
+  errMessage,
   isPrivateDir,
   ownedByCurrentUser,
   privateDirAt,
@@ -200,9 +201,8 @@ function isRespawnable(err) {
  * @returns {Error}
  */
 function failClosed(cause) {
-  const detail = cause instanceof Error ? cause.message : String(cause);
   return new Error(
-    `secret redaction unavailable (${detail}); secret-shaped output could not be vetted`,
+    `secret redaction unavailable (${errMessage(cause)}); secret-shaped output could not be vetted`,
   );
 }
 

package/claude-hooks/lib/secret-annotate.mjs

@@ -94,7 +94,7 @@ const ENV_VALUE_REGEX_CACHE = new Map();
  */
 export function hasEnvBoundSecret(text, env = process.env) {
   const minLen = minEnvSecretLen();
-  return envBoundSecretVars().some((name) => {
+  return envBoundSecretVars(env).some((name) => {
     const value = env[name];
     // Code-point length to match envValueRegex's code-point split — an astral
     // char counts once, not as two UTF-16 units, so minLen means the same thing

package/claude-hooks/pretooluse-sanitize.mjs

@@ -49,6 +49,9 @@ import {
   defaultOpen,
 } from "./lib/hook-fault.mjs";
 import { runLayerPipeline } from "./lib/layer-pipeline.mjs";
+// Relative, like src/claude-context.mjs: the fault path reads this table and
+// must work when the agent-sanitizer package failed to load.
+import { isFileWriteTool } from "../src/file-write-tools.mjs";
 import { controlPlane, runJudgeCli } from "./lib/control-plane.mjs";
 import {
   invisibleCharAlert,
@@ -764,18 +767,6 @@ export function failClosedFields(parsedOk, err, opts = {}) {
 // DEFAULT_HINT) failed to load. Exported so test/claude-hooks-fail-open.test.mjs
 // can pin the two spellings together.
 export const REDACTION_HINT = "[REDACTED";
-// The file-editing tools whose input fields ARE the bytes persisted to disk.
-// 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 — grepping for it, discussing
-// it — for an ask to hold precision there. That is an accepted gap, named in
-// THREAT-MODEL.md's carve-out paragraph, not a completeness claim.
-export const WRITE_SHAPED_TOOLS = new Set([
-  "Write",
-  "Edit",
-  "MultiEdit",
-  "NotebookEdit",
-]);
 
 /**
  * True when a faulting PreToolUse call is the one case the OPEN posture must
@@ -786,8 +777,13 @@ export const WRITE_SHAPED_TOOLS = new Set([
  * 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}
  */
@@ -797,7 +793,7 @@ export function hintedWriteFault(input) {
       input
     );
   return (
-    WRITE_SHAPED_TOOLS.has(/** @type {string} */ (payload?.tool_name)) &&
+    isFileWriteTool(payload?.tool_name) &&
     containsPlaceholder(payload?.tool_input)
   );
 }

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

@@ -69,6 +69,7 @@ import {
   CLAUDE_CONTEXT_SUBDIRS,
   CLAUDE_INSTRUCTION_GLOBS,
   CLAUDE_LAUNCH_GLOBS,
+  classifyReadFailure,
   displayUntrusted,
   isInsideDir,
 } from "../src/claude-context.mjs";
@@ -219,12 +220,11 @@ function decodeRun(run) {
   return instrDecodeRun(run);
 }
 
-// Target discovery stays hook-local glue, NOT a copy of the SSOT's
-// containment-checked `findInstructionFiles`: the two have different contracts.
-// The SSOT finder drops every target it cannot resolve, which is right for a
-// pure scan API; this hook must instead bucket it (see classifyReadFailure).
-// The write-side symlink hazard the SSOT finder guards against is covered here
-// by cleanFile's own root containment and O_NOFOLLOW open.
+// Target discovery stays hook-local glue, NOT a call to the library's
+// `findInstructionFiles`: this hook walks the bounded LAUNCH scope, the library
+// the whole-tree one. Both bucket an unreadable target through
+// classifyReadFailure. The write-side symlink hazard is covered by cleanFile's
+// own root containment and O_NOFOLLOW open.
 
 /**
  * Every file Claude Code loads as model context AT LAUNCH: `dir`'s own
@@ -286,35 +286,6 @@ export {
 
 // Main (skip when imported for testing)
 
-/**
- * PROBLEM CLASS — how a failed instruction-file read is classified. Every
- * consumer reads this one bucketing; nothing re-derives it from an errno.
- *
- * The scan is the only thing between a poisoned `CLAUDE.md` and a session that
- * loads it as instructions, and its caller announces "clean" on the trace
- * channel, whose whole purpose is that a MISSING announcement is loud. So 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: reported to the operator and it arms the gate.
- *   - ABSENT — ENOENT. The path resolves to nothing, and Claude Code loads
- *     instruction files through the same open, so no bytes can reach the model.
- *     Announced on the trace channel only; naming a risk that does not exist
- *     teaches the operator to dismiss the gate.
- *   - THROWN — no errno at all, i.e. a bug (a TypeError from an unloaded
- *     binding). Nothing here can be trusted, so it goes to the caller's
- *     declared failure posture. Same errno-vs-bug split {@link
- *     autoCleanFindings} uses.
- * @param {unknown} err
- * @returns {"absent" | "skipped"}  never returns for a non-errno throw
- */
-function classifyReadFailure(err) {
-  const code = /** @type {NodeJS.ErrnoException} */ (err).code;
-  if (code === undefined) throw err;
-  return code === "ENOENT" ? "absent" : "skipped";
-}
-
 /**
  * Scan every instruction file under the project, bucketing each unreadable
  * target through {@link classifyReadFailure}. `scanned` is DERIVED from the two

package/package.json

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

package/src/claude-context.mjs

@@ -250,6 +250,28 @@ export function displayUntrusted(text) {
   );
 }
 
+/**
+ * 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) {
+  const code = /** @type {NodeJS.ErrnoException} */ (err).code;
+  if (code === undefined) throw err;
+  return code === "ENOENT" ? "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/src/credential-names.mjs

@@ -34,20 +34,15 @@
  * — the same file the Python renderings read and the same file the
  * `agent-sanitizer/credential-names` subpath exports, so the ecosystems cannot
  * drift apart on the words either.
+ *
+ * PROBLEM CLASS — the vocabulary loaded by more than one reader. This module is
+ * the ONE JavaScript loader: a static JSON import, which a bundler inlines into
+ * every bundle that reaches it (the plugin ships no `python/` directory, so a
+ * module-relative file read there finds nothing). Every consumer — the secret
+ * pre-gate, the hooks' env-var matcher — calls {@link credentialNames} instead
+ * of importing the file again.
  */
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const DATA_FILE = join(
-  dirname(fileURLToPath(import.meta.url)),
-  "..",
-  "python",
-  "agent_sanitizer",
-  "secrets",
-  "data",
-  "credential-names.json",
-);
+import packagedSpec from "../python/agent_sanitizer/secrets/data/credential-names.json" with { type: "json" };
 
 const FILE_LABEL = "credential-names.json";
 const ENV_NAME_USE = "env-name";
@@ -158,15 +153,14 @@ export function parseCredentialNames(spec) {
 let _packaged;
 /** 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() {
-  return (_packaged ??= parseCredentialNames(
-    JSON.parse(readFileSync(DATA_FILE, "utf8")),
-  ));
+  return (_packaged ??= parseCredentialNames(packagedSpec));
 }
 
 /** @typedef {"trailing" | "any-segment"} CredentialNameScope */

package/src/err-message.mjs

@@ -0,0 +1,21 @@
+/**
+ * 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) {
+  if (!(err instanceof Error)) return String(err);
+  const cause = err.cause instanceof Error ? `: ${err.cause.message}` : "";
+  return err.message + cause;
+}