agent-sanitizer 2.66.6 → 2.67.0

package/types/file-write-tools.d.mts

@@ -0,0 +1,64 @@
+/**
+ * True when `tool` is one of {@link FILE_WRITE_TOOLS}.
+ * @param {unknown} tool
+ * @returns {boolean}
+ */
+export function isFileWriteTool(tool: unknown): boolean;
+/**
+ * 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: string): {
+    key: string;
+} | {
+    arr: string;
+    sub: string;
+};
+/**
+ * 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: string, input: any): unknown[] | null;
+/**
+ * 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: Readonly<Record<string, FileWriteTool>>;
+export type FileWriteTool = {
+    authored: readonly string[];
+    placeholders: readonly string[];
+    rehydrates: boolean;
+};

package/types/gates.d.mts

@@ -30,7 +30,7 @@ export function needsUrlScan(text: string): boolean;
  */
 export function isHtmlShaped(text: string): boolean;
 /**
- * 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).
@@ -38,20 +38,6 @@ export function isHtmlShaped(text: string): boolean;
  * @returns {boolean}
  */
 export function matchesSecretHint(text: string): boolean;
-/**
- * Cheap, dependency-free pre-gates shared by the HTML layer (Layers 2 & 3) and
- * re-exported from both the package root and the `./html` subpath.
- *
- * 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.
- *
- * 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.
- */
 /**
  * Matches every point where the HTML tokenizer leaves the data state: `<` then
  * an ASCII letter, `/`, `!` or `?`. No closing `>` on purpose: a comment holding

package/types/instructions.d.mts

@@ -55,14 +55,12 @@ export function walkContextGlobs(globs: string[], cwd: string, exclude?: (entry:
  * 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
@@ -78,21 +76,32 @@ export function findInstructionFiles(globs: string[], { cwd, exclude }?: {
     exclude?: (entry: string) => boolean;
 }): string[];
 /**
- * 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: string[], { cwd, exclude }?: {
     cwd?: string;
     exclude?: (entry: string) => boolean;
-}): Array<{
-    file: string;
-    findings: ReturnType<typeof scanText>;
-}>;
+}): {
+    findings: Array<{
+        file: string;
+        findings: ReturnType<typeof scanText>;
+    }>;
+    skipped: Array<{
+        file: string;
+        reason: string;
+    }>;
+};
 /**
  * Strip payload-capable invisible characters from `absPath` in place. Returns
  * `true` when the file's bytes actually changed (a payload {@link scanText}
@@ -151,4 +160,4 @@ export function cleanFile(absPath: string, { root, lstat }?: {
     lstat?: (path: string) => import("node:fs").Stats;
 }): boolean;
 export { contextScanExclude } from "./repo-scope.mjs";
-export { ancestorInstructionFiles, announcedByInstructionsLoaded, CLAUDE_CONTEXT_KINDS, CLAUDE_CONTEXT_SUBDIRS, CLAUDE_DIR_INSTRUCTION_FILES, CLAUDE_INSTRUCTION_GLOBS, CLAUDE_LAUNCH_GLOBS, CLAUDE_MEMORY_FILES, contextScopeContradiction, excludeFromContextScan, USER_GLOBAL_EVENT_NAMED_GLOBS } from "./claude-context.mjs";
+export { ancestorInstructionFiles, announcedByInstructionsLoaded, CLAUDE_CONTEXT_KINDS, CLAUDE_CONTEXT_SUBDIRS, CLAUDE_DIR_INSTRUCTION_FILES, CLAUDE_INSTRUCTION_GLOBS, CLAUDE_LAUNCH_GLOBS, CLAUDE_MEMORY_FILES, classifyReadFailure, contextScopeContradiction, excludeFromContextScan, USER_GLOBAL_EVENT_NAMED_GLOBS } from "./claude-context.mjs";

package/types/src/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/src/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;

package/types/src/file-write-tools.d.mts

@@ -0,0 +1,64 @@
+/**
+ * True when `tool` is one of {@link FILE_WRITE_TOOLS}.
+ * @param {unknown} tool
+ * @returns {boolean}
+ */
+export function isFileWriteTool(tool: unknown): boolean;
+/**
+ * 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: string): {
+    key: string;
+} | {
+    arr: string;
+    sub: string;
+};
+/**
+ * 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: string, input: any): unknown[] | null;
+/**
+ * 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: Readonly<Record<string, FileWriteTool>>;
+export type FileWriteTool = {
+    authored: readonly string[];
+    placeholders: readonly string[];
+    rehydrates: boolean;
+};

package/types/src/instructions.d.mts

@@ -55,14 +55,12 @@ export function walkContextGlobs(globs: string[], cwd: string, exclude?: (entry:
  * 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
@@ -78,21 +76,32 @@ export function findInstructionFiles(globs: string[], { cwd, exclude }?: {
     exclude?: (entry: string) => boolean;
 }): string[];
 /**
- * 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: string[], { cwd, exclude }?: {
     cwd?: string;
     exclude?: (entry: string) => boolean;
-}): Array<{
-    file: string;
-    findings: ReturnType<typeof scanText>;
-}>;
+}): {
+    findings: Array<{
+        file: string;
+        findings: ReturnType<typeof scanText>;
+    }>;
+    skipped: Array<{
+        file: string;
+        reason: string;
+    }>;
+};
 /**
  * Strip payload-capable invisible characters from `absPath` in place. Returns
  * `true` when the file's bytes actually changed (a payload {@link scanText}
@@ -151,4 +160,4 @@ export function cleanFile(absPath: string, { root, lstat }?: {
     lstat?: (path: string) => import("node:fs").Stats;
 }): boolean;
 export { contextScanExclude } from "./repo-scope.mjs";
-export { ancestorInstructionFiles, announcedByInstructionsLoaded, CLAUDE_CONTEXT_KINDS, CLAUDE_CONTEXT_SUBDIRS, CLAUDE_DIR_INSTRUCTION_FILES, CLAUDE_INSTRUCTION_GLOBS, CLAUDE_LAUNCH_GLOBS, CLAUDE_MEMORY_FILES, contextScopeContradiction, excludeFromContextScan, USER_GLOBAL_EVENT_NAMED_GLOBS } from "./claude-context.mjs";
+export { ancestorInstructionFiles, announcedByInstructionsLoaded, CLAUDE_CONTEXT_KINDS, CLAUDE_CONTEXT_SUBDIRS, CLAUDE_DIR_INSTRUCTION_FILES, CLAUDE_INSTRUCTION_GLOBS, CLAUDE_LAUNCH_GLOBS, CLAUDE_MEMORY_FILES, classifyReadFailure, contextScopeContradiction, excludeFromContextScan, USER_GLOBAL_EVENT_NAMED_GLOBS } from "./claude-context.mjs";