agent-sanitizer 2.50.0 → 2.51.0

package/README.md

@@ -289,6 +289,7 @@ singleton, and two copies in one bundle double-fire the inlined CLIs.
 | `claude-hooks/lib/reveal`               | The Layer-2 sidecar that lets the model re-read what the HTML splice removed               |
 | `claude-hooks/lib/secret-annotate`      | The cheap deterministic Layer-4 pre-gate checks around the daemon call                     |
 | `claude-hooks/lib/trace`                | The opt-in structured trace channel every layer announces itself on                        |
+| `claude-hooks/lib/hook-timing`          | The shared slow-hook budget, its measured windows and the notice they compose              |
 
 Only `plugin-hooks` itself is unexported under its own name — it is reachable as
 the bare `claude-hooks` entry above.

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

@@ -199,6 +199,7 @@ export async function runJudgeCli(
           tool,
           cpuMs: timer.cpuMs(),
           redactorMs: timer.redactorMs(),
+          hostMs: timer.hostMs(),
         }),
         event,
       ),
@@ -216,6 +217,7 @@ export async function runJudgeCli(
         tool,
         cpuMs: timer.cpuMs(),
         redactorMs: timer.redactorMs(),
+        hostMs: timer.hostMs(),
       });
     onError(err, input);
   }

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

@@ -9,15 +9,21 @@
  * before anyone traced it back here). A hook past the budget therefore says so
  * IN BAND, in the model's context, where it can be relayed to the operator.
  *
- * THREE numbers, because wall-clock alone cannot say whose cost it is: a hook on
+ * FOUR numbers, because wall-clock alone cannot say whose cost it is: a hook on
  * a contended host waits far longer than it computes (a 1.1 KB payload and a
  * 235 KB one both reported 7.2s on a loaded 2-vCPU box, against 0.3s of work).
- * So the notice prints, beside the clock, the CPU this process burned and the
- * time it spent inside redactor round trips — the daemon is a separate,
- * long-lived process whose CPU this one cannot see (see {@link processCpuMs}),
- * so the call that waits for it is the only measurable stand-in. The notice
- * GATES on none of them: a hook wedged on a dead redactor socket burns no CPU
- * and is exactly the sanitizer's fault.
+ * So the notice prints, beside the clock, the CPU this process burned, the time
+ * it spent inside redactor round trips, and the time it spent inside a HOST
+ * EXTENSION it called ({@link chargeHostExtension}) — the redactor daemon and a
+ * host callback's subprocess or socket peer are separate processes whose CPU this
+ * one cannot see (see {@link processCpuMs}), so the call that waits for each is
+ * the only measurable stand-in. The notice GATES on none of them: a hook wedged
+ * on a dead redactor socket burns no CPU and is exactly the sanitizer's fault.
+ *
+ * The host-extension window is what turned "blocked on something outside the
+ * sanitizer" — a verdict nobody can act on — into a named callee: a composer's
+ * best-effort audit POST to an unreachable sink charged every tool call its full
+ * 1.0s connect bound, and the notice could name none of it.
  *
  * ONE-TIME PROVISIONING is excluded (see {@link excludeProvisioning}): charging
  * an install to the hook that merely waited it out would make the FIRST call of
