agent-sanitizer 2.57.1 → 2.57.3

package/THREAT-MODEL.md

@@ -495,7 +495,26 @@ RECONSTITUTES during stripping is judged as the sequence it becomes.
 (a harness that gets a shape-mismatched value silently shows the raw output).
 Layer 4 (secret redaction) is an **injected** redactor and is the one
 fail-closed path: a redactor that throws makes the pipeline rethrow, so the
-caller suppresses the output rather than emit an unvetted value. In the Claude
+caller suppresses the output rather than emit an unvetted value. That
+suppression (`suppressToolOutput`) replaces string leaves in place so the
+placeholder still matches the tool's shape, with one exception it must make: an
+Anthropic **content block** is collapsed whole to `{ type: "text", text: … }`
+rather than walked, because rewriting the `type` tag (or a tagged union nested
+under it — `citations`, `source`, `cache_control`) produces a block the API
+rejects with a 400, and the invalid block then replays on every later turn, so
+no retry clears it. A block is recognised only when its own keys match that
+tag's schema exactly **and** each value has that field's shape, so an ordinary
+object that merely carries a `type` field — or an `{ type: "image", source:
+"https://…" }` record whose `source` is a URL rather than the block's object —
+keeps the leaf-wise walk; only the enum-valued tag is preserved, never a string
+from the block itself. Two residual cases are accepted rather than papered over.
+A tag that PAIRS a block with another block (`tool_use` ↔ `tool_result`, and
+their server-tool twins) is deliberately not recognised: collapsing one orphans
+its partner, which is the same permanent rejection, so those keep the walk and
+#398 stands for them. And the depth/cycle truncation still substitutes the bare
+sentinel string for whatever subtree it cuts, block position or not — the walk
+cannot tell a content position from an ordinary array from inside, and guessing
+would rewrite ordinary arrays of strings into blocks. In the Claude
 Code hooks the entire secret layer is **opt-in**: `secretsEnabled()`
 (`claude-hooks/lib/env-config.mjs`) reads `AGENT_SANITIZER_SECRETS_ENABLED=1`,
 and every secret-layer guarantee below — Layer-4 redaction, rehydration, the

package/package.json

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

package/src/output.mjs

