agent-sanitizer 2.57.0 → 2.57.2

package/README.md

@@ -357,8 +357,13 @@ the extension bag's `trace` on
 receives the same `TraceEvent` names the default emits, and it **replaces** the
 default rather than running alongside it — the package channel goes silent, so
 there is one announcement to detect, not two. It may throw freely: each hook
-binds the sink it is given through `bestEffortTrace`, so an announcement can
-never be the thing that breaks a hook.
+binds the sink it is given through `hookTrace`, so an announcement can never be
+the thing that breaks a hook.
+
+That same binding charges whatever a host sink spends — a write to an unanswered
+socket, a subprocess — to the slow-hook notice's host-extension window. A hook
+past its budget then names the sink, instead of leaving the wait in the
+unattributed remainder and the sink's in-process CPU billed to the sanitizer.
 
 **A host's own cold-start marker can replace the derived one.** The hooks wait
 out an in-flight dependency install by polling a marker file whose path they

package/THREAT-MODEL.md

@@ -495,7 +495,17 @@ 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, so an ordinary object that merely carries a `type` field
+keeps the leaf-wise walk; only the enum-valued tag is preserved, never a string
+from the block itself. 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/claude-hooks/lib/trace.mjs

@@ -19,6 +19,7 @@
  */
 
 import { appendFileSync } from "node:fs";
+import { chargeHostExtensionSync } from "./hook-timing.mjs";
 
 /**
  * The sink shape a hook emits through: the event name, its metadata fields, and
@@ -26,7 +27,7 @@ import { appendFileSync } from "node:fs";
  * default emits, so it can remap them onto its own channel's vocabulary.
  *
  * A sink is NOT required to be total — throw freely. Every hook binds the one it
- * was given through {@link bestEffortTrace}, which is what upholds the channel's
+ * was given through {@link hookTrace}, which is what upholds the channel's
  * never-breaks-a-hook posture on host code that cannot promise it.
  * @typedef {(event: string, fields?: Record<string, unknown>, level?: "info"|"debug") => void} TraceFn
  */
@@ -105,3 +106,30 @@ export function bestEffortTrace(sink) {
     }
   };
 }
+
+/**
+ * The sink a hook emits through, given a host's or none: a HOST sink is made
+ * best-effort and charged to the slow-hook notice's host-extension window; the
+ * package's own {@link trace} is handed back untouched.
+ *
+ * A composer's sink may write over a socket or spawn a subprocess whose cost
+ * this process cannot see, so an uncharged one leaves its wait in the notice's
+ * unattributed remainder and its in-process CPU billed to the sanitizer. The
+ * default sink's file write IS the sanitizer's own work, so charging it would
+ * move a real per-call cost out of the figure that names it.
+ *
+ * Both properties are bound HERE, not at each hook, so a sixth caller can
+ * neither drop one nor nest them wrong — and the nesting is load-bearing twice
+ * over. The charge is booked in a `finally` inside the best-effort bracket, so
+ * a sink that spends its wait and THEN throws is measured before the throw is
+ * swallowed. And the exemption above reads the host's own sink, which a
+ * best-effort wrapper applied first would have replaced with a truthy one.
+ * @param {TraceFn} [sink]  a host's sink; absent asks for the package channel
+ * @returns {TraceFn}
+ */
+export function hookTrace(sink) {
+  if (!sink) return trace;
+  return bestEffortTrace((event, fields, level) =>
+    chargeHostExtensionSync(() => sink(event, fields, level)),
+  );
+}

package/claude-hooks/pretooluse-sanitize.mjs

@@ -73,7 +73,7 @@ import {
   LAYER2_PLACEHOLDER_RE,
 } from "./lib/placeholder-grammar.mjs";
 import { readSpan, spanPath } from "./lib/reveal.mjs";
