agent-sanitizer 2.31.1 → 2.31.3

package/bin/sanitize-cli.mjs

@@ -14,7 +14,7 @@
  * Protocol — a request is a JSON object with an `op` (default `"sanitize"` so a
  * bare `{ text, html }` keeps working). Per op:
  *
- *   sanitize           { text, html? }            -> { cleaned, found, warnings, notes }
+ *   sanitize           { text, html? }            -> { cleaned, found, warnings, notes, splices? }
  *   sanitizeText       { text, html?, exfilScan? } -> { cleaned, warnings, notes, modified, sgrNote }
  *   classifyPrompt     { text }                    -> { action, reason? }
  *   scanInstructionFiles { globs, cwd? }           -> { findings: [{ file, findings }] }
@@ -114,10 +114,14 @@ export const OPS = {
   /** @param {Record<string, unknown>} req */
   async sanitize(req) {
     const text = requireString(req, "text");
-    const { cleaned, found, warnings, notes } = await sanitize(text, {
-      html: Boolean(req.html),
-    });
-    return { cleaned, found, warnings, notes };
+    // Forwarded whole rather than re-listed field by field. A hand-picked
+    // projection is a second copy of the return shape that nothing keeps in
+    // sync: `splices` was part of `sanitize()`'s result and silently never
+    // reached the wire, so every non-JS caller was blind to Layer 2's spliced
+    // ranges. `test/cli-response-contract.test.mjs` pins this set against the
+    // Python client's field list, so growing the result stays a two-file edit
+    // that CI notices instead of a silent drop.
+    return await sanitize(text, { html: Boolean(req.html) });
   },
 
   /** @param {Record<string, unknown>} req */

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.1",
+  "version": "2.31.3",
   "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/src/html.mjs

@@ -882,6 +882,131 @@ function hasImageLayer(nodeOf) {
   return paintsImageLayer(nodeOf("background"));
 }
 
+// The declarations that add to an axis's BORDER box beyond its content-box
+// length, per axis. Shorthands are listed alongside the longhands they can set,
+// because a shorthand this checker cannot resolve must fail OPEN rather than be
+// ignored — ignoring it is what let `height:0; padding-bottom:56.25%` read as
+// invisible.
+// Logical spellings are listed beside their physical twins: `padding-block-end`
+// IS the aspect-ratio idiom in a logical stylesheet, so omitting it would leave
+// the exact false positive this checker exists to close.
+const BLOCK_AXIS_EXTENT_PROPS = [
+  "padding",
+  "padding-top",
+  "padding-bottom",
+  "padding-block",
+  "padding-block-start",
+  "padding-block-end",
+  "border",
+  "border-width",
+  "border-top",
+  "border-bottom",
+  "border-top-width",
+  "border-bottom-width",
+  "border-block",
+  "border-block-width",
+  "border-block-start",
+  "border-block-end",
+  "border-block-start-width",
+  "border-block-end-width",
+];
+const INLINE_AXIS_EXTENT_PROPS = [
+  "padding",
+  "padding-left",
+  "padding-right",
+  "padding-inline",
+  "padding-inline-start",
+  "padding-inline-end",
+  "border",
+  "border-width",
+  "border-left",
+  "border-right",
+  "border-left-width",
+  "border-right-width",
+  "border-inline",
+  "border-inline-width",
+  "border-inline-start",
+  "border-inline-end",
+  "border-inline-start-width",
+  "border-inline-end-width",
+];
+
+// The shorthands that can set a width alongside a style and a color. An omitted
+// width computes to `medium`, so these need an explicit numeric width before
+// the declaration can be called zero-extent.
+const BORDER_SHORTHANDS = new Set([
+  "border",
+  "border-top",
+  "border-bottom",
+  "border-left",
+  "border-right",
+  "border-block",
+  "border-inline",
+  "border-block-start",
+  "border-block-end",
+  "border-inline-start",
+  "border-inline-end",
+]);
+
+// `border-width`'s keyword values. They are LENGTHS, so a border shorthand that
+// names one (or names none at all, defaulting to `medium`) has real extent.
+const BORDER_WIDTH_KEYWORDS = new Set(["thin", "medium", "thick"]);
+
+/**
+ * True when a declared axis-additive property provably contributes NO extent.
+ *
+ * Deliberately conservative: every numeric token must be near zero, no
+ * border-width keyword may appear, and a `border*` shorthand must carry an
+ * explicit numeric width (an omitted width computes to `medium`, i.e. 3px). A
+ * `calc()`, a `var()`, or any unit this cannot resolve leaves a non-numeric
+ * token behind and returns false — the fail-open the module's own policy
+ * requires, since an unresolvable value may well paint a visible box.
+ * @param {string} prop @param {any} node @returns {boolean}
+ */
+function contributesNoExtent(prop, node) {
+  const tokens = valueTokens(node);
+  if (tokens.length === 0) return false;
+  const isBorderShorthand = BORDER_SHORTHANDS.has(prop);
+  let sawNumeric = false;
+  for (const token of tokens) {
+    if (
+      token.type === "Number" ||
+      token.type === "Dimension" ||
+      token.type === "Percentage"
+    ) {
+      if (Math.abs(parseFloat(token.value)) >= NEAR_ZERO_EPSILON) return false;
+      sawNumeric = true;
+      continue;
+    }
+    // A hex color is a `Hash` node, never a length — accepting it keeps
+    // `border:0 solid #ccc` resolvable without weakening the fail-open below.
+    if (token.type === "Hash") continue;
+    // A style/color identifier (`solid`, `red`) adds no length, but a
+    // width keyword does — and anything else (a function node, `var()`) is
+    // unresolvable and must fail open.
+    if (token.type !== "Identifier") return false;
+    if (BORDER_WIDTH_KEYWORDS.has(String(token.name).toLowerCase()))
+      return false;
+  }
+  return isBorderShorthand ? sawNumeric : true;
+}
+
+/**
+ * True when every declaration that could add to `axisProps`' axis is either
+ * absent or provably zero, so a near-zero content-box length really does mean
+ * the rendered border box is empty.
+ * @param {(key: string) => any} nodeOf @param {string[]} axisProps
+ * @returns {boolean}
+ */
+function axisExtentProvablyZero(nodeOf, axisProps) {
+  for (const prop of axisProps) {
+    const node = nodeOf(prop);
+    if (!node) continue; // undeclared: contributes its initial value, 0
+    if (!contributesNoExtent(prop, node)) return false;
+  }
+  return true;
+}
+
 /**
  * @param {(key: string) => any} nodeOf value node for a property, or null
  * @param {(key: string) => string} textOf decoded/lowercased text for a property
@@ -889,10 +1014,24 @@ function hasImageLayer(nodeOf) {
  */
 function isOverflowHidden(nodeOf, textOf) {
   if (textOf("overflow") !== "hidden") return false;
-  for (const dim of ["height", "width", "max-height", "max-width"])
+  for (const [dim, axisProps] of /** @type {[string, string[]][]} */ ([
+    ["height", BLOCK_AXIS_EXTENT_PROPS],
+    ["width", INLINE_AXIS_EXTENT_PROPS],
+    ["max-height", BLOCK_AXIS_EXTENT_PROPS],
+    ["max-width", INLINE_AXIS_EXTENT_PROPS],
+  ]))
     // Near-zero (epsilon band), not exact 0, so `height:0.0001px` still counts —
     // matching the standalone size checks a browser renders as invisible.
-    if (isNearZeroLength(nodeOf(dim))) return true;
+    // The content box being empty is necessary but NOT sufficient: the universal
+    // aspect-ratio wrapper (`height:0; padding-bottom:56.25%; overflow:hidden` —
+    // Bootstrap's `.ratio`, and every hand-pasted padding-bottom hack) renders
+    // at 56.25% of its container with everything inside it on screen. Reading
+    // the content-box length alone spliced that visible content out.
+    if (
+      isNearZeroLength(nodeOf(dim)) &&
+      axisExtentProvablyZero(nodeOf, axisProps)
+    )
+      return true;
   return false;
 }
 

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