agent-sanitizer 2.31.2 → 2.31.4

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

@@ -21,6 +21,15 @@
  *      *literals* (`\033`, `\x1b`, `\e`) — a *raw* ESC byte in authored content
  *      is anomalous.
  *
+ * SCOPE IS DECLARED, NOT INFERRED. Which tools this layer touches is a
+ * partition — {@link AUTHORED_FIELDS} (covered, with the field list) and
+ * {@link EXEMPT_TOOLS}/{@link EXEMPT_TOOL_PATTERNS} (looked at, with the reason
+ * nothing is sanitized) — resolved through the single
+ * {@link authoredScopeDecision} helper. Notably `mcp__*` server tools are
+ * exempt, so a PR body written via `gh pr create` IS stripped while the same
+ * body sent through a GitHub MCP tool is NOT; that asymmetry is a stated
+ * position with a rationale, not an oversight.
+ *
  * Distinct from sanitize-output.mjs, which scrubs tool *responses* flowing
  * toward the model (data the model reads). This scrubs what the model emits
  * (data the model writes out). In pretooluse-sanitize.mjs it runs *after*
@@ -55,14 +64,76 @@ const { STRIP, LONG_RUN_RE, SCATTERED_THRESHOLD, stripInvisible } =
 // 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[]>} */
-const FIELDS = {
-  Write: ["content"],
-  Edit: ["new_string"],
-  MultiEdit: ["edits[].new_string"],
-  NotebookEdit: ["new_source"],
-  Bash: ["command"],
-};
+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"],
+  }),
+);
+
+// The other half of the partition: tools this layer has LOOKED AT and decided
+// carry no model-authored free text, each with the reason. Together with
+// AUTHORED_FIELDS this is a declared scope rather than a fallthrough — an
+// omission becomes a reviewable line instead of the absence of one, and
+// test/claude-hooks-authored-scope.test.mjs fails when a tool the package
+// elsewhere claims to know lands in neither side.
+/** @type {Record<string, string>} */
+export const EXEMPT_TOOLS = Object.freeze(
+  Object.assign(Object.create(null), {
+    Read: "inputs are a path plus offsets — nothing the model authored is persisted or displayed",
+    Grep: "inputs are a search pattern and a path; rewriting a pattern would change what the search matches",
+    Glob: "inputs are a glob pattern and a path; rewriting a pattern would change what it matches",
+    LS: "input is a path — the confusable layer's domain, not authored free text",
+  }),
+);
+
+// Prefix-shaped exemptions, for tool families no fixed list can enumerate.
+/** @type {ReadonlyArray<{ pattern: RegExp, reason: string }>} */
+export const EXEMPT_TOOL_PATTERNS = Object.freeze([
+  Object.freeze({
+    pattern: /^mcp__/u,
+    reason:
+      "MCP tool inputs follow a server-declared schema this package cannot see, " +
+      "so there is no field it can name as authored free text. A blanket walk over " +
+      "every string in the input would buy recall at a real precision cost — it " +
+      "would rewrite opaque IDs, base64 blobs and protocol fields the server parses " +
+      "— so the gap is DECLARED rather than closed. A deployment that wants a " +
+      "specific server's body field covered adds it to AUTHORED_FIELDS by its full " +
+      'tool name (e.g. mcp__github__create_issue: ["body"]).',
+  }),
+]);
+
+/**
+ * The single place an unlisted tool's fate is decided: covered by a field list,
+ * exempt with a stated reason, or undeclared — nobody has classified it.
+ *
+ * `undeclared` is NOT a runtime alarm. Every arm returns the same
+ * pass-through behaviour, because a stderr line on each of the many tools no
+ * one has had a reason to classify (Task, TodoWrite, WebFetch, …) is alert
+ * 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" }}
+ */
+export function authoredScopeDecision(tool) {
+  const fields = AUTHORED_FIELDS[tool];
+  if (fields) return { kind: "covered", fields };
+  const exempt = EXEMPT_TOOLS[tool];
+  if (exempt) return { kind: "exempt", reason: exempt };
+  const matched = EXEMPT_TOOL_PATTERNS.find((entry) =>
+    entry.pattern.test(tool),
+  );
+  if (matched) return { kind: "exempt", reason: matched.reason };
+  return { kind: "undeclared" };
+}
 
 // Payload-capable: a long contiguous run, or enough scattered invisibles to
 // carry a message. Mirrors sanitize-user-prompt so the model→world and