-import { bestEffortTrace, trace, TraceEvent } from "./lib/trace.mjs";
+import { hookTrace, TraceEvent } from "./lib/trace.mjs";
 
 const HOOK_NAME = "pretooluse-sanitize";
 
@@ -474,11 +474,11 @@ function toolTargetDir(tool, toolInput) {
 export async function buildPreToolUseResponse(
   input,
   rehydrate = defaultRehydrate,
-  sink = trace,
+  sink,
 ) {
-  // Every path into the announcement runs through here, so this is the one place
-  // a host sink has to be made best-effort (see bestEffortTrace).
-  const emitTrace = bestEffortTrace(sink);
+  // Every path into the announcement runs through here, so this is the one
+  // place a host sink has to be bound (see hookTrace).
+  const emitTrace = hookTrace(sink);
   const asks = [];
   const contexts = [];
 
@@ -618,7 +618,11 @@ function assembleResponse({
  * @returns {Promise<import("agent-control-plane-core").Verdict>}
  */
 export async function judgePreToolUseSanitize(event, rehydrate, opts = {}) {
-  const { gates = [], trace: emitTrace = trace } = opts;
+  // Forwarded UNRESOLVED: substituting the package sink for an absent one here
+  // would hand hookTrace a truthy sink, charging this package's own trace write
+  // to the host window — the misattribution the split exists to prevent. Only
+  // buildPreToolUseResponse's binding may pick the default.
+  const { gates = [], trace: sink } = opts;
   // MERGED over the defaults, never substituted for them. A host that overrides
   // one field would otherwise leave the rest undefined, and the miss lands in
   // the fail-closed path: failClosedFields runs inside runJudgeCli's catch, so a
@@ -653,7 +657,7 @@ export async function judgePreToolUseSanitize(event, rehydrate, opts = {}) {
     const denyReason = gate(input);
     if (denyReason) return { decision: Decision.DENY, reason: denyReason };
   }
-  const fields = await buildPreToolUseResponse(input, rehydrate, emitTrace);
+  const fields = await buildPreToolUseResponse(input, rehydrate, sink);
   if (fields === null) return { decision: Decision.ALLOW };
   /** @type {Record<string, unknown>} */
   const verdict = {
@@ -897,7 +901,8 @@ registerFaultPolicy(HOOK_NAME, {
  * @returns {Promise<void>}
  */
 export async function cliMain(opts = {}) {
-  const { gates = [], trace: emitTrace = trace } = opts;
+  // Unresolved, for the reason judgePreToolUseSanitize states.
+  const { gates = [], trace: sink } = opts;
   const messages = { ...PRE_TOOL_USE_MESSAGES, ...opts.messages };
   await runJudgeCli(
     HOOK_NAME,
@@ -905,7 +910,7 @@ export async function cliMain(opts = {}) {
       judgePreToolUseSanitize(event, undefined, {
         messages,
         gates,
-        trace: emitTrace,
+        trace: sink,
       }),
     {
       // The caller's posture, WITHOUT the package: pass through with a warning

package/claude-hooks/sanitize-output.mjs

@@ -47,7 +47,7 @@ import {
 } from "./lib/hook-io.mjs";
 import { registerFaultPolicy, hookFaultOutcome } from "./lib/hook-fault.mjs";
 import { controlPlane, runJudgeCli } from "./lib/control-plane.mjs";
-import { bestEffortTrace, trace, TraceEvent } from "./lib/trace.mjs";
+import { hookTrace, TraceEvent } from "./lib/trace.mjs";
 import { hasEnvBoundSecret } from "./lib/secret-annotate.mjs";
 import { digestFlaggingEnabled, secretsEnabled } from "./lib/env-config.mjs";
 import {
@@ -856,18 +856,9 @@ registerFaultPolicy(HOOK_NAME, {
  * @returns {Promise<{ mutated_output?: unknown, additional_context?: string } | null>}
  */
 export async function evaluateToolOutput(input, ext = {}) {
-  // Best-effort, like the default sink: a host callback that throws must not be
-  // the thing that suppresses a tool output (see bestEffortTrace). A COMPOSER's
-  // sink is charged to the host window — it may write over a socket this process
-  // cannot see the cost of — while the package's own sink is not, since that
-  // file write is the sanitizer's own work.
-  const hostTrace = ext.trace;
-  const emitTrace = bestEffortTrace(
-    hostTrace
-      ? (event, fields) =>
-          chargeHostExtensionSync(() => hostTrace(event, fields))
-      : trace,
-  );
+  // A host callback that throws must not be the thing that suppresses a tool
+  // output (see hookTrace).
+  const emitTrace = hookTrace(ext.trace);
   /**
    * @param {string} outcome  noop | clean | flagged | modified
    * @param {{ mutated_output?: unknown, additional_context?: string } | null} fields

package/claude-hooks/sanitize-user-prompt.mjs

@@ -32,7 +32,7 @@ import {
   writeFaultOutcome,
 } from "./lib/hook-fault.mjs";
 import { controlPlane, runJudgeCli } from "./lib/control-plane.mjs";
-import { bestEffortTrace, trace, TraceEvent } from "./lib/trace.mjs";
+import { hookTrace, TraceEvent } from "./lib/trace.mjs";
 // classifyPrompt (the user-prompt verdict) and stripAnsiFully (its ANSI stripper)
 // come from the agent-sanitizer package. They are bound by a *caught* dynamic
 // import, never a bare top-level `import … from "…"`: a static npm import
@@ -208,10 +208,10 @@ export async function main(read, write, opts = {}) {
   const {
     strip = stripAnsiFully,
     overrides = USER_PROMPT_MESSAGES,
-    trace: sink = trace,
+    trace: sink,
     env = process.env,
   } = opts;
-  const emitTrace = bestEffortTrace(sink);
+  const emitTrace = hookTrace(sink);
   // Merged, not substituted — see judgeSanitizeUserPrompt. onError below is the
   // call site where a missing field would throw out of the catch and fail OPEN.
   const messages = { ...USER_PROMPT_MESSAGES, ...overrides };

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

@@ -51,7 +51,7 @@ import {
 import { formatReport } from "./lib/invisible-report.mjs";
 import { sweepStaleReveals } from "./lib/reveal.mjs";
 import { sweepStaleConfirms } from "./lib/secret-drop-guard.mjs";
-import { bestEffortTrace, trace, TraceEvent } from "./lib/trace.mjs";
+import { hookTrace, TraceEvent } from "./lib/trace.mjs";
 import { reportSlowHook, startHookTimer } from "./lib/hook-timing.mjs";
 // Relative, not the `agent-sanitizer` specifier every other engine import uses:
 // this is the scan's SCOPE, which is hook policy, and package.json's exports map
@@ -412,7 +412,14 @@ export async function cliMain(opts = {}) {
       HookEvent.SESSION_START,
       emitHookResponse,
       undefined,
-      { cpuMs: timer.cpuMs() },
+      // All four windows, including the two this scan normally leaves empty: a
+      // measured 0 rules a window OUT, where an omitted one leaves the notice
+      // naming candidates it cannot separate.
+      {
+        cpuMs: timer.cpuMs(),
+        redactorMs: timer.redactorMs(),
+        hostMs: timer.hostMs(),
+      },
     );
   }
 }
@@ -428,11 +435,11 @@ export async function cliMain(opts = {}) {
  * }} opts  see {@link cliMain}
  * @returns {Promise<void>}
  */
-async function runScanCli({ trace: sink = trace, scan: runScan, sessionId }) {
+async function runScanCli({ trace: sink, scan: runScan, sessionId }) {
   // Bound best-effort: the announcements below run BEFORE the auto-clean and
   // the alert write, with no catch above them, so a throwing host sink would
-  // abort the scan silently (see bestEffortTrace).
-  const emitTrace = bestEffortTrace(sink);
+  // abort the scan silently (see hookTrace).
+  const emitTrace = hookTrace(sink);
   // Everything the PreToolUse gate must surface this session, written once at
   // the end: an incomplete scan and an uncleanable file are independent reasons
   // to arm the gate, and two separate writes would have the second clobber the

package/claude-hooks/scan-loaded-instructions.mjs

@@ -37,7 +37,7 @@ import {
   appendAlert,
   recordInstructionsLoaded,
 } from "./lib/invisible-alert.mjs";
-import { bestEffortTrace, trace, TraceEvent } from "./lib/trace.mjs";
+import { hookTrace, TraceEvent } from "./lib/trace.mjs";
 import { reportSlowHook, startHookTimer } from "./lib/hook-timing.mjs";
 import { formatReport } from "./lib/invisible-report.mjs";
 import {
@@ -256,9 +256,9 @@ export { HOOK_NAME };
  *   passes its sink (see lib/trace.mjs)
  * @returns {Promise<void>}
  */
-export async function cliMain({ trace: sink = trace } = {}) {
+export async function cliMain({ trace: sink } = {}) {
   const timer = startHookTimer();
-  const emitTrace = bestEffortTrace(sink);
+  const emitTrace = hookTrace(sink);
   /** @type {string | undefined} */
   let sessionId;
   try {
@@ -321,7 +321,14 @@ export async function cliMain({ trace: sink = trace } = {}) {
       HookEvent.INSTRUCTIONS_LOADED,
       emitHookResponse,
       undefined,
-      { cpuMs: timer.cpuMs() },
+      // All four windows, including the two this scan normally leaves empty: a
+      // measured 0 rules a window OUT, where an omitted one leaves the notice
+      // naming candidates it cannot separate.
+      {
+        cpuMs: timer.cpuMs(),
+        redactorMs: timer.redactorMs(),
+        hostMs: timer.hostMs(),
+      },
     );
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.57.0",
+  "version": "2.57.2",
   "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,7 +1094,9 @@ 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
@@ -1110,6 +1112,81 @@ export function suppressToolOutput(value, message) {
   return suppressAt(value, message, 0, new WeakSet(), depthMemo());
 }
 
+/**
+ * Own-key schema of every Anthropic content block the suppressor recognises,
+ * from the Messages API request 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`. An unrecognised object is
+ * walked as ordinary data, so a schema entry that is wrong or missing costs a
+ * false NEGATIVE (the leaf-wise walk) rather than collapsing a legitimate
+ * object that merely carries a `type` field.
+ * @type {Map<string, { required: string[], optional: string[] }>}
+ */
+const CONTENT_BLOCK_SCHEMAS = new Map([
+  ["text", { required: ["text"], optional: ["citations", "cache_control"] }],
+  ["image", { required: ["source"], optional: ["cache_control"] }],
+  [
+    "document",
+    {
+      required: ["source"],
+      optional: ["title", "context", "citations", "cache_control"],
+    },
+  ],
+  [
+    "search_result",
+    {
+      required: ["source", "title", "content"],
+      optional: ["citations", "cache_control"],
+    },
+  ],
+  ["thinking", { required: ["thinking", "signature"], optional: [] }],
+  ["redacted_thinking", { required: ["data"], optional: [] }],
+  [
+    "tool_use",
+    { required: ["id", "name", "input"], optional: ["cache_control"] },
+  ],
+  [
+    "server_tool_use",
+    { required: ["id", "name", "input"], optional: ["cache_control"] },
+  ],
+  [
+    "tool_result",
+    {
+      required: ["tool_use_id"],
+      optional: ["content", "is_error", "cache_control"],
+    },
+  ],
+  [
+    "web_search_tool_result",
+    { required: ["tool_use_id", "content"], optional: ["cache_control"] },
+  ],
+]);
+
+/**
+ * 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 match that shape exactly.
+ * @param {any} value
+ * @returns {boolean}
+ */
+function isContentBlock(value) {
+  if (Array.isArray(value)) return false;
+  const keys = Object.keys(value);
+  if (!keys.includes("type")) return false;
+  const schema = CONTENT_BLOCK_SCHEMAS.get(value.type);
+  if (schema === undefined) return false;
+  return (
+    schema.required.every((key) => keys.includes(key)) &&
+    keys.every(
+      (key) =>
+        key === "type" ||
+        schema.required.includes(key) ||
+        schema.optional.includes(key),
+    )
+  );
+}
+
 /**
  * Recursion core for {@link suppressToolOutput}; see {@link sanitizeValueAt} for
  * the depth/`seen` bookkeeping rationale.
@@ -1128,6 +1205,13 @@ 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;
+  // A content block's `type` tag tells the API how to parse the block, and the
+  // tagged unions under it (`citations[]`, `source`, `cache_control`) are
+  // validated the same way — so walking a block's keys yields one the API
+  // rejects with a 400, permanently: it stays in the transcript and replays on
+  // every later turn. Collapse to the one block shape `message` is legal in.
+  // Only the enum-valued tag survives, never a string from the block itself.
+  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/claude-hooks/lib/trace.d.mts

@@ -33,13 +33,34 @@ export function trace(event: string, fields?: Record<string, unknown>, level?: "
  * @returns {TraceFn}
  */
 export function bestEffortTrace(sink: TraceFn): TraceFn;
+/**
+ * The sink a hook emits through, given a host's or none: a HOST sink is made
+ * best-effort and charged to the slow-hook notice's host-extension window; the
+ * package's own {@link trace} is handed back untouched.
+ *
+ * A composer's sink may write over a socket or spawn a subprocess whose cost
+ * this process cannot see, so an uncharged one leaves its wait in the notice's
+ * unattributed remainder and its in-process CPU billed to the sanitizer. The
+ * default sink's file write IS the sanitizer's own work, so charging it would
+ * move a real per-call cost out of the figure that names it.
+ *
+ * Both properties are bound HERE, not at each hook, so a sixth caller can
+ * neither drop one nor nest them wrong — and the nesting is load-bearing twice
+ * over. The charge is booked in a `finally` inside the best-effort bracket, so
+ * a sink that spends its wait and THEN throws is measured before the throw is
+ * swallowed. And the exemption above reads the host's own sink, which a
+ * best-effort wrapper applied first would have replaced with a truthy one.
+ * @param {TraceFn} [sink]  a host's sink; absent asks for the package channel
+ * @returns {TraceFn}
+ */
+export function hookTrace(sink?: TraceFn): TraceFn;
 /**
  * The sink shape a hook emits through: the event name, its metadata fields, and
  * the level. A host implementation receives the same {@link TraceEvent} names the
  * default emits, so it can remap them onto its own channel's vocabulary.
  *
  * A sink is NOT required to be total — throw freely. Every hook binds the one it
- * was given through {@link bestEffortTrace}, which is what upholds the channel's
+ * was given through {@link hookTrace}, which is what upholds the channel's
  * never-breaks-a-hook posture on host code that cannot promise it.
  * @typedef {(event: string, fields?: Record<string, unknown>, level?: "info"|"debug") => void} TraceFn
  */
@@ -55,7 +76,7 @@ export const TraceEvent: Readonly<{
  * default emits, so it can remap them onto its own channel's vocabulary.
  *
  * A sink is NOT required to be total — throw freely. Every hook binds the one it
- * was given through {@link bestEffortTrace}, which is what upholds the channel's
+ * was given through {@link hookTrace}, which is what upholds the channel's
  * never-breaks-a-hook posture on host code that cannot promise it.
  */
 export type TraceFn = (event: string, fields?: Record<string, unknown>, level?: "info" | "debug") => void;

package/types/output.d.mts

@@ -175,7 +175,9 @@ 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