agent-sanitizer 2.56.1 → 2.57.1

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/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 = {
@@ -713,6 +717,11 @@ export function depLoadHint(
  * — redactor daemon down, package not loaded) is the sanitizer being UNAVAILABLE,
  * so it ASKS to keep a human in the loop rather than hard-block on infrastructure.
  *
+ * An UNATTENDED host has no human for that ask to reach, so the ask stops the
+ * call and buys no review. Such a host passes `unavailableDecision: DENY` and
+ * gets a hard refusal on the clean-parse arm too, with the same reason text.
+ * The default stays ASK, so a host that wires nothing keeps today's behavior.
+ *
  * Deliberately knob-blind: this is the fail-CLOSED posture itself, so it ignores
  * AGENT_SANITIZER_FAIL_OPEN — a host that wires it directly keeps strictness by
  * construction, with no env var to remember. A host that instead wants the
@@ -720,19 +729,27 @@ export function depLoadHint(
  * which delegates here when the posture is closed.
  * @param {boolean} parsedOk whether the input parsed before the failure
  * @param {unknown} err
- * @param {{ messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>, hint?: string }} [opts]
+ * @param {{
+ *   messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>,
+ *   hint?: string,
+ *   unavailableDecision?: (typeof PermissionDecision)[keyof typeof PermissionDecision],
+ * }} [opts]
  * @returns {Record<string, unknown>}
  */
 export function failClosedFields(parsedOk, err, opts = {}) {
-  const { hint = depLoadHint(err) } = opts;
+  const { hint = depLoadHint(err), unavailableDecision } = opts;
   // Merged, not substituted — see judgePreToolUseSanitize. This is the call site
   // where a missing field would throw out of the catch and fail OPEN.
   const messages = { ...PRE_TOOL_USE_MESSAGES, ...opts.messages };
   const cause = `${safeErrMessage(err)}${hint}`;
+  // An unknown or absent override falls back to ASK rather than being trusted:
+  // a typo must not silently widen this arm past the two closed verdicts.
+  const unavailable =
+    unavailableDecision === PermissionDecision.DENY
+      ? PermissionDecision.DENY
+      : PermissionDecision.ASK;
   return {
-    permissionDecision: parsedOk
-      ? PermissionDecision.ASK
-      : PermissionDecision.DENY,
+    permissionDecision: parsedOk ? unavailable : PermissionDecision.DENY,
     permissionDecisionReason: parsedOk
       ? messages.failed(cause)
       : messages.unparsable(cause),
@@ -884,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,
@@ -892,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.56.1",
+  "version": "2.57.1",
   "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/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/claude-hooks/pretooluse-sanitize.d.mts

@@ -109,6 +109,11 @@ export function depLoadHint(err: unknown, remedy?: string, failedPackages?: () =
  * — redactor daemon down, package not loaded) is the sanitizer being UNAVAILABLE,
  * so it ASKS to keep a human in the loop rather than hard-block on infrastructure.
  *
+ * An UNATTENDED host has no human for that ask to reach, so the ask stops the
+ * call and buys no review. Such a host passes `unavailableDecision: DENY` and
+ * gets a hard refusal on the clean-parse arm too, with the same reason text.
+ * The default stays ASK, so a host that wires nothing keeps today's behavior.
+ *
  * Deliberately knob-blind: this is the fail-CLOSED posture itself, so it ignores
  * AGENT_SANITIZER_FAIL_OPEN — a host that wires it directly keeps strictness by
  * construction, with no env var to remember. A host that instead wants the
@@ -116,12 +121,17 @@ export function depLoadHint(err: unknown, remedy?: string, failedPackages?: () =
  * which delegates here when the posture is closed.
  * @param {boolean} parsedOk whether the input parsed before the failure
  * @param {unknown} err
- * @param {{ messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>, hint?: string }} [opts]
+ * @param {{
+ *   messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>,
+ *   hint?: string,
+ *   unavailableDecision?: (typeof PermissionDecision)[keyof typeof PermissionDecision],
+ * }} [opts]
  * @returns {Record<string, unknown>}
  */
 export function failClosedFields(parsedOk: boolean, err: unknown, opts?: {
     messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>;
     hint?: string;
+    unavailableDecision?: (typeof PermissionDecision)[keyof typeof PermissionDecision];
 }): Record<string, unknown>;
 /**
  * True when a faulting PreToolUse call is the one case the OPEN posture must
@@ -225,4 +235,5 @@ export type HostGate = (input: {
     permission_mode?: string;
 }) => string | null | undefined;
 declare const rehydrateRedacted: typeof import("agent-sanitizer/rehydrate").rehydrateRedacted;
+import { PermissionDecision } from "./lib/hook-io.mjs";
 export {};