agent-sanitizer 2.37.4 → 2.38.0

package/claude-hooks/lib/control-plane.mjs

@@ -11,6 +11,7 @@ import {
   awaitLazyDependency,
   errMessage,
   hookgateMarkerPath,
+  lastStdinByteLength,
   lazyImport,
   markerIsTrusted,
   missingPackageError,
@@ -171,19 +172,34 @@ export async function runJudgeCli(
   // an invented number is worse than none.
   /** @type {(() => number) | null} */
   let elapsed = null;
+  /** @type {number | null} */
+  let payloadBytes = null;
+  /** @type {string | null} */
+  let tool = null;
   try {
     input = await readInput();
+    // Read right after the call that would have set it — an injected test
+    // seam bypasses readStdinJson entirely, so lastStdinByteLength() would
+    // otherwise report a STALE size left by a previous real call.
+    payloadBytes = readInput === readStdinJson ? lastStdinByteLength() : null;
     // Timed from HERE, not from process start: the wait for the harness to hand
     // over stdin is not this hook's cost, and blaming it for one would send
     // operators chasing a bug report that is not theirs to fix.
     elapsed = startHookTimer();
     const { claudeAdapter: adapter } = controlPlane();
     const event = adapter.parse(transformInput(input));
+    tool = event.tool ?? null;
     // Awaited into its own binding first: as an inline argument, `elapsed()`
     // would be evaluated BEFORE the judge it is supposed to be timing.
     const judged = await judge(event);
     const out = nativeStdout(
-      adapter.render(withSlowHookNotice(hookName, elapsed(), judged), event),
+      adapter.render(
+        withSlowHookNotice(hookName, elapsed(), judged, undefined, {
+          payloadBytes,
+          tool,
+        }),
+        event,
+      ),
     );
     if (out !== null) write(out);
   } catch (err) {
@@ -192,7 +208,11 @@ export async function runJudgeCli(
     // must act on first, and the timing is context for it. stderr only — the
     // model-facing channel here belongs to onError's fail-closed message, and a
     // performance aside must not dilute a "this output was never vetted".
-    if (elapsed !== null) writeSlowHookNotice(hookName, elapsed());
+    if (elapsed !== null)
+      writeSlowHookNotice(hookName, elapsed(), undefined, {
+        payloadBytes,
+        tool,
+      });
     onError(err, input);
   }
 }

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

@@ -365,12 +365,35 @@ async function readAllBounded(stream, maxBytes = MAX_STDIN_BYTES) {
   return Buffer.concat(chunks);
 }
 
+/**
+ * Byte length of the most recent {@link readStdinJson} read, or null before
+ * the first one. Recorded as a side channel rather than widened into
+ * `readStdinJson`'s return value, since that return shape is depended on by
+ * callers (plugin-hooks.mjs, sanitize-user-prompt.mjs,
+ * scan-loaded-instructions.mjs, control-plane.mjs) that only want the parsed
+ * payload.
+ * @type {number | null}
+ */
+let lastStdinBytes = null;
+
+/**
+ * The byte length recorded by the most recent {@link readStdinJson} call, or
+ * null if none has run yet (e.g. a test injected its own `readInput`). Read by
+ * `runJudgeCli` to fold the payload size into the slow-hook notice.
+ * @returns {number | null}
+ */
+export function lastStdinByteLength() {
+  return lastStdinBytes;
+}
+
 /**
  * @param {number} [maxBytes] cap before aborting (overridable for tests)
  * @returns {Promise<any>}
  */
 export async function readStdinJson(maxBytes = MAX_STDIN_BYTES) {
-  return JSON.parse((await readAllBounded(process.stdin, maxBytes)).toString());
+  const buf = await readAllBounded(process.stdin, maxBytes);
+  lastStdinBytes = buf.length;
+  return JSON.parse(buf.toString());
 }
 
 /**

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

@@ -69,6 +69,45 @@ export function formatSeconds(ms) {
   return (Math.round(ms / 100) / 10).toFixed(1);
 }
 
+/**
+ * Bytes as a human-scaled string (B / KB / MB, one decimal past B) for the
+ * slow-hook notice's payload clause. No shell-parity constraint applies here —
+ * unlike {@link formatSeconds}, the shell port never has a payload size to
+ * print (see plugin/scripts/lib/hook-timing.sh's header).
+ * @param {number} bytes
+ * @returns {string}
+ */
+export function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * Debugging context a caller may already have in hand when a hook overruns its
+ * budget, so the notice names WHAT was slow instead of just HOW slow — the gap
+ * that made this specific latency report take a manual multi-step
+ * investigation to characterize (which tool call, how large a payload) before
+ * anyone could act on it.
+ * @typedef {{ payloadBytes?: number | null, tool?: string | null }} SlowHookContext
+ */
+
+/**
+ * The parenthetical clause naming `context`'s known fields, or `""` when
+ * `context` is absent or carries neither — so a caller with no context to give
+ * gets the exact same notice text as before this existed.
+ * @param {SlowHookContext | undefined} [context]
+ * @returns {string}
+ */
+function formatContextSuffix(context) {
+  if (!context) return "";
+  const parts = [];
+  if (typeof context.payloadBytes === "number")
+    parts.push(`a ${formatBytes(context.payloadBytes)} payload`);
+  if (context.tool) parts.push(`tool ${context.tool}`);
+  return parts.length > 0 ? ` (${parts.join(", ")})` : "";
+}
+
 // Process-wide total of milliseconds spent in one-time provisioning. A running
 // total rather than a flag because a single hook run can pay more than one (a
 // dependency wait AND a cold daemon spawn), and they may not nest.
@@ -124,17 +163,21 @@ export function startHookTimer(now = Date.now) {
  * @param {string} hookName
  * @param {number} elapsedMs
  * @param {number} [thresholdMs]
+ * @param {SlowHookContext} [context]  known payload size / triggering tool, so
+ *   the notice is self-diagnosing rather than requiring the next reader to
+ *   reconstruct what was slow by hand
  * @returns {string | null}
  */
 export function slowHookNotice(
   hookName,
   elapsedMs,
   thresholdMs = SLOW_HOOK_THRESHOLD_MS,
+  context,
 ) {
   if (elapsedMs <= thresholdMs) return null;
   return (
     `agent-sanitizer PERFORMANCE: the ${hookName} hook took ` +
-    `${formatSeconds(elapsedMs)}s, over its ${formatSeconds(thresholdMs)}s budget — ` +
+    `${formatSeconds(elapsedMs)}s${formatContextSuffix(context)}, over its ${formatSeconds(thresholdMs)}s budget — ` +
     "this delay is the sanitizer's, not the model's, and every affected call pays it. " +
     `Tell the user, and suggest they report it at ${ISSUE_URL} with the hook name and timing.`
   );
@@ -191,14 +234,16 @@ export function slowProvisionNotice(
  * @param {string} hookName
  * @param {number} elapsedMs
  * @param {(chunk: string) => void} [writeErr]  injectable stderr sink, for tests
+ * @param {SlowHookContext} [context]  see {@link slowHookNotice}
  * @returns {string | null}
  */
 export function writeSlowHookNotice(
   hookName,
   elapsedMs,
   writeErr = (chunk) => process.stderr.write(chunk),
+  context,
 ) {
-  const notice = slowHookNotice(hookName, elapsedMs);
+  const notice = slowHookNotice(hookName, elapsedMs, undefined, context);
   if (notice === null) return null;
   writeErr(notice + "\n");
   return notice;
@@ -217,6 +262,7 @@ export function writeSlowHookNotice(
  * @param {number} elapsedMs
  * @param {V} verdict
  * @param {(chunk: string) => void} [writeErr]  injectable stderr sink, for tests
+ * @param {SlowHookContext} [context]  see {@link slowHookNotice}
  * @returns {V}
  */
 export function withSlowHookNotice(
@@ -224,8 +270,9 @@ export function withSlowHookNotice(
   elapsedMs,
   verdict,
   writeErr = (chunk) => process.stderr.write(chunk),
+  context,
 ) {
-  const notice = writeSlowHookNotice(hookName, elapsedMs, writeErr);
+  const notice = writeSlowHookNotice(hookName, elapsedMs, writeErr, context);
   if (notice === null) return verdict;
   return {
     ...verdict,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.37.4",
+  "version": "2.38.0",
   "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/types/claude-hooks/lib/hook-io.d.mts

@@ -123,6 +123,13 @@ export function disabledHooks(known: readonly string[], env?: NodeJS.ProcessEnv
  * @returns {string}
  */
 export function failOpenContext(hookName: string, guarded: string, err: unknown, failedPackages?: () => string[], packageMessage?: (pkg: string) => string): string;
+/**
+ * The byte length recorded by the most recent {@link readStdinJson} call, or
+ * null if none has run yet (e.g. a test injected its own `readInput`). Read by
+ * `runJudgeCli` to fold the payload size into the slow-hook notice.
+ * @returns {number | null}
+ */
+export function lastStdinByteLength(): number | null;
 /**
  * @param {number} [maxBytes] cap before aborting (overridable for tests)
  * @returns {Promise<any>}

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

@@ -12,6 +12,15 @@
  * @returns {string}
  */
 export function formatSeconds(ms: number): string;
+/**
+ * Bytes as a human-scaled string (B / KB / MB, one decimal past B) for the
+ * slow-hook notice's payload clause. No shell-parity constraint applies here —
+ * unlike {@link formatSeconds}, the shell port never has a payload size to
+ * print (see plugin/scripts/lib/hook-timing.sh's header).
+ * @param {number} bytes
+ * @returns {string}
+ */
+export function formatBytes(bytes: number): string;
 /**
  * Run `work`, charging its whole duration to provisioning so no timer running
  * across it counts that time. Charged in a `finally`, so a provisioning step
@@ -48,9 +57,12 @@ export function startHookTimer(now?: () => number): () => number;
  * @param {string} hookName
  * @param {number} elapsedMs
  * @param {number} [thresholdMs]
+ * @param {SlowHookContext} [context]  known payload size / triggering tool, so
+ *   the notice is self-diagnosing rather than requiring the next reader to
+ *   reconstruct what was slow by hand
  * @returns {string | null}
  */
-export function slowHookNotice(hookName: string, elapsedMs: number, thresholdMs?: number): string | null;
+export function slowHookNotice(hookName: string, elapsedMs: number, thresholdMs?: number, context?: SlowHookContext): string | null;
 /**
  * The line for a ONE-TIME provisioning step that overran
  * {@link SLOW_PROVISION_THRESHOLD_MS}, or null when it did not.
@@ -88,9 +100,10 @@ export function slowProvisionNotice(stepName: string, elapsedMs: number, thresho
  * @param {string} hookName
  * @param {number} elapsedMs
  * @param {(chunk: string) => void} [writeErr]  injectable stderr sink, for tests
+ * @param {SlowHookContext} [context]  see {@link slowHookNotice}
  * @returns {string | null}
  */
-export function writeSlowHookNotice(hookName: string, elapsedMs: number, writeErr?: (chunk: string) => void): string | null;
+export function writeSlowHookNotice(hookName: string, elapsedMs: number, writeErr?: (chunk: string) => void, context?: SlowHookContext): string | null;
 /**
  * `verdict` with the slow-hook notice folded into its `additional_context`, or
  * the verdict untouched when the run was within budget. Also writes the notice
@@ -104,11 +117,12 @@ export function writeSlowHookNotice(hookName: string, elapsedMs: number, writeEr
  * @param {number} elapsedMs
  * @param {V} verdict
  * @param {(chunk: string) => void} [writeErr]  injectable stderr sink, for tests
+ * @param {SlowHookContext} [context]  see {@link slowHookNotice}
  * @returns {V}
  */
 export function withSlowHookNotice<V extends {
     additional_context?: string;
-}>(hookName: string, elapsedMs: number, verdict: V, writeErr?: (chunk: string) => void): V;
+}>(hookName: string, elapsedMs: number, verdict: V, writeErr?: (chunk: string) => void, context?: SlowHookContext): V;
 /**
  * Report a slow run for a hook that answers with a bare `hookSpecificOutput`
  * envelope rather than a control-plane verdict — SessionStart, which has no
@@ -171,3 +185,14 @@ export const SLOW_HOOK_THRESHOLD_MS: 1000;
  * re-provisioning every session), which is worth saying out loud.
  */
 export const SLOW_PROVISION_THRESHOLD_MS: 60000;
+/**
+ * Debugging context a caller may already have in hand when a hook overruns its
+ * budget, so the notice names WHAT was slow instead of just HOW slow — the gap
+ * that made this specific latency report take a manual multi-step
+ * investigation to characterize (which tool call, how large a payload) before
+ * anyone could act on it.
+ */
+export type SlowHookContext = {
+    payloadBytes?: number | null;
+    tool?: string | null;
+};