agent-sanitizer 2.67.1 → 2.68.0

package/THREAT-MODEL.md

@@ -298,16 +298,17 @@ plugin injects the Python engine from `agent-sanitizer[secrets]`
 (`python/agent_sanitizer/secrets/engine.py`) over a local daemon;
 `plugin/scripts/provision-redactor.sh` installs it at SessionStart.
 
-**It is the one fail-closed layer.** A redactor that throws — unreachable
-daemon, engine error — is rethrown from `sanitizeValue` as `CRITICAL: secret
-redaction failed …` (`src/output.mjs`).
-With the layer opted in, the output hook's fault policy (`alwaysClosed` in
-`claude-hooks/sanitize-output.mjs`, resolved in `lib/hook-fault.mjs`) then
-suppresses the output under **either** `AGENT_SANITIZER_FAIL_OPEN` posture —
-and so does any other fault of that hook, since an output the hook failed on
-was never vetted for secrets either. One accepted gap: a launcher-level failure
-(no `node`, corrupt bundle) never runs the policy, so the launcher's own
-posture applies there, warning by default.
+**A redactor fault follows the operator's posture.** A redactor that throws —
+unreachable daemon, engine error, spent budget — is rethrown from
+`sanitizeValue` as `CRITICAL: secret redaction failed …` (`src/output.mjs`), so
+the seam never returns unvetted text as if it were vetted. The output hook then
+answers it like any other fault, under `AGENT_SANITIZER_FAIL_OPEN`
+(`lib/hook-fault.mjs`, the one posture resolver, which has no per-hook override):
+open by default — the output reaches the model with an UNSANITIZED warning, and
+the operator's terminal names the redactor failure — and withheld under `=0`.
+Accepted risk of the default: while the redactor is down, a credential in tool
+output reaches the model unredacted. The alternative blocks every tool call on
+an availability failure, which is what a deployment chooses with `=0`.
 
 **Lone surrogates are normalized to U+FFFD before the redactor sees the text.**
 A secret split by an interposed lone surrogate renders as contiguous to the