@@ -123,8 +194,10 @@ export function authoredContext(changed) {
  * @returns {{ updatedInput: any, changed: string[] } | null}
  */
 export function sanitizeAuthoredContent(tool, toolInput) {
-  const keys = FIELDS[tool];
-  if (!keys || toolInput === null || toolInput === undefined) return null;
+  const scope = authoredScopeDecision(tool);
+  if (scope.kind !== "covered" || toolInput === null || toolInput === undefined)
+    return null;
+  const keys = scope.fields;
 
   const changed = [];
   // Null-prototype copy: toolInput is untrusted parsed JSON where a `__proto__`

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

@@ -210,12 +210,20 @@ export const PermissionDecision = Object.freeze({
 export const FAIL_OPEN_ENV = "AGENT_SANITIZER_FAIL_OPEN";
 
 /**
- * Values that turn the default posture back to fail-closed. Matched exactly,
- * so the launcher's shell `case` can state the same two literals — a
- * case-insensitive match here would need `tr`, which the launcher cannot reach
- * (it runs its no-node arm on shell builtins alone) and the two would drift.
+ * Values that turn the default posture back to fail-closed. Matched exactly:
+ * a case-insensitive match would need `tr`, which the launcher cannot reach
+ * (it runs its no-node arm on shell builtins alone).
+ *
+ * THE SINGLE SOURCE OF TRUTH for the closed set. The shell shims cannot import
+ * it, so `plugin/scripts/lib/fail-open.sh` is GENERATED from it by
+ * `scripts/gen-fail-open-lib.mjs` and committed; the round trip is asserted in
+ * plugin/test/fail-open-parity.test.mjs. Everything else that spells the set
+ * out by hand is an implementation that must appear in the parity table in
+ * tests/test_safe_launch.py.
  */
-const FAIL_CLOSED_VALUES = new Set(["0", "false"]);
+export const FAIL_CLOSED_VALUES = Object.freeze(["0", "false"]);
+
+const FAIL_CLOSED_SET = new Set(FAIL_CLOSED_VALUES);
 
 /**
  * Whether hook failures pass the guarded action through. True unless the caller
@@ -231,7 +239,7 @@ const FAIL_CLOSED_VALUES = new Set(["0", "false"]);
  * @returns {boolean}
  */
 export function failOpenEnabled(env = process.env) {
-  return !FAIL_CLOSED_VALUES.has(env[FAIL_OPEN_ENV] ?? "");
+  return !FAIL_CLOSED_SET.has(env[FAIL_OPEN_ENV] ?? "");
 }
 
 /**

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

@@ -98,7 +98,7 @@ export function layer2KeysIn(value, depth = 0) {
 // 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.
-const REHYDRATED_TOOLS = new Set([
+export const REHYDRATED_TOOLS = new Set([
   "Edit",
   "Write",
   "MultiEdit",

package/claude-hooks/pretooluse-sanitize.mjs

@@ -686,7 +686,7 @@ export const REDACTION_HINT = "[REDACTED";
 // 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.
-const WRITE_SHAPED_TOOLS = new Set([
+export const WRITE_SHAPED_TOOLS = new Set([
   "Write",
   "Edit",
   "MultiEdit",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.31.2",
+  "version": "2.31.4",
   "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": {
@@ -216,6 +216,7 @@
     "typecheck": "tsc --noEmit && tsc -p tsconfig.hooks.json --noEmit",
     "build:types": "tsc -p tsconfig.build.json && tsc -p tsconfig.build-hooks.json",
     "gen:joining-type": "node scripts/gen-joining-type.mjs",
+    "gen:fail-open-lib": "node scripts/gen-fail-open-lib.mjs",
     "lint": "eslint .",
     "test:mutation": "node scripts/mutate.mjs",
     "format": "prettier --write .",

package/types/claude-hooks/lib/authored-content.d.mts

@@ -1,3 +1,24 @@
+/**
+ * The single place an unlisted tool's fate is decided: covered by a field list,
+ * exempt with a stated reason, or undeclared — nobody has classified it.
+ *
+ * `undeclared` is NOT a runtime alarm. Every arm returns the same
+ * pass-through behaviour, because a stderr line on each of the many tools no
+ * one has had a reason to classify (Task, TodoWrite, WebFetch, …) is alert
+ * 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" }}
+ */
+export function authoredScopeDecision(tool: string): {
+    kind: "covered";
+    fields: string[];
+} | {
+    kind: "exempt";
+    reason: string;
+} | {
+    kind: "undeclared";
+};
 /** @param {string[]} changed */
 export function authoredContext(changed: string[]): string;
 /**
@@ -13,3 +34,12 @@ export function sanitizeAuthoredContent(tool: string, toolInput: any): {
     updatedInput: any;
     changed: string[];
 } | null;
+/** @type {Record<string, string[]>} */
+export const AUTHORED_FIELDS: Record<string, string[]>;
+/** @type {Record<string, string>} */
+export const EXEMPT_TOOLS: Record<string, string>;
+/** @type {ReadonlyArray<{ pattern: RegExp, reason: string }>} */
+export const EXEMPT_TOOL_PATTERNS: ReadonlyArray<{
+    pattern: RegExp;
+    reason: string;
+}>;

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

@@ -430,6 +430,19 @@ export const PermissionDecision: Readonly<{
  * by construction, not by remembering to set an env var.
  */
 export const FAIL_OPEN_ENV: "AGENT_SANITIZER_FAIL_OPEN";
+/**
+ * Values that turn the default posture back to fail-closed. Matched exactly:
+ * a case-insensitive match would need `tr`, which the launcher cannot reach
+ * (it runs its no-node arm on shell builtins alone).
+ *
+ * THE SINGLE SOURCE OF TRUTH for the closed set. The shell shims cannot import
+ * it, so `plugin/scripts/lib/fail-open.sh` is GENERATED from it by
+ * `scripts/gen-fail-open-lib.mjs` and committed; the round trip is asserted in
+ * plugin/test/fail-open-parity.test.mjs. Everything else that spells the set
+ * out by hand is an implementation that must appear in the parity table in
+ * tests/test_safe_launch.py.
+ */
+export const FAIL_CLOSED_VALUES: readonly string[];
 /**
  * Hard cap on hook stdin. A well-formed Claude Code hook payload is at most a
  * few MB (tool input plus the harness-truncated tool output); 64 MiB leaves

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

@@ -117,6 +117,7 @@ export const LAYER2_PLACEHOLDER_RE: RegExp;
  * points at the sidecar instead of a span file.
  */
 export const UNPARSEABLE_MARKER: "[HTML unparseable \u2014 withheld]";
+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

@@ -210,6 +210,7 @@ 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