@@ -93,15 +99,16 @@ export function formatBytes(bytes) {
  * 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.
- * `cpuMs` is the run's own processor time and `redactorMs` the wall-clock it
- * spent inside redactor round trips (both from {@link startHookTimer}); absent
- * when the caller has no way to measure them, which is what the shell port of
- * this module reports.
+ * `cpuMs` is the run's own processor time, `redactorMs` the wall-clock it spent
+ * inside redactor round trips, and `hostMs` the wall-clock it spent inside host
+ * extensions (all from {@link startHookTimer}); absent when the caller has no way
+ * to measure them, which is what the shell port of this module reports.
  * @typedef {{
  *   payloadBytes?: number | null,
  *   tool?: string | null,
  *   cpuMs?: number | null,
  *   redactorMs?: number | null,
+ *   hostMs?: number | null,
  * }} SlowHookContext
  */
 
@@ -149,6 +156,20 @@ let provisioningCpuMs = 0;
 // measurement available.
 let redactorRoundTripMs = 0;
 
+// Process-wide total of wall-clock spent inside host extensions. Same reason as
+// the redactor total above: a callback's cost lands in a subprocess or a socket
+// peer, so this side's wait is the only measurement available. Its CPU is tracked
+// beside it because a callback that computes IN THIS PROCESS shows up in
+// processCpuMs too, and the notice must not charge one second of work to two
+// windows; startHookTimer subtracts this from the hook's own CPU figure.
+let hostExtensionMs = 0;
+let hostExtensionCpuMs = 0;
+// How many host-extension brackets are open. Only the OUTERMOST charges: the
+// package brackets `postText` and `audit` itself AND publishes the charger, so a
+// composer that charges its own work inside one of those callbacks would
+// otherwise add the same interval twice and report a 3s callback as 6s.
+let hostExtensionDepth = 0;
+
 /**
  * Run `work` — one redactor round trip — charging its duration to the redactor
  * share, so a run that spent its second inside a redaction call is told apart
@@ -173,6 +194,84 @@ export async function chargeRedactorRoundTrip(work, now = Date.now) {
   }
 }
 
+/**
+ * Run `work` — one call into a HOST EXTENSION (a composer's `postText`, `audit`
+ * or other injected callback) — charging its duration to the host share, so a run
+ * that spent its second inside a callback is told apart from one that spent it
+ * anywhere else. Charged in a `finally`, since a callback that THROWS is the one
+ * that spent the most.
+ *
+ * Like {@link chargeRedactorRoundTrip} this only attributes; the time stays in
+ * the hook's wall-clock, because the user waits for it either way. It says WHERE
+ * the time went and declines to say WHOSE: the wait holds the callback's own work
+ * AND whatever descheduling the host imposed on it.
+ *
+ * `work` may be synchronous — a callback that spawns a subprocess and blocks is
+ * charged in full, because the whole call runs inside this bracket.
+ *
+ * Reach this through `claude-hooks/sanitize-output`'s re-export whenever the hook
+ * is the bundled copy: importing this subpath separately yields a SECOND module
+ * instance whose total no timer reads, and the notice then reports a measured
+ * `0.0s` for a window that really burned seconds.
+ * @template T
+ * @param {() => Promise<T> | T} work
+ * @param {() => number} [now]  injectable clock, for tests
+ * @returns {Promise<T>}
+ */
+export async function chargeHostExtension(
+  work,
+  now = Date.now,
+  cpuNow = processCpuMs,
+) {
+  const outermost = hostExtensionDepth === 0;
+  const started = now();
+  const cpuStarted = cpuNow();
+  hostExtensionDepth += 1;
+  try {
+    return await work();
+  } finally {
+    hostExtensionDepth -= 1;
+    if (outermost) {
+      hostExtensionMs += Math.max(0, now() - started);
+      hostExtensionCpuMs += Math.max(0, cpuNow() - cpuStarted);
+    }
+  }
+}
+
+/**
+ * {@link chargeHostExtension} for a callback that must answer SYNCHRONOUSLY — the
+ * `redactNote` seam returns a string, so an async wrapper cannot stand in for it,
+ * and a composer that spawns a subprocess there would otherwise leave the wait in
+ * the unattributed remainder and its CPU charged to the sanitizer.
+ *
+ * Nesting and CPU are handled exactly as above, so the two chargers compose: a
+ * sync callback invoked inside an async bracket charges nothing twice.
+ * @template T
+ * @param {() => T} work
+ * @param {() => number} [now]  injectable clock, for tests
+ * @param {() => number} [cpuNow]  injectable CPU clock, for tests
+ * @returns {T}
+ */
+export function chargeHostExtensionSync(
+  work,
+  now = Date.now,
+  cpuNow = processCpuMs,
+) {
+  const outermost = hostExtensionDepth === 0;
+  const started = now();
+  const cpuStarted = cpuNow();
+  hostExtensionDepth += 1;
+  try {
+    return work();
+  } finally {
+    hostExtensionDepth -= 1;
+    if (outermost) {
+      hostExtensionMs += Math.max(0, now() - started);
+      hostExtensionCpuMs += Math.max(0, cpuNow() - cpuStarted);
+    }
+  }
+}
+
 /**
  * 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
@@ -212,10 +311,11 @@ export async function excludeProvisioning(
  * so far MINUS any provisioning charged in the meantime, and may be called more
  * than once.
  *
- * `wallMs` is what the user waited, `cpuMs` is what this process actually
- * computed, and `redactorMs` is what it spent inside redactor round trips
- * ({@link chargeRedactorRoundTrip}). All three are needed to say where a slow
- * run's time went — see the module header for the report that read a contended
+ * `wallMs` is what the user waited, `cpuMs` is what this process computed OUTSIDE
+ * a host callback, `redactorMs` is what it spent inside redactor round trips
+ * ({@link chargeRedactorRoundTrip}) and `hostMs` what it spent inside host
+ * extensions ({@link chargeHostExtension}). All four are needed to say where a
+ * slow run's time went — see the module header for the report that read a contended
  * host as a sanitizer bug.
  *
  * Every reader counts only what was charged since this timer started, so an
@@ -225,7 +325,7 @@ export async function excludeProvisioning(
  * the timer has measured, so the results are floored at 0.
  * @param {() => number} [now]  injectable clock, for tests
  * @param {() => number} [cpuNow]  injectable CPU clock, for tests
- * @returns {{ wallMs: () => number, cpuMs: () => number, redactorMs: () => number }}
+ * @returns {{ wallMs: () => number, cpuMs: () => number, redactorMs: () => number, hostMs: () => number }}
  */
 export function startHookTimer(now = Date.now, cpuNow = processCpuMs) {
   const started = now();
@@ -233,22 +333,33 @@ export function startHookTimer(now = Date.now, cpuNow = processCpuMs) {
   const provisionedBefore = provisioningMs;
   const provisionedCpuBefore = provisioningCpuMs;
   const redactorBefore = redactorRoundTripMs;
+  const hostBefore = hostExtensionMs;
+  const hostCpuBefore = hostExtensionCpuMs;
   return {
     wallMs: () =>
       Math.max(0, now() - started - (provisioningMs - provisionedBefore)),
+    // Host-extension CPU is subtracted alongside provisioning's, so this figure is
+    // the SANITIZER's own work: a callback that computes in this process would
+    // otherwise be charged to the hook and to the host window both, and the
+    // largest-share verdict would name the sanitizer for the composer's cost.
     cpuMs: () =>
       Math.max(
         0,
-        cpuNow() - cpuStarted - (provisioningCpuMs - provisionedCpuBefore),
+        cpuNow() -
+          cpuStarted -
+          (provisioningCpuMs - provisionedCpuBefore) -
+          (hostExtensionCpuMs - hostCpuBefore),
       ),
     redactorMs: () => Math.max(0, redactorRoundTripMs - redactorBefore),
+    hostMs: () => Math.max(0, hostExtensionMs - hostBefore),
   };
 }
 
 /**
  * The attribution sentence for a run whose CPU and redactor-round-trip shares
- * are both known: the two numbers, then which of the three WINDOWS the time went
- * into — this hook computing, the redactor call, or neither.
+ * are both known: the three numbers, then which of the four WINDOWS the time went
+ * into — this hook computing, the redactor call, a host extension, or none of
+ * them.
  *
  * A window, not a culprit. The round trip is wall-clock measured from this side,
  * so it holds the daemon's scan AND whatever descheduling the host imposed on
@@ -260,25 +371,46 @@ export function startHookTimer(now = Date.now, cpuNow = processCpuMs) {
  * say WHOSE, while the other two windows, which no host load can move time into,
  * are named outright.
  *
- * The CPU and redactor shares overlap by the framing this side does
- * mid-round-trip, so they do not sum to the elapsed time; a share that dominates
- * despite the overlap is still the one to act on.
+ * The host-extension window is named the same way and for the same reason: the
+ * callback is the composer's code, so a wait inside it is a cost the COMPOSER
+ * owns, and naming it is what lets a reader look at the right repository. A
+ * composer's audit POST to an absent sink is the case that motivated it.
+ *
+ * The CPU, redactor and host shares overlap by the framing this side does
+ * mid-round-trip and mid-callback, so they do not sum to the elapsed time; a
+ * share that dominates despite the overlap is still the one to act on.
  * @param {number} elapsedMs
  * @param {number} cpuMs
  * @param {number} redactorMs
+ * @param {number | undefined} hostMs  absent when the caller measures no host
+ *   callbacks; a caller that does pass 0 when none ran
  * @returns {string}
  */
-function attributeWait(elapsedMs, cpuMs, redactorMs) {
-  const otherMs = Math.max(0, elapsedMs - cpuMs - redactorMs);
+function attributeWait(elapsedMs, cpuMs, redactorMs, hostMs) {
+  // `hostMs` absent means the caller cannot measure that window, not that it was
+  // empty — a caller that CAN measure passes 0 and gets the zero printed. So an
+  // absent one is left out of both the sentence and the remainder, and the
+  // verdict's fourth arm names it as one of the unmeasured candidates.
+  const measuredHostMs = hostMs ?? 0;
+  const otherMs = Math.max(0, elapsedMs - cpuMs - redactorMs - measuredHostMs);
+  const largest = Math.max(cpuMs, redactorMs, measuredHostMs, otherMs);
   const verdict =
-    redactorMs >= cpuMs && redactorMs >= otherMs
+    redactorMs === largest
       ? "The largest share was spent inside the redactor round trip — the daemon's scan, the host it shares, or both; this hook was not computing it."
-      : cpuMs >= otherMs
-        ? "The largest share is this hook computing — a per-call cost the sanitizer owns, repeated by every affected call."
-        : "The largest share is neither the redactor nor this hook computing: it was blocked on a loaded machine or on something outside the sanitizer that it called.";
+      : hostMs !== undefined && hostMs === largest
+        ? "The largest share was spent inside a host extension this hook called — a callback the composer injected, and a cost that composer owns; neither the sanitizer nor the redactor was computing it."
+        : cpuMs === largest
+          ? "The largest share is this hook computing — a per-call cost the sanitizer owns, repeated by every affected call."
+          : hostMs === undefined
+            ? "The largest share is neither the redactor nor this hook computing: it was blocked on a loaded machine, on a host extension this caller does not measure, or on something else outside the sanitizer that it called."
+            : "The largest share is none of those three: it was blocked on a loaded machine or on something outside the sanitizer that it called without measuring.";
+  const hostClause =
+    hostMs === undefined
+      ? ""
+      : ` and ${formatSeconds(hostMs)}s was inside host extensions`;
   return (
-    `, of which ${formatSeconds(cpuMs)}s was this hook's own CPU and ` +
-    `${formatSeconds(redactorMs)}s was inside redactor round trips. ${verdict}`
+    `, of which ${formatSeconds(cpuMs)}s was this hook's own CPU${hostClause === "" ? " and" : ","} ` +
+    `${formatSeconds(redactorMs)}s was inside redactor round trips${hostClause}. ${verdict}`
   );
 }
 
@@ -290,7 +422,9 @@ function attributeWait(elapsedMs, cpuMs, redactorMs) {
  *
  * With `context.cpuMs` in hand the line says which share of the wait was the
  * sanitizer computing, and with `context.redactorMs` too it names the window the
- * time went into ({@link attributeWait}). Without them the line says that it cannot
+ * time went into ({@link attributeWait}), including `context.hostMs`'s host
+ * extensions — a caller that measured the first two but has no extensions to
+ * charge reports that window as zero, which is a measurement and not a shrug. Without them the line says that it cannot
  * tell, rather than asserting an attribution nothing measured: a wall-clock
  * overrun on a loaded host is the common case, and blaming it on the sanitizer
  * sends the operator hunting a per-call cost that does not exist.
@@ -318,14 +452,21 @@ export function slowHookNotice(
   const redactorMs = context?.redactorMs;
   const attributed =
     typeof cpuMs === "number" && typeof redactorMs === "number";
+  // Left UNDEFINED when the caller passed none: a zero would claim a measurement
+  // nobody made. Every caller in this package charges the seams and passes the
+  // number, including when it is 0.
+  const hostMs =
+    typeof context?.hostMs === "number" ? context.hostMs : undefined;
   const attribution = attributed
-    ? attributeWait(elapsedMs, cpuMs, redactorMs)
+    ? attributeWait(elapsedMs, cpuMs, redactorMs, hostMs)
     : typeof cpuMs === "number"
       ? `, and used ${formatSeconds(cpuMs)}s of CPU. ` +
         "Only the CPU share is work every affected call repeats; the rest was spent waiting, on a busy machine or on something this hook called."
       : ". Wall-clock alone cannot separate the sanitizer's own work from a busy machine.";
   const timings = attributed
-    ? "all three timings"
+    ? hostMs === undefined
+      ? "all three timings"
+      : "all four timings"
     : typeof cpuMs === "number"
       ? "both timings"
       : "timing";

package/claude-hooks/sanitize-output.mjs

@@ -25,6 +25,15 @@
  * isUntrustedIngress).
  */
 import { redactViaDaemon, positiveMsOr } from "./lib/redactor-client.mjs";
+import {
+  chargeHostExtension,
+  chargeHostExtensionSync,
+} from "./lib/hook-timing.mjs";
+// Re-exported for a composer whose own awaited work runs INSIDE this hook's
+// judge (an audit POST, a policy call): charging it needs the same module
+// instance the timer reads, and a bundled composer that imports the package
+// subpath separately gets a second instance whose totals no timer sees.
+export { chargeHostExtension, chargeHostExtensionSync };
 import {
   isMain,
   lazyImport,
@@ -284,8 +293,13 @@ export async function sanitizeText(
           if (!secrets) return null;
           // The note is derived from the PRE-redaction text: the caller's reason for
           // annotating (which variable, which provenance) is exactly what redaction
-          // is about to remove.
-          const note = ext.redactNote?.(content);
+          // is about to remove. Charged like the other seams — this one must answer
+          // synchronously, so a composer that blocks here (a `spawnSync` lookup)
+          // would otherwise leave its wait unattributed and its CPU on the hook.
+          const redactNote = ext.redactNote;
+          const note = redactNote
+            ? chargeHostExtensionSync(() => redactNote(content))
+            : undefined;
           return note
             ? { text: secrets.text, found: secrets.found, note }
             : { text: secrets.text, found: secrets.found };
@@ -298,16 +312,18 @@ export async function sanitizeText(
   // The one place the seam's shape is normalized, so nothing downstream has to
   // branch on an absent `notes` and the banner composer sees one shape.
   const result = { ...seamResult, notes: seamResult.notes ?? [] };
-  return ext.postText
-    ? applyPostText(
-        result,
-        await ext.postText(result.cleaned, {
-          toolName,
-          webIngress,
-          deadline,
-        }),
-      )
-    : result;
+  // Charged to the host-extension window: the callback is the composer's code and
+  // may block on a subprocess or a socket, neither of which this process's CPU
+  // figure can see, so an uncharged wait would land in the slow-hook notice's
+  // unattributed remainder and name nobody.
+  const postText = ext.postText;
+  if (!postText) return result;
+  return applyPostText(
+    result,
+    await chargeHostExtension(() =>
+      postText(result.cleaned, { toolName, webIngress, deadline }),
+    ),
+  );
 }
 
 /**
@@ -837,8 +853,17 @@ registerFaultPolicy(HOOK_NAME, {
  */
 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).
-  const emitTrace = bestEffortTrace(ext.trace ?? trace);
+  // 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,
+  );
   /**
    * @param {string} outcome  noop | clean | flagged | modified
    * @param {{ mutated_output?: unknown, additional_context?: string } | null} fields
@@ -1044,16 +1069,22 @@ export async function judgeSanitizeOutput(event, ext = {}) {
   // with silent holes is worse than a suppressed tool output.
   if (ext.audit && event.response !== null && event.response !== undefined) {
     const modified = fields !== null && Object.hasOwn(fields, "mutated_output");
-    await ext.audit({
-      tool: event.tool,
-      // The session identity travels in `meta`, not alongside the tool fields, so
-      // a recorder filing one trail per session cannot reach it unless it is
-      // lifted here.
-      session_id: event.meta?.session_id,
-      modified,
-      output: modified ? fields?.mutated_output : event.response,
-      context: fields?.additional_context,
-    });
+    // Charged to the host-extension window for the same reason as `postText`
+    // above: a recorder that POSTs to an absent sink waits out its own connect
+    // bound, and the notice must be able to name that window.
+    const audit = ext.audit;
+    await chargeHostExtension(() =>
+      audit({
+        tool: event.tool,
+        // The session identity travels in `meta`, not alongside the tool fields,
+        // so a recorder filing one trail per session cannot reach it unless it is
+        // lifted here.
+        session_id: event.meta?.session_id,
+        modified,
+        output: modified ? fields?.mutated_output : event.response,
+        context: fields?.additional_context,
+      }),
+    );
   }
   /** @type {import("agent-control-plane-core").Verdict} */
   const verdict = { decision: Decision.ALLOW };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.50.0",
+  "version": "2.51.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": {
@@ -196,6 +196,10 @@
     "./claude-hooks/lib/trace": {
       "types": "./types/claude-hooks/lib/trace.d.mts",
       "default": "./claude-hooks/lib/trace.mjs"
+    },
+    "./claude-hooks/lib/hook-timing": {
+      "types": "./types/claude-hooks/lib/hook-timing.d.mts",
+      "default": "./claude-hooks/lib/hook-timing.mjs"
     }
   },
   "files": [

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

@@ -37,6 +37,46 @@ export function formatBytes(bytes: number): string;
  * @returns {Promise<T>}
  */
 export function chargeRedactorRoundTrip<T>(work: () => Promise<T>, now?: () => number): Promise<T>;
+/**
+ * Run `work` — one call into a HOST EXTENSION (a composer's `postText`, `audit`
+ * or other injected callback) — charging its duration to the host share, so a run
+ * that spent its second inside a callback is told apart from one that spent it
+ * anywhere else. Charged in a `finally`, since a callback that THROWS is the one
+ * that spent the most.
+ *
+ * Like {@link chargeRedactorRoundTrip} this only attributes; the time stays in
+ * the hook's wall-clock, because the user waits for it either way. It says WHERE
+ * the time went and declines to say WHOSE: the wait holds the callback's own work
+ * AND whatever descheduling the host imposed on it.
+ *
+ * `work` may be synchronous — a callback that spawns a subprocess and blocks is
+ * charged in full, because the whole call runs inside this bracket.
+ *
+ * Reach this through `claude-hooks/sanitize-output`'s re-export whenever the hook
+ * is the bundled copy: importing this subpath separately yields a SECOND module
+ * instance whose total no timer reads, and the notice then reports a measured
+ * `0.0s` for a window that really burned seconds.
+ * @template T
+ * @param {() => Promise<T> | T} work
+ * @param {() => number} [now]  injectable clock, for tests
+ * @returns {Promise<T>}
+ */
+export function chargeHostExtension<T>(work: () => Promise<T> | T, now?: () => number, cpuNow?: typeof processCpuMs): Promise<T>;
+/**
+ * {@link chargeHostExtension} for a callback that must answer SYNCHRONOUSLY — the
+ * `redactNote` seam returns a string, so an async wrapper cannot stand in for it,
+ * and a composer that spawns a subprocess there would otherwise leave the wait in
+ * the unattributed remainder and its CPU charged to the sanitizer.
+ *
+ * Nesting and CPU are handled exactly as above, so the two chargers compose: a
+ * sync callback invoked inside an async bracket charges nothing twice.
+ * @template T
+ * @param {() => T} work
+ * @param {() => number} [now]  injectable clock, for tests
+ * @param {() => number} [cpuNow]  injectable CPU clock, for tests
+ * @returns {T}
+ */
+export function chargeHostExtensionSync<T>(work: () => T, now?: () => number, cpuNow?: () => number): T;
 /**
  * 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
@@ -62,10 +102,11 @@ export function excludeProvisioning<T>(work: () => Promise<T>, now?: () => numbe
  * so far MINUS any provisioning charged in the meantime, and may be called more
  * than once.
  *
- * `wallMs` is what the user waited, `cpuMs` is what this process actually
- * computed, and `redactorMs` is what it spent inside redactor round trips
- * ({@link chargeRedactorRoundTrip}). All three are needed to say where a slow
- * run's time went — see the module header for the report that read a contended
+ * `wallMs` is what the user waited, `cpuMs` is what this process computed OUTSIDE
+ * a host callback, `redactorMs` is what it spent inside redactor round trips
+ * ({@link chargeRedactorRoundTrip}) and `hostMs` what it spent inside host
+ * extensions ({@link chargeHostExtension}). All four are needed to say where a
+ * slow run's time went — see the module header for the report that read a contended
  * host as a sanitizer bug.
  *
  * Every reader counts only what was charged since this timer started, so an
@@ -75,12 +116,13 @@ export function excludeProvisioning<T>(work: () => Promise<T>, now?: () => numbe
  * the timer has measured, so the results are floored at 0.
  * @param {() => number} [now]  injectable clock, for tests
  * @param {() => number} [cpuNow]  injectable CPU clock, for tests
- * @returns {{ wallMs: () => number, cpuMs: () => number, redactorMs: () => number }}
+ * @returns {{ wallMs: () => number, cpuMs: () => number, redactorMs: () => number, hostMs: () => number }}
  */
 export function startHookTimer(now?: () => number, cpuNow?: () => number): {
     wallMs: () => number;
     cpuMs: () => number;
     redactorMs: () => number;
+    hostMs: () => number;
 };
 /**
  * The model-facing line for a hook that overran the budget, or null when it did
@@ -90,7 +132,9 @@ export function startHookTimer(now?: () => number, cpuNow?: () => number): {
  *
  * With `context.cpuMs` in hand the line says which share of the wait was the
  * sanitizer computing, and with `context.redactorMs` too it names the window the
- * time went into ({@link attributeWait}). Without them the line says that it cannot
+ * time went into ({@link attributeWait}), including `context.hostMs`'s host
+ * extensions — a caller that measured the first two but has no extensions to
+ * charge reports that window as zero, which is a measurement and not a shrug. Without them the line says that it cannot
  * tell, rather than asserting an attribution nothing measured: a wall-clock
  * overrun on a loaded host is the common case, and blaming it on the sanitizer
  * sends the operator hunting a per-call cost that does not exist.
@@ -195,15 +239,21 @@ export function reportSlowHook(hookName: string, elapsedMs: number, hookEventNam
  * before anyone traced it back here). A hook past the budget therefore says so
  * IN BAND, in the model's context, where it can be relayed to the operator.
  *
- * THREE numbers, because wall-clock alone cannot say whose cost it is: a hook on
+ * FOUR numbers, because wall-clock alone cannot say whose cost it is: a hook on
  * a contended host waits far longer than it computes (a 1.1 KB payload and a
  * 235 KB one both reported 7.2s on a loaded 2-vCPU box, against 0.3s of work).
- * So the notice prints, beside the clock, the CPU this process burned and the
- * time it spent inside redactor round trips — the daemon is a separate,
- * long-lived process whose CPU this one cannot see (see {@link processCpuMs}),
- * so the call that waits for it is the only measurable stand-in. The notice
- * GATES on none of them: a hook wedged on a dead redactor socket burns no CPU
- * and is exactly the sanitizer's fault.
+ * So the notice prints, beside the clock, the CPU this process burned, the time
+ * it spent inside redactor round trips, and the time it spent inside a HOST
+ * EXTENSION it called ({@link chargeHostExtension}) — the redactor daemon and a
+ * host callback's subprocess or socket peer are separate processes whose CPU this
+ * one cannot see (see {@link processCpuMs}), so the call that waits for each is
+ * the only measurable stand-in. The notice GATES on none of them: a hook wedged
+ * on a dead redactor socket burns no CPU and is exactly the sanitizer's fault.
+ *
+ * The host-extension window is what turned "blocked on something outside the
+ * sanitizer" — a verdict nobody can act on — into a named callee: a composer's
+ * best-effort audit POST to an unreachable sink charged every tool call its full
+ * 1.0s connect bound, and the notice could name none of it.
  *
  * ONE-TIME PROVISIONING is excluded (see {@link excludeProvisioning}): charging
  * an install to the hook that merely waited it out would make the FIRST call of
@@ -241,14 +291,26 @@ export const SLOW_PROVISION_THRESHOLD_MS: 60000;
  * 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.
- * `cpuMs` is the run's own processor time and `redactorMs` the wall-clock it
- * spent inside redactor round trips (both from {@link startHookTimer}); absent
- * when the caller has no way to measure them, which is what the shell port of
- * this module reports.
+ * `cpuMs` is the run's own processor time, `redactorMs` the wall-clock it spent
+ * inside redactor round trips, and `hostMs` the wall-clock it spent inside host
+ * extensions (all from {@link startHookTimer}); absent when the caller has no way
+ * to measure them, which is what the shell port of this module reports.
  */
 export type SlowHookContext = {
     payloadBytes?: number | null;
     tool?: string | null;
     cpuMs?: number | null;
     redactorMs?: number | null;
+    hostMs?: number | null;
 };
+/**
+ * This process's own user+system processor time so far, in milliseconds.
+ *
+ * `process.cpuUsage()` is RUSAGE_SELF: it counts what this node process
+ * computed and excludes both idle waiting and any child process. That is
+ * exactly the split the notice needs — a hook blocked on a socket, a lock or a
+ * loaded scheduler adds wall-clock here and no CPU.
+ * @returns {number}
+ */
+declare function processCpuMs(): number;
+export {};

package/types/claude-hooks/sanitize-output.d.mts

@@ -351,3 +351,6 @@ export type SanitizeExtensions = {
      */
     remedy?: string | undefined;
 };
+import { chargeHostExtension } from "./lib/hook-timing.mjs";
+import { chargeHostExtensionSync } from "./lib/hook-timing.mjs";
+export { chargeHostExtension, chargeHostExtensionSync };