@@ -608,9 +609,9 @@ RECONSTITUTES during stripping is judged as the sequence it becomes.
 Layer order: 1 → 2–3 → 4 → 5 → 4, the second Layer 4 a re-scan of what Layer 5's
 deletions left. Shape matters
 (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. That
+Layer 4 (secret redaction) is an **injected** redactor: a redactor that throws
+makes the pipeline rethrow rather than return an unvetted value, and the
+caller's posture decides whether the output is suppressed. 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: … }`
@@ -977,14 +978,13 @@ to hold precision. All other faults keep the open default, and
 
 **The open default is not enforceable against content.** Several of those
 failures are composable by whoever authored the payload — in the output hook
-alone, a nesting depth that overflows the sanitize walk and a redaction budget
-exhausted by many secret-shaped leaves — though with Layer 4 opted in, the
-output hook withholds on any fault whatever the knob says (see Layer 4). (A
-**key collision** — two field names that collapse to one after Layer 1 — used
-to be on that list. It no longer
-fails the hook at all: only the colliding fields are withheld, and every sibling
-field survives. Both colliding values are replaced **whole** by a marker string,
-not walked leaf-wise: a shape-preserving walk rewrites only string leaves, so a
+alone, a nesting depth that overflows the sanitize walk, a redaction budget
+exhausted by many secret-shaped leaves, and a payload large enough to blow the
+redactor daemon's scan budget. (A **key collision** — two field names that
+collapse to one after Layer 1 — does not fail the hook: only the colliding
+fields are withheld, and every sibling field survives. Both colliding values
+are replaced **whole** by a marker string, not walked leaf-wise: a
+shape-preserving walk rewrites only string leaves, so a
 colliding number or boolean would reach the model verbatim under a legitimate
 field name while the warning claimed it was withheld. That changes the field's
 JSON type, which is accepted because a duplicate name is off-schema by

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

@@ -37,6 +37,8 @@ let claudeAdapter;
 let Decision;
 /** @type {typeof import("agent-control-plane-core/contract").EventKind | undefined} */
 let EventKind;
+/** @type {typeof import("agent-control-plane-core/contract").renderEscalated | undefined} */
+let renderEscalated;
 
 /* c8 ignore start -- module-load boundary: the real import resolves in every
    in-process test and spawned CLI run, and a missing node_modules can't be
@@ -55,26 +57,35 @@ const loaded = await awaitLazyDependency({
       );
     // The /contract subpath, not the package root: the root barrel also pulls
     // all four adapters, the registry and the conformance harness, which costs
-    // ~22 ms of import work per process for two enums. A guardrail hook is one
-    // process per tool call, so that cost lands on every gated call.
-    const { Decision: decision, EventKind: eventKind } =
-      /** @type {Partial<typeof import("agent-control-plane-core/contract")>} */ (
-        await lazyImport("agent-control-plane-core/contract")
-      );
-    if (!adapter || !decision || !eventKind) return null;
-    return { claudeAdapter: adapter, Decision: decision, EventKind: eventKind };
+    // ~22 ms of import work per process for three bindings. A guardrail hook is
+    // one process per tool call, so that cost lands on every gated call.
+    const {
+      Decision: decision,
+      EventKind: eventKind,
+      renderEscalated: escalated,
+    } = /** @type {Partial<typeof import("agent-control-plane-core/contract")>} */ (
+      await lazyImport("agent-control-plane-core/contract")
+    );
+    if (!adapter || !decision || !eventKind || !escalated) return null;
+    return {
+      claudeAdapter: adapter,
+      Decision: decision,
+      EventKind: eventKind,
+      renderEscalated: escalated,
+    };
   },
   markerPresent: () => markerIsTrusted(marker),
   setupAlive: () => probeSetupAlive(marker),
 });
 if (loaded) {
   const bound =
-    /** @type {{ claudeAdapter: typeof claudeAdapter, Decision: typeof Decision, EventKind: typeof EventKind }} */ (
+    /** @type {{ claudeAdapter: typeof claudeAdapter, Decision: typeof Decision, EventKind: typeof EventKind, renderEscalated: typeof renderEscalated }} */ (
       loaded
     );
   claudeAdapter = bound.claudeAdapter;
   Decision = bound.Decision;
   EventKind = bound.EventKind;
+  renderEscalated = bound.renderEscalated;
 }
 // Stryker restore all
 /* c8 ignore stop */
@@ -83,16 +94,28 @@ if (loaded) {
  * The loaded control-plane bindings, narrowed to non-undefined — or a throw
  * the calling hook's catch converts into its own failure posture. Overrides
  * exist so tests can drive the unavailable arm in-process.
- * @param {{ claudeAdapter?: unknown, Decision?: unknown, EventKind?: unknown }} [overrides]
+ * @param {{ claudeAdapter?: unknown, Decision?: unknown, EventKind?: unknown, renderEscalated?: unknown }} [overrides]
  * @returns {{
  *   claudeAdapter: typeof import("agent-control-plane-core/claude").claudeAdapter,
  *   Decision: typeof import("agent-control-plane-core/contract").Decision,
  *   EventKind: typeof import("agent-control-plane-core/contract").EventKind,
+ *   renderEscalated: typeof import("agent-control-plane-core/contract").renderEscalated,
  * }}
  */
 export function controlPlane(overrides = {}) {
-  const bindings = { claudeAdapter, Decision, EventKind, ...overrides };
-  if (!bindings.claudeAdapter || !bindings.Decision || !bindings.EventKind)
+  const bindings = {
+    claudeAdapter,
+    Decision,
+    EventKind,
+    renderEscalated,
+    ...overrides,
+  };
+  if (
+    !bindings.claudeAdapter ||
+    !bindings.Decision ||
+    !bindings.EventKind ||
+    !bindings.renderEscalated
+  )
     throw missingPackageError("agent-control-plane-core");
   return /** @type {ReturnType<typeof controlPlane>} */ (bindings);
 }
@@ -101,10 +124,10 @@ export function controlPlane(overrides = {}) {
  * Serialize a rendered NativeResponse for Claude Code's stdout, or null when
  * the body carries nothing a silent exit 0 doesn't already say. The adapter's
  * exit_code is deliberately NOT honored by the hooks: Claude Code parses hook
- * stdout as JSON only on exit 0 — under the adapter's exit-2 enforced-deny
- * channel it discards stdout and reads the (empty) stderr instead, so the
- * deny would land without its reason. For this host the stdout JSON's
- * permissionDecision IS the enforcement channel, and hooks always exit 0.
+ * stdout as JSON only on exit 0, and that body is the one channel that carries
+ * every verdict field (updatedInput, additionalContext) beside the decision.
+ * For this host the stdout JSON's permissionDecision IS the enforcement
+ * channel, and a rendered verdict always exits 0.
  * @param {{ stdout?: unknown }} response a NativeResponse from adapter.render
  * @returns {string | null}
  */
@@ -133,8 +156,10 @@ export function nativeStdout(response) {
  * native response. This encodes the two transport invariants every gate hook
  * shares: stdin is read BEFORE the control-plane bindings are touched, so a
  * package-load failure still lands in `onError` with the parsed input in hand;
- * and the process always exits 0 with the verdict in the stdout JSON (see
- * nativeStdout — exit-code enforcement is deliberately not used). Any throw —
+ * and a verdict exits 0 in the stdout JSON (see nativeStdout). The verdict
+ * renders through the package's renderEscalated: a response with no stdout body
+ * that still blocks (a deny on a payload that names no event) blocks through its
+ * exit code and stderr instead. Any throw —
  * unparsable stdin, missing package, a judge error — is reported on stderr and
  * routed to `onError(err, input)` (`input` undefined when stdin never parsed),
  * where the hook applies its declared fail posture.
@@ -152,6 +177,8 @@ export function nativeStdout(response) {
  * @param {(input: unknown) => unknown} [opts.transformInput]  raw-payload normalization before adapter.parse
  * @param {() => Promise<unknown>} [opts.readInput]  injectable stdin reader
  * @param {(chunk: string) => void} [opts.write]  injectable stdout writer
+ * @param {(chunk: string) => void} [opts.writeErr]  injectable stderr writer
+ * @param {(code: number) => void} [opts.setExitCode]  injectable exit-code setter
  * @param {import("./hook-timing.mjs").ReportTo} [opts.reportTo]  the composer
  *   that owns this hook, which a slow-run notice names and sends the report to;
  *   omitted, the notice names this package
@@ -165,6 +192,10 @@ export async function runJudgeCli(
     transformInput = (raw) => raw,
     readInput = readStdinJson,
     write = (chunk) => process.stdout.write(chunk),
+    writeErr = (chunk) => process.stderr.write(chunk),
+    setExitCode = (code) => {
+      process.exitCode = code;
+    },
     reportTo,
   },
 ) {
@@ -190,26 +221,30 @@ export async function runJudgeCli(
     // 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.
     timer = startHookTimer();
-    const { claudeAdapter: adapter } = controlPlane();
+    const { claudeAdapter: adapter, renderEscalated: render } = controlPlane();
     const event = adapter.parse(transformInput(input));
     tool = event.tool ?? null;
     // Awaited into its own binding first: as an inline argument, the timer read
     // would be evaluated BEFORE the judge it is supposed to be timing.
     const judged = await judge(event);
-    const out = nativeStdout(
-      adapter.render(
-        withSlowHookNotice(hookName, timer.wallMs(), judged, undefined, {
-          payloadBytes,
-          tool,
-          cpuMs: timer.cpuMs(),
-          redactorMs: timer.redactorMs(),
-          hostMs: timer.hostMs(),
-          reportTo,
-        }),
-        event,
-      ),
+    const response = render(
+      adapter,
+      withSlowHookNotice(hookName, timer.wallMs(), judged, undefined, {
+        payloadBytes,
+        tool,
+        cpuMs: timer.cpuMs(),
+        redactorMs: timer.redactorMs(),
+        hostMs: timer.hostMs(),
+        reportTo,
+      }),
+      event,
     );
+    const out = nativeStdout(response);
     if (out !== null) write(out);
+    else if (response.enforced) {
+      writeErr(`${response.stderr}\n`);
+      setExitCode(response.exit_code);
+    }
   } catch (err) {
     process.stderr.write(`${hookName} hook error: ${errMessage(err)}\n`);
     // After the error line, before the posture: the fault is what the reader

package/claude-hooks/lib/env-config.mjs

@@ -15,7 +15,7 @@
  * esbuild inlines them into the plugin bundle (which ships with no config
  * directory beside it) and Node resolves them natively from the package when the
  * hooks run from source. Their VALIDATION stays lazy — a malformed credential
- * vocabulary throws on first use, inside the consuming hook's fail-closed catch,
+ * vocabulary throws on first use, inside the consuming hook's fault catch,
  * rather than at module load where a throw would abort before that catch installs
  * and let the harness pass the tool output through UNSANITIZED (fail OPEN).
  */
@@ -72,7 +72,7 @@ export function configureEnvConfigSource(source) {
 /**
  * The stored host source with its shape validated, or null when unconfigured.
  * Shape errors — a non-object source, a key this seam does not read — throw
- * HERE, on first use inside the consuming hook's fail-closed catch, never at
+ * HERE, on first use inside the consuming hook's fault catch, never at
  * configure time: a top-level throw in a bundle entry would kill the hook
  * before that catch installs (fail OPEN), and silently ignoring the problem
  * is worse — a typo'd `minSecretLength: 32` must not leave the helpers

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

@@ -85,41 +85,23 @@ export const FAULT_POLICY_HOOKS = Object.freeze([
  * The context a builder is handed: the caller's own inputs (whatever it passed
  * to {@link hookFaultOutcome}) plus the values every hook derived by hand
  * before — the hook name, the scrubbed error message, and the model-facing
- * open-posture warning — and `pinnedClosed`, true when the policy's
- * `alwaysClosed` overrode an open knob, so the closed arm can say why.
+ * open-posture warning.
  * @typedef {Record<string, any> & {
  *   hook: string,
  *   err: unknown,
  *   message: string,
  *   openContext: string,
- *   pinnedClosed: boolean,
  * }} FaultContext
  */
 
 /**
- * Whether a hook's faults are withheld whatever AGENT_SANITIZER_FAIL_OPEN says,
- * for the caller's environment.
- * @typedef {(
- *   env: NodeJS.ProcessEnv | Record<string, string | undefined> | undefined,
- * ) => boolean} AlwaysClosed
- */
-
-/**
- * The `alwaysClosed` of a hook whose posture the knob alone decides.
- * @type {AlwaysClosed}
- */
-export const KNOB_DECIDES = Object.freeze(() => false);
-
-/**
- * A hook's declared posture. `alwaysClosed` is REQUIRED, so every hook states
- * on the record whether the knob can open it: {@link KNOB_DECIDES}, or a
- * predicate that pins the CLOSED arm — how a guarantee the docs make
- * unconditionally (Layer 4 withholds what it could not vet) is enforced in the
- * one posture resolver rather than by a hook re-reading the knob.
+ * A hook's declared posture. There is deliberately no way for a policy to pin
+ * the CLOSED arm: AGENT_SANITIZER_FAIL_OPEN alone decides, so no hook fault can
+ * withhold a tool output or block a prompt unless the operator set the knob to
+ * `0`. A pin turns any bug in the guarded layer into every tool call failing.
  * @typedef {{
  *   event: string | null,
  *   guarded: string,
- *   alwaysClosed: AlwaysClosed,
  *   open?: (ctx: FaultContext) => FaultParts,
  *   closed: (ctx: FaultContext) => FaultParts,
  * }} FaultPolicy
@@ -143,12 +125,10 @@ export function registerFaultPolicy(hook, policy) {
     );
   // Checked here, not at fault time: a posture that is incomplete must fail the
   // import, never the one fault it was supposed to answer.
-  for (const arm of /** @type {const} */ (["alwaysClosed", "closed"]))
-    if (typeof policy[arm] !== "function")
-      throw new Error(
-        `fault policy for ${JSON.stringify(hook)} declares no \`${arm}\`; ` +
-          "every hook states it explicitly (KNOB_DECIDES for alwaysClosed)",
-      );
+  if (typeof policy.closed !== "function")
+    throw new Error(
+      `fault policy for ${JSON.stringify(hook)} declares no \`closed\` arm`,
+    );
   policies.set(hook, policy);
 }
 
@@ -190,8 +170,7 @@ export function defaultOpen(ctx) {
 /**
  * Resolve `hook`'s response to its own failure under the caller's posture. This
  * is the ONLY place {@link failOpenEnabled} is consulted on a hook fault, so the
- * knob cannot be honored in three hooks and skipped in the fourth — and the
- * only place a policy's `alwaysClosed` can override it.
+ * knob cannot be honored in three hooks and skipped in the fourth.
  * @param {string} hook
  * @param {unknown} err
  * @param {Record<string, any> & {
@@ -204,9 +183,7 @@ export function defaultOpen(ctx) {
  */
 export function hookFaultOutcome(hook, err, ctx = {}) {
   const policy = faultPolicy(hook);
-  const knobOpen = failOpenEnabled(ctx.env);
-  const pinnedClosed = knobOpen && policy.alwaysClosed(ctx.env);
-  const open = knobOpen && !pinnedClosed;
+  const open = failOpenEnabled(ctx.env);
   /** @type {FaultContext} */
   const full = {
     ...ctx,
@@ -214,7 +191,6 @@ export function hookFaultOutcome(hook, err, ctx = {}) {
     err,
     message: safeErrMessage(err),
     openContext: failOpenContext(hook, policy.guarded, err),
-    pinnedClosed,
   };
   const parts = (open ? (policy.open ?? defaultOpen) : policy.closed)(full);
   const fields = parts.fields ?? null;

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

@@ -17,8 +17,16 @@
  * 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 only measurable stand-in. A caller that supplies the CPU and redactor
+ * figures is reported only when the share its owner answers for — CPU plus
+ * redactor round trips plus host extensions — itself exceeds the budget; wall
+ * time past that is the machine's, and neither a notice nor a report request is
+ * the answer to it. Redactor wait counts toward that share, so a hook wedged on a
+ * dead redactor socket (no CPU, all wait) is still reported. A wait on a
+ * subprocess this package spawns itself (a `git` probe, a lock) is charged to
+ * no window, so it reads as the machine's and goes unreported — the accepted
+ * cost of never blaming the sanitizer for a loaded host. A caller that supplies
+ * no attribution is gated on wall-clock alone.
  *
  * 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
@@ -598,6 +606,11 @@ export function startHookTimer(now = Date.now, cpuNow = processCpuMs) {
  * 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.
+ *
+ * Reached only for a run whose owned share already exceeds the budget
+ * ({@link slowHookNotice}), so the "none of them" verdict means the unmeasured
+ * remainder is larger than a share that is itself over budget — not that the
+ * hook's own cost was small.
  * @param {number} elapsedMs
  * @param {number} cpuMs
  * @param {number} redactorMs
@@ -646,10 +659,15 @@ function attributeWait(elapsedMs, cpuMs, redactorMs, hostMs, owner) {
  * sanitizer computing, and with `context.redactorMs` too it names the window the
  * 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.
+ * charge reports that window as zero, which is a measurement and not a shrug.
+ * Such a caller is reported only when `cpuMs + redactorMs + hostMs` (an absent
+ * `hostMs` counting as 0) exceeds `thresholdMs`: a wall-clock overrun whose
+ * owned share is within the budget is the machine's and returns null, so the
+ * operator is never asked to report a cost the owner did not spend. Without the
+ * measurements 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.
  *
  * A CPU figure alone cannot pick a cause, so with only that the clause names
  * candidates and commits to none. A hook that blocks on a dead socket inside a
@@ -684,6 +702,8 @@ export function slowHookNotice(
   // number, including when it is 0.
   const hostMs =
     typeof context?.hostMs === "number" ? context.hostMs : undefined;
+  if (attributed && cpuMs + redactorMs + (hostMs ?? 0) <= thresholdMs)
+    return null;
   const owner = noticeOwner(context?.reportTo, version);
   const attribution = attributed
     ? attributeWait(elapsedMs, cpuMs, redactorMs, hostMs, owner)

package/claude-hooks/lib/redactor-client.mjs

@@ -6,9 +6,9 @@
  * request is just a scan. detect-secrets stays the one and only detection engine
  * — this module never inspects the text itself.
  *
- * Fail-closed, per call only: a connection/protocol/scan failure throws so the
- * caller suppresses THAT output; it sets no session-wide state, so the next call
- * retries from scratch. If the socket is absent or dead we (re)spawn the daemon
+ * Per call only: a connection/protocol/scan failure throws, and the caller
+ * answers THAT output under its fault posture; it sets no session-wide state,
+ * so the next call retries from scratch. If the socket is absent or dead we (re)spawn the daemon
  * once and retry — a crashed daemon self-heals on the next redaction.
  *
  * Wire protocol: python/agent_sanitizer/secrets/data/redactor-protocol.json,
@@ -54,7 +54,7 @@ const DAEMON_REASON = /^[\x20-\x7e]{1,200}$/u;
 export { positiveMsOr } from "./knobs.mjs";
 
 // sun_path is 104 bytes on macOS (108 on Linux), NUL included; a longer path
-// makes the daemon's bind() fail and every call fail closed. The daemon binds
+// makes the daemon's bind() fail and every call fault. The daemon binds
 // "." + 16 hex digits before renaming onto "redactor.sock", so the longer
 // 17-byte name is what must fit.
 const SOCKET_PATH_MAX = 103;
@@ -100,7 +100,7 @@ export const DEFAULT_SOCKET_PATH = resolveSocketPath(process.env, currentUid());
  *
  * 1. `_AGENT_SANITIZER_REDACTOR_DAEMON` — authoritative when set (the launcher
  *    sets it to the provisioned venv's console script when one exists, and
- *    tests point it at dead paths to drive the fail-closed arm; a fallback
+ *    tests point it at dead paths to drive the fault arm; a fallback
  *    from an explicit setting would turn those arms into silent passes).
  * 2. The shipped self-contained zipapp (`plugin/dist/redactor/daemon.pyz`) —
  *    the guaranteed floor: it needs only a python3 on PATH, so a cold start
@@ -126,20 +126,20 @@ function daemonCommand() {
 }
 // How long to wait for a freshly-spawned daemon to start accepting. A cold start
 // pays the detect-secrets import + plugin prime (~1-3s), so the default leaves
-// margin; tests shorten it to exercise the give-up-and-fail-closed path quickly.
+// margin; tests shorten it to exercise the give-up path quickly.
 const WAIT_DEADLINE_MS = readKnob("_AGENT_SANITIZER_REDACTOR_WAIT_MS");
 
-// A daemon that ACCEPTS the connection but then stalls — a deadlock, a
-// pathological detect-secrets input, or a half-written length prefix that never
-// completes — emits none of the errno codes isRespawnable reacts to and never
-// closes, so without a deadline connectAndRequest's Promise never settles.
-// redactViaDaemon (the required, fail-closed Layer 4) would then hang until
-// Claude Code kills the PostToolUse hook at its own timeout, and a killed hook is
-// non-blocking — so the RAW, unredacted tool output is shown (the exact fail-open
-// this layer exists to prevent). The total per-connect deadline below makes a
-// stall reject, so the caller fails closed. It stays comfortably under the hook
-// timeout (two connects + the spawn wait must fit); tests shorten it via the env
-// override (read per call) or the deadlineMs parameter to exercise the path fast.
+/**
+ * The total per-connect deadline. A daemon that ACCEPTS and then stalls — a
+ * deadlock, a pathological detect-secrets input, a length prefix that never
+ * completes — emits no errno isRespawnable reacts to and never closes, so
+ * without it connectAndRequest never settles and the PostToolUse hook is killed
+ * at its timeout, which shows the RAW output with no warning. A stall instead
+ * rejects, and the caller's fault posture answers it, warning included. Two
+ * connects plus the spawn wait must fit under the hook timeout. Read per call,
+ * so tests shorten it through the env override (or the deadlineMs parameter).
+ * @returns {number}
+ */
 function requestDeadlineMs() {
   return readKnob("_AGENT_SANITIZER_REDACTOR_REQUEST_MS");
 }
@@ -270,9 +270,9 @@ export function classifySocket(socketPath, deps = {}) {
  * by us or by root, carrying no group/other write bit.
  *
  * This refusal is what blocks a co-tenant unlinking our socket and binding their
- * own listener that answers "nothing to redact" to every payload, which would flip
- * the fail-CLOSED redactor to fail-OPEN and leak unscrubbed secrets to the
- * transcript.
+ * own listener that answers "nothing to redact" to every payload, which would turn
+ * a loud fault into a silent "nothing to redact" and leak unscrubbed secrets to
+ * the transcript.
  *
  * Root ownership is trusted because it is strictly stronger than our own, not a
  * concession: a deployment may hand the socket dir to root after the daemon has
@@ -291,9 +291,9 @@ function isTrustedSocketDir(dir, uid) {
 /**
  * Open one connection, send `request`, resolve with the parsed response object
  * (or null). Rejects on connect failure, a malformed/oversize/short frame, or an
- * {error} response — every one of which the caller turns into a fail-closed. A
+ * {error} response — every one of which the caller treats as a fault. A
  * socket present but not owned by us, and a request the protocol does not
- * accept, fail closed WITHOUT dialing (the error carries no errno, so
+ * accept, throw WITHOUT dialing (the error carries no errno, so
  * isRespawnable is false): we never dial into a squat, and an oversize request
  * is not mistaken for a dead daemon worth respawning.
  * @param {string} socketPath
@@ -484,7 +484,7 @@ function canConnect(socketPath) {
 /**
  * Redact `text` via the daemon. Returns the response object (`{text, found}` for
  * plain, `{text, pairs, found}` / `{unmappable}` for map) or null when nothing was
- * redacted (plain mode). Throws to fail closed when the text cannot be vetted.
+ * redacted (plain mode). Throws when the text cannot be vetted.
  *
  * `connect`/`spawn`/`waitForSocket` are injectable seams (default to the real
  * implementations) so callers can stub the daemon in-process. `deadline` is the