@@ -1094,14 +1094,19 @@ export function composeContext(
 /**
  * Replace every string leaf of `value` with `message`, preserving shape so a
  * fail-closed placeholder matches the tool's output schema. Non-string leaves
- * pass through.
+ * pass through. An Anthropic content block is the one exception: it is
+ * collapsed whole to `{ type: "text", text: message }`, because rewriting its
+ * `type` tag produces a block the API rejects (see {@link isContentBlock}).
  *
  * Shares {@link sanitizeValue}'s depth/cycle guard for the same reason: this
  * runs on the fail-closed path (an already-suspect output), so a 200k-deep or
  * self-referential value must NOT blow the stack here — that would re-open the
  * very hole suppression exists to close. Past {@link MAX_DEPTH} or on a cycle it
  * substitutes `message` for the offending subtree (already the suppression
- * sentinel, so the placeholder is consistent with the rest of the output).
+ * sentinel, so the placeholder is consistent with the rest of the output). A
+ * recognised block collapses BEFORE either guard and recurses no further, so it
+ * is subject to neither; a truncated subtree that is not itself a block is
+ * still replaced by the bare string, block position or not.
  * @param {any} value
  * @param {string} message
  * @returns {any}
@@ -1110,6 +1115,139 @@ export function suppressToolOutput(value, message) {
   return suppressAt(value, message, 0, new WeakSet(), depthMemo());
 }
 
+/**
+ * @typedef {(v: any) => boolean} FieldShape  a content-block field's value test
+ * @typedef {{ required: Record<string, FieldShape>, optional: Record<string, FieldShape> }} BlockSchema
+ */
+
+/** @type {FieldShape} */
+const isString = (v) => typeof v === "string";
+/** @type {FieldShape} */
+const isRecord = (v) =>
+  v !== null && typeof v === "object" && !Array.isArray(v);
+/** @type {FieldShape} */
+const isNullableString = (v) => v === null || isString(v);
+/** @type {FieldShape} */
+const isNullableArray = (v) => v === null || Array.isArray(v);
+// The API marks every optional object-valued block field nullable, and an
+// explicit null must not push the block back onto the walk that invalidates it.
+/** @type {FieldShape} */
+const isNullableRecord = (v) => v === null || isRecord(v);
+/** @type {FieldShape} */
+const isArray = (v) => Array.isArray(v);
+
+/**
+ * Schema of every Anthropic content block the suppressor recognises, from the
+ * Messages API block shapes (https://docs.claude.com/en/api/messages). A block
+ * is recognised only when its own keys match its tag's schema exactly — every
+ * `required` key present, no key outside `required` ∪ `optional` ∪ `type` —
+ * AND every present key's VALUE satisfies its predicate. Gating on the value's
+ * shape and not the key name alone is what keeps an ordinary record like
+ * `{ type: "image", source: "https://…/x.png" }` out: a real image block's
+ * `source` is an object. An unrecognised object is walked as ordinary data.
+ *
+ * Both directions cost something, and they are not symmetric in the way the
+ * rest of this module's precision rule assumes. Too LOOSE mangles an object
+ * that was never a block. Too STRICT is fail-safe only for those same
+ * non-blocks: for a REAL block it sends the walk over the `type` tag, which is
+ * the permanently-rejected block this collapse exists to prevent. So a
+ * predicate must admit every value the API admits — hence the nullable
+ * variants below, since every optional object-valued field is `object | null`.
+ *
+ * A block whose tag PAIRS it with another block (`tool_use` ↔ `tool_result`,
+ * and their server-tool twins) is deliberately absent: collapsing one to a text
+ * block orphans its partner, which the API rejects exactly as permanently as
+ * the rewritten tag this collapse exists to prevent. They keep the walk.
+ *
+ * Held as an entry list rather than annotated on the `new Map(...)` below
+ * because only the element-wise annotation typechecks: annotating the map lets
+ * tsc union the entry literals first, and that union's `source?: undefined`
+ * members fail `BlockSchema`'s index signature.
+ * @type {[string, BlockSchema][]}
+ */
+const CONTENT_BLOCK_SCHEMA_ENTRIES = [
+  [
+    "text",
+    {
+      required: { text: isString },
+      // A response's text block carries `citations` as an array (or null); a
+      // request's carries none.
+      optional: { citations: isNullableArray, cache_control: isNullableRecord },
+    },
+  ],
+  [
+    "image",
+    {
+      required: { source: isRecord },
+      optional: { cache_control: isNullableRecord },
+    },
+  ],
+  [
+    "document",
+    {
+      required: { source: isRecord },
+      // A document's `citations` is the `{ enabled }` toggle, not a list.
+      optional: {
+        title: isNullableString,
+        context: isNullableString,
+        citations: isNullableRecord,
+        cache_control: isNullableRecord,
+      },
+    },
+  ],
+  [
+    "search_result",
+    {
+      required: { source: isString, title: isString, content: isArray },
+      optional: {
+        citations: isNullableRecord,
+        cache_control: isNullableRecord,
+      },
+    },
+  ],
+  [
+    "thinking",
+    { required: { thinking: isString, signature: isString }, optional: {} },
+  ],
+  ["redacted_thinking", { required: { data: isString }, optional: {} }],
+];
+
+/** Tag → schema, keyed for {@link isContentBlock}'s lookup. */
+const CONTENT_BLOCK_SCHEMAS = new Map(CONTENT_BLOCK_SCHEMA_ENTRIES);
+
+/**
+ * Whether `value` (already known to be a walkable container) is an Anthropic
+ * content block — an object whose `type` tag names a known block shape AND
+ * whose own keys and values match that shape exactly.
+ * @param {any} value
+ * @returns {boolean}
+ */
+function isContentBlock(value) {
+  // An array with own `type`/`text` properties still occupies an array
+  // position, where a block may not be substituted for the array itself.
+  if (Array.isArray(value)) return false;
+  const schema = CONTENT_BLOCK_SCHEMAS.get(value.type);
+  // The own-key check is what blocks a polluted `Object.prototype.type`: the
+  // `value.type` read above resolves through the prototype, so without it
+  // `{ text: "leak" }` would tag itself a text block and be collapsed, dropping
+  // a legitimate field on the fail-closed path.
+  if (schema === undefined || !Object.hasOwn(value, "type")) return false;
+  // Object.hasOwn, not a bare index: a bare lookup resolves inherited
+  // Object.prototype members ("toString", "constructor") to real functions,
+  // letting a key outside the schema pass as if it had a predicate.
+  const isValidField = (/** @type {string} */ key) => {
+    if (Object.hasOwn(schema.required, key))
+      return schema.required[key](value[key]);
+    if (Object.hasOwn(schema.optional, key))
+      return schema.optional[key](value[key]);
+    return false;
+  };
+  return (
+    Object.keys(schema.required).every((key) => Object.hasOwn(value, key)) &&
+    Object.keys(value).every((key) => key === "type" || isValidField(key))
+  );
+}
+
 /**
  * Recursion core for {@link suppressToolOutput}; see {@link sanitizeValueAt} for
  * the depth/`seen` bookkeeping rationale.
@@ -1128,6 +1266,10 @@ function suppressAt(value, message, depth, seen, memo) {
   // Same opaque-leaf rule as sanitizeValueAt: only arrays and plain objects are
   // walked; an exotic object would be corrupted to an empty clone.
   if (!isWalkableContainer(value)) return value;
+  // Walking a block's keys rewrites its `type` tag and the tagged unions under
+  // it, yielding a block the API rejects with a 400 that then replays on every
+  // later turn. Collapse to the one block shape `message` is legal in.
+  if (isContentBlock(value)) return { type: "text", text: message };
   const cached = memo.get(value, depth);
   if (cached !== undefined) return cached;
   // Placeholders are not cached at all: they are O(1) to recompute, and the

package/types/output.d.mts

@@ -175,14 +175,19 @@ export function composeContext(modified: boolean, warnings: string[], { injectio
 /**
  * Replace every string leaf of `value` with `message`, preserving shape so a
  * fail-closed placeholder matches the tool's output schema. Non-string leaves
- * pass through.
+ * pass through. An Anthropic content block is the one exception: it is
+ * collapsed whole to `{ type: "text", text: message }`, because rewriting its
+ * `type` tag produces a block the API rejects (see {@link isContentBlock}).
  *
  * Shares {@link sanitizeValue}'s depth/cycle guard for the same reason: this
  * runs on the fail-closed path (an already-suspect output), so a 200k-deep or
  * self-referential value must NOT blow the stack here — that would re-open the
  * very hole suppression exists to close. Past {@link MAX_DEPTH} or on a cycle it
  * substitutes `message` for the offending subtree (already the suppression
- * sentinel, so the placeholder is consistent with the rest of the output).
+ * sentinel, so the placeholder is consistent with the rest of the output). A
+ * recognised block collapses BEFORE either guard and recurses no further, so it
+ * is subject to neither; a truncated subtree that is not itself a block is
+ * still replaced by the bare string, block position or not.
  * @param {any} value
  * @param {string} message
  * @returns {any}
@@ -285,5 +290,13 @@ export type SanitizeTextOptions = {
 export type Deadline = {
     remainingMs: () => number;
 };
+/**
+ * a content-block field's value test
+ */
+export type FieldShape = (v: any) => boolean;
+export type BlockSchema = {
+    required: Record<string, FieldShape>;
+    optional: Record<string, FieldShape>;
+};
 import { needsMarkdownPipeline } from "./gates.mjs";
 export { describeExfil, describeRemoved, describeWarned } from "./warnings.mjs";