agent-sanitizer 2.58.11 → 2.59.0

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

@@ -11,11 +11,10 @@
  * 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 (both directions): a 4-byte big-endian unsigned length prefix
- * then that many bytes of UTF-8 JSON. Request {text, map, web_ingress,
- * env_secrets}; response is the same object the redactor's one-shot CLI would
- * print, or JSON null for the "nothing to redact" case, or {error} when the
- * daemon could not vet input.
+ * Wire protocol: python/agent_sanitizer/secrets/data/redactor-protocol.json,
+ * which the daemon reads too — the framing, the frame cap, and the exact shape
+ * of every request and response. A response that matches no shape the request
+ * allows fails closed.
  */
 import { spawn } from "node:child_process";
 import {
@@ -28,11 +27,18 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { envBoundSecretVars } from "./env-config.mjs";
+import {
+  FRAME_CAP,
+  FrameReader,
+  PROTOCOL,
+  conforms,
+  encodeFrame,
+  isPlainObject,
+} from "./redactor-wire.mjs";
 import { currentUid, isPrivateDir, ownedByCurrentUser } from "./hook-io.mjs";
 import { readKnob } from "./knobs.mjs";
 
-// Refuse absurd frames rather than buffer unbounded (mirrors the daemon's cap).
-export const FRAME_CAP = 16 * 1024 * 1024;
+export { FRAME_CAP };
 
 // Published here, where hosts already import it; the parser behind every
 // millisecond knob lives with the knob table.
@@ -238,10 +244,12 @@ 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
- * socket present but not owned by us fails closed WITHOUT respawning (the error
- * carries no errno, so isRespawnable is false), so we never dial into a squat.
+ * 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
+ * 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
- * @param {{text: string, map: boolean, web_ingress: boolean}} request
+ * @param {Record<string, unknown>} request
  * @param {number} [deadlineMs] total exchange deadline; defaults to the env-tunable value
  * @returns {Promise<RedactResponse|null>}
  */
@@ -259,16 +267,15 @@ export function connectAndRequest(
       );
       return;
     }
+    if (!conforms(request, PROTOCOL.request)) {
+      reject(new Error("redactor request does not match the wire protocol"));
+      return;
+    }
+    // Encoded before dialing: an over-cap request throws here, rejecting with
+    // no errno, so it is not mistaken for a dead daemon worth respawning.
+    const frame = encodeFrame(request);
     const sock = createConnection(socketPath);
-    /** @type {Buffer[]} */
-    const chunks = [];
-    // Running total of buffered bytes, so we never re-concat the whole backlog on
-    // every 'data' event (that would be O(n^2) in the response size). We concat at
-    // most twice: once to read the 4-byte header if it straddles chunks, once to
-    // slice the full frame — both O(n) overall.
-    let received = 0;
-    /** @type {number|null} */
-    let expected = null;
+    const reader = new FrameReader();
     // Total deadline for the whole connect→request→response exchange, cleared by
     // finish() on the first terminal event. A stalled daemon (post-connect
     // silence) trips it and fails the call closed instead of hanging the hook.
@@ -286,41 +293,31 @@ export function connectAndRequest(
       () => finish(reject, new Error("redactor response timeout")),
       deadlineMs,
     );
-    // The bytes buffered so far as one Buffer, copying only when more than one
-    // chunk is held (a single chunk — the common case — is returned as-is).
-    const joined = () =>
-      chunks.length === 1 ? chunks[0] : Buffer.concat(chunks, received);
     sock.on("error", (err) => finish(reject, err));
-    sock.on("connect", () => {
-      const body = Buffer.from(JSON.stringify(request), "utf8");
-      const header = Buffer.allocUnsafe(4);
-      header.writeUInt32BE(body.length, 0);
-      sock.write(Buffer.concat([header, body]));
-    });
+    sock.on("connect", () => sock.write(frame));
     sock.on("data", (chunk) => {
-      // No setEncoding, so 'data' is always a Buffer at runtime; the cast tells the
-      // type checker that without a (never-taken, uncoverable) string branch.
-      chunks.push(/** @type {Buffer} */ (chunk));
-      received += chunk.length;
-      if (expected === null) {
-        if (received < 4) return;
-        expected = joined().readUInt32BE(0);
-        if (expected > FRAME_CAP) {
-          finish(reject, new Error("oversize response frame"));
-          return;
-        }
-      }
-      if (received < 4 + expected) return;
-      const buf = joined();
-      let parsed;
+      let frameRead;
       try {
-        parsed = JSON.parse(buf.subarray(4, 4 + expected).toString("utf8"));
+        // No setEncoding, so 'data' is always a Buffer at runtime.
+        frameRead = reader.push(/** @type {Buffer} */ (chunk));
       } catch (err) {
+        // Recovery: an over-cap or non-JSON frame fails THIS call closed.
         finish(reject, err);
         return;
       }
-      if (parsed && typeof parsed === "object" && "error" in parsed) {
-        finish(reject, new Error("daemon reported redaction failure"));
+      if (frameRead === undefined) return;
+      const parsed = frameRead.value;
+      if (isPlainObject(parsed) && "error" in parsed) {
+        // The daemon's error strings are fixed literals, never request data.
+        const reason = conforms(parsed, PROTOCOL.responses.error)
+          ? `: ${parsed.error}`
+          : "";
+        finish(
+          reject,
+          new Error(
+            `daemon reported redaction failure${reason}; its log is ${join(dirname(socketPath), "daemon.log")}`,
+          ),
+        );
         return;
       }
       finish(resolve, parsed);
@@ -331,43 +328,81 @@ export function connectAndRequest(
   });
 }
 
+// How much of a failed daemon's stderr is kept for the error message: the tail,
+// which is where a Python traceback names its exception.
+const STDERR_TAIL_CHARS = 2000;
+
+/**
+ * A spawned daemon, as far as the spawning hook can see it.
+ * @typedef {object} DaemonHandle
+ * @property {() => string | undefined} failure why the daemon died before it was
+ *   ready (its exit status and stderr tail), or undefined while it may still bind
+ * @property {() => void} release stop reading its stderr
+ */
+
 /**
  * Spawn the daemon detached so it outlives this hook process. The daemon's bind()
- * is the cross-process mutex, so a racing second spawn just exits — the spawn is
- * idempotent and needs no lock here.
+ * is the cross-process mutex, so a racing second spawn just exits 0 — the spawn
+ * is idempotent and needs no lock here.
+ *
+ * Its stderr is piped back so a daemon that dies on startup (an import error, a
+ * refused cache directory) fails the call at once with its own reason rather than
+ * after the whole spawn wait with none. The daemon points its stderr at a log
+ * file before it publishes the socket, so the pipe is only read until then.
  * @param {string} socketPath
  * @param {string[]} [command] daemon command as [argv0, ...leadingArgs]
  * (injectable so tests can drive the missing-binary arm in-process;
  * production always uses daemonCommand())
+ * @returns {DaemonHandle}
  */
 export function spawnDaemon(socketPath, command = daemonCommand()) {
   const [bin, ...leading] = command;
   const child = spawn(bin, [...leading, socketPath], {
     detached: true,
-    stdio: "ignore",
+    stdio: ["ignore", "ignore", "pipe"],
+  });
+  const stderr = /** @type {import("node:net").Socket} */ (child.stderr);
+  let output = "";
+  /** @type {string | undefined} */
+  let failure;
+  stderr.setEncoding("utf8");
+  stderr.on("data", (/** @type {string} */ chunk) => {
+    output = (output + chunk).slice(-STDERR_TAIL_CHARS);
   });
   // A missing daemon binary surfaces as an async 'error' event; UNHANDLED it
   // kills this hook process, which the harness reads as "no objection" — the
-  // tool output would pass through UNSANITIZED (fail open). Swallowed, the
-  // daemon simply never binds and waitForSocket's deadline fails the call
-  // CLOSED, the declared posture for an unreachable redactor.
-  child.on("error", () => {});
+  // tool output would pass through UNSANITIZED (fail open). Recorded instead,
+  // it ends the spawn wait and fails the call CLOSED.
+  child.on("error", (err) => {
+    failure = err.message;
+  });
+  // 'close', not 'exit': it fires after stderr has drained, so the tail is whole.
+  // Exit 0 is the daemon that lost the bind race to a live one.
+  child.on("close", (code, signal) => {
+    if (code === 0) return;
+    const status = signal ? `killed by ${signal}` : `exit ${code}`;
+    const tail = output.trim();
+    failure ??= tail ? `${status}: ${tail}` : status;
+  });
   child.unref();
+  stderr.unref();
+  return { failure: () => failure, release: () => stderr.destroy() };
 }
 
 /**
- * Poll until the daemon is accepting connections or the deadline passes. Probes by
- * connecting (not just existsSync) so it waits for listen(), not merely bind().
+ * Poll until the daemon is accepting connections, the deadline passes, or
+ * `abandon` reports the spawned daemon dead. Probes by connecting (not just
+ * existsSync) so it waits for listen(), not merely bind().
  * @param {string} socketPath
- * @param {{deadlineMs?: number, stepMs?: number}} [opts]
+ * @param {{deadlineMs?: number, stepMs?: number, abandon?: () => boolean}} [opts]
  * @returns {Promise<boolean>}
  */
 export async function waitForSocket(
   socketPath,
-  { deadlineMs = WAIT_DEADLINE_MS, stepMs = 100 } = {},
+  { deadlineMs = WAIT_DEADLINE_MS, stepMs = 100, abandon = () => false } = {},
 ) {
   const deadline = Date.now() + deadlineMs;
-  while (Date.now() < deadline) {
+  while (Date.now() < deadline && !abandon()) {
     if (existsSync(socketPath) && (await canConnect(socketPath))) return true;
     await sleep(stepMs);
   }
@@ -404,17 +439,26 @@ function canConnect(socketPath) {
  * budget fails CLOSED without dialing — never dial with a non-positive deadline,
  * which would race and could return the raw, unvetted secret (fail open). Omitted,
  * the redactor keeps its own per-call request deadline (the standalone default).
+ *
+ * `webIngress` is required: it chooses between the name-trusting heuristics for
+ * local output and the stricter ones for attacker-controlled text, and a
+ * default would make that choice silently for any caller that forgot it.
  * @param {string} text
- * @param {{map?: boolean, webIngress?: boolean, socketPath?: string,
+ * @param {{map?: boolean, webIngress: boolean, socketPath?: string,
  *   deadline?: {remainingMs: () => number},
- *   connect?: typeof connectAndRequest, spawn?: typeof spawnDaemon,
- *   waitForSocket?: typeof waitForSocket, now?: () => number}} [opts]
+ *   connect?: typeof connectAndRequest,
+ *   spawn?: (socketPath: string) => DaemonHandle | void,
+ *   waitForSocket?: typeof waitForSocket, now?: () => number}} opts
  * @returns {Promise<RedactResponse|null>}
  */
-export async function redactViaDaemon(text, opts = {}) {
+export async function redactViaDaemon(text, opts) {
+  if (typeof opts?.webIngress !== "boolean")
+    throw new TypeError(
+      "redactViaDaemon: opts.webIngress must be true (attacker-controlled text) or false (local output)",
+    );
   const {
     map = false,
-    webIngress = false,
+    webIngress,
     socketPath = DEFAULT_SOCKET_PATH,
     deadline,
     connect = connectAndRequest,
@@ -441,36 +485,33 @@ export async function redactViaDaemon(text, opts = {}) {
     web_ingress: webIngress,
     env_secrets: collectEnvSecrets(),
   };
-  // Response-contract guard — every out-of-contract shape fails CLOSED, because a
-  // caller reading a field the daemon didn't set gets `undefined` and would proceed
-  // on unvetted content (fail OPEN). null (nothing to redact) is in-contract in both
-  // modes. Plain mode: `{text, found}` — text must be a string. Map mode: the
-  // `{unmappable}` marker (the daemon could not build a reversible map, so the
-  // caller suppresses) OR a `{text, pairs}` map — string text AND an array of pairs;
-  // a bare `{}` or a missing/non-array `pairs` is refused, since rehydrateRedacted
-  // reading `result.pairs` on it would silently emit the original secret-shaped
-  // content. Validated AFTER the respawn/retry logic so a malformed response is not
-  // mistaken for a dead socket worth respawning.
-  // Each throw carries the BARE cause: every call sits inside a catch that
-  // wraps what it caught, so wrapping here too would nest the sentence in itself.
-  /** @param {RedactResponse|null} result @returns {RedactResponse|null} */
+  // Response-contract guard — every shape the protocol does not allow for this
+  // mode fails CLOSED, because a caller reading a field the daemon didn't set
+  // gets `undefined` and would proceed on unvetted content (fail OPEN). Plain
+  // mode: `{text, found}`, or null for nothing to redact. Map mode: a
+  // `{text, pairs, found}` map or the `{unmappable}` marker — never null, since
+  // the daemon always answers a map request with one of the two. Validated AFTER
+  // the respawn/retry logic so a malformed response is not mistaken for a dead
+  // socket worth respawning. Each throw carries the BARE cause: every call sits
+  // inside a catch that wraps what it caught.
+  const { responses } = PROTOCOL;
+  /** @param {unknown} result @returns {RedactResponse|null} */
   const validate = (result) => {
-    if (result === null) return null;
     if (map) {
       if (
-        result?.unmappable === undefined &&
-        !(typeof result?.text === "string" && Array.isArray(result?.pairs))
+        !conforms(result, responses.map) &&
+        !conforms(result, responses.unmappable)
       )
         throw new Error(
-          "redactor returned a malformed map response (no `unmappable` marker and no `{text, pairs}` map)",
+          "redactor returned a malformed map response (neither `{text, pairs, found}` nor `{unmappable}`)",
         );
-      return result;
+      return /** @type {RedactResponse} */ (result);
     }
-    if (typeof result?.text !== "string")
+    if (result !== null && !conforms(result, responses.plain))
       throw new Error(
-        "redactor returned a malformed plain response (no string `text`)",
+        "redactor returned a malformed plain response (neither null nor `{text, found}`)",
       );
-    return result;
+    return /** @type {RedactResponse|null} */ (result);
   };
   // Every dial is charged to the redactor share, so the slow-hook notice can
   // place the wait in this call rather than guess at it: the daemon is a
@@ -491,7 +532,7 @@ export async function redactViaDaemon(text, opts = {}) {
     // Socket absent or dead: (re)spawn the daemon, wait for it, retry exactly once
     // — but only if the shared budget still has room for a cold start + a scan.
     if (budgetSpent()) throw outOfBudget("before redactor respawn");
-    spawnFn(socketPath);
+    const daemon = spawnFn(socketPath) ?? undefined;
     // Clamp the cold-start wait to what the budget still allows, so a respawn can
     // never blow it. waitForSocket returns false when the daemon never bound
     // within the deadline; surface that as the actual cause rather than the opaque
@@ -501,18 +542,30 @@ export async function redactViaDaemon(text, opts = {}) {
       budgetMs === undefined
         ? WAIT_DEADLINE_MS
         : Math.min(WAIT_DEADLINE_MS, budgetMs);
-    const waitOpts =
-      budgetMs === undefined ? undefined : { deadlineMs: waitMs };
+    const waitOpts = {
+      deadlineMs: waitMs,
+      abandon: () => daemon?.failure() !== undefined,
+    };
     // The cold-start wait is PROVISIONING — a one-time detect-secrets import and
     // plugin prime (~1-3s, see WAIT_DEADLINE_MS), paid by whichever tool call
     // happens to be first and by no other. Charging it to this hook would make
     // the slow-hook notice fire once per session on a healthy install.
-    if (!(await excludeProvisioning(() => waitFn(socketPath, waitOpts), now)))
+    const ready = await excludeProvisioning(
+      () => waitFn(socketPath, waitOpts),
+      now,
+    );
+    daemon?.release();
+    const died = daemon?.failure();
+    if (!ready)
       throw failClosed(
-        // The CLAMPED wait, since that is what actually elapsed: naming
-        // WAIT_DEADLINE_MS tells an operator debugging a 200ms budget that the
-        // redactor got seconds it was never given.
-        new Error(`redactor daemon did not start within ${waitMs}ms`),
+        new Error(
+          died === undefined
+            ? // The CLAMPED wait, since that is what actually elapsed: naming
+              // WAIT_DEADLINE_MS tells an operator debugging a 200ms budget
+              // that the redactor got seconds it was never given.
+              `redactor daemon did not start within ${waitMs}ms`
+            : `redactor daemon failed to start (${died})`,
+        ),
       );
     if (budgetSpent()) throw outOfBudget("after redactor respawn");
     try {

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

@@ -0,0 +1,145 @@
+/**
+ * The redactor daemon's wire protocol, on the Node side: the one codec every
+ * party that speaks it here (the client, and the stand-in daemons the tests
+ * serve) derives from.
+ *
+ * The protocol itself is python/agent_sanitizer/secrets/data/redactor-protocol.json,
+ * which the Python daemon reads too: the frame cap and the exact shape of every
+ * request and response. A frame is a 4-byte big-endian body length, then that
+ * many bytes of UTF-8 JSON, in both directions.
+ */
+import PROTOCOL from "../../python/agent_sanitizer/secrets/data/redactor-protocol.json" with { type: "json" };
+
+export { PROTOCOL };
+
+// Refuse absurd frames rather than buffer unbounded, in either direction.
+export const FRAME_CAP = PROTOCOL.frame_cap;
+
+const HEADER_BYTES = 4;
+
+/** @typedef {Record<string, string>} Shape protocol field name -> field type */
+
+/**
+ * Whether `value` is of protocol field type `kind` (see the protocol file's
+ * description). An unknown type throws: it is a defect in the protocol file,
+ * never a verdict on the value.
+ * @param {unknown} value
+ * @param {string} kind
+ * @returns {boolean}
+ */
+function hasType(value, kind) {
+  switch (kind) {
+    case "string":
+      return typeof value === "string";
+    case "boolean":
+      return typeof value === "boolean";
+    case "index":
+      return Number.isSafeInteger(value) && /** @type {number} */ (value) >= 0;
+    case "string-list":
+      return Array.isArray(value) && value.every((v) => typeof v === "string");
+    case "string-map":
+      return (
+        isPlainObject(value) &&
+        Object.values(value).every((v) => typeof v === "string")
+      );
+    case "pair-list":
+      return (
+        Array.isArray(value) && value.every((v) => conforms(v, PROTOCOL.pair))
+      );
+    default:
+      throw new Error(`unknown protocol field type ${JSON.stringify(kind)}`);
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+export function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Whether `value` is an object with exactly `shape`'s fields, each of its
+ * declared protocol type.
+ * @param {unknown} value
+ * @param {Shape} shape
+ * @returns {boolean}
+ */
+export function conforms(value, shape) {
+  if (!isPlainObject(value)) return false;
+  const names = Object.keys(shape);
+  return (
+    Object.keys(value).length === names.length &&
+    names.every(
+      (name) => Object.hasOwn(value, name) && hasType(value[name], shape[name]),
+    )
+  );
+}
+
+/**
+ * One frame carrying `value`. Throws (with no errno, so the client does not
+ * mistake it for a dead daemon) when the body exceeds the frame cap, which the
+ * peer would refuse unread.
+ * @param {unknown} value
+ * @returns {Buffer}
+ */
+export function encodeFrame(value) {
+  const body = Buffer.from(JSON.stringify(value), "utf8");
+  if (body.length > FRAME_CAP) {
+    throw new Error(
+      `redactor frame of ${body.length} bytes exceeds the ${FRAME_CAP}-byte frame cap`,
+    );
+  }
+  const header = Buffer.allocUnsafe(HEADER_BYTES);
+  header.writeUInt32BE(body.length, 0);
+  return Buffer.concat([header, body]);
+}
+
+/**
+ * Reassembles one frame from the chunks a stream delivers. Holds a running
+ * byte total so the backlog is concatenated at most twice (header, then the
+ * whole frame) rather than on every chunk, which would be quadratic.
+ */
+export class FrameReader {
+  /** @type {Buffer[]} */
+  #chunks = [];
+  #received = 0;
+  /** @type {number | null} */
+  #expected = null;
+
+  /**
+   * Feed one chunk. Returns `{ value }` once the whole frame has arrived and
+   * undefined before then; throws on a header over the frame cap or a body
+   * that is not JSON.
+   * @param {Buffer} chunk
+   * @returns {{ value: unknown } | undefined}
+   */
+  push(chunk) {
+    this.#chunks.push(chunk);
+    this.#received += chunk.length;
+    if (this.#expected === null) {
+      if (this.#received < HEADER_BYTES) return undefined;
+      this.#expected = this.#joined().readUInt32BE(0);
+      if (this.#expected > FRAME_CAP) {
+        throw new Error(
+          `redactor frame header claims ${this.#expected} bytes, over the ${FRAME_CAP}-byte frame cap`,
+        );
+      }
+    }
+    const end = HEADER_BYTES + this.#expected;
+    if (this.#received < end) return undefined;
+    return {
+      value: JSON.parse(
+        this.#joined().subarray(HEADER_BYTES, end).toString("utf8"),
+      ),
+    };
+  }
+
+  /** The bytes buffered so far, copying only when more than one chunk is held. */
+  #joined() {
+    return this.#chunks.length === 1
+      ? this.#chunks[0]
+      : Buffer.concat(this.#chunks, this.#received);
+  }
+}

package/claude-hooks/pretooluse-sanitize.mjs

@@ -161,9 +161,11 @@ const confusableScan = (text) =>
 const redactorIo = {
   readFile: (path) => readFileSync(path, "utf8"),
   redactMap: async (text) =>
-    /** @type {any} */ (await redactViaDaemon(text, { map: true })),
+    /** @type {any} */ (
+      await redactViaDaemon(text, { map: true, webIngress: false })
+    ),
   redact: async (text) => {
-    const out = await redactViaDaemon(text, {});
+    const out = await redactViaDaemon(text, { webIngress: false });
     return out ? /** @type {string} */ (out.text) : null;
   },
 };

package/claude-hooks/sanitize-output.mjs

@@ -171,11 +171,11 @@ function isUntrustedIngress(toolName) {
  * daemon. A transient daemon failure fails only THIS call — no session-wide
  * sentinel — and the client respawns a dead daemon on the next call.
  * @param {string} text
- * @param {boolean} [webIngress]
+ * @param {boolean} webIngress
  * @param {{remainingMs: () => number}} [deadline] shared wall-clock budget
  * @returns {Promise<{ text: string, found: string[] } | null>}
  */
-async function redactSecrets(text, webIngress = false, deadline) {
+async function redactSecrets(text, webIngress, deadline) {
   if (!matchesSecretHint(text) && !hasEnvBoundSecret(text)) return null;
   // On web ingress the field name around a value is attacker-controlled, so the
   // redactor's benign-skip heuristics (metadata field / cursor / path) are a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.58.11",
+  "version": "2.59.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": {
@@ -209,6 +209,7 @@
     "python/agent_sanitizer/data/invisible-charset.json",
     "python/agent_sanitizer/secrets/data/credential-names.json",
     "python/agent_sanitizer/secrets/data/redaction-floor.json",
+    "python/agent_sanitizer/secrets/data/redactor-protocol.json",
     "claude-hooks/*.mjs",
     "claude-hooks/lib/*.mjs",
     "claude-hooks/config/*.json",

package/python/README.md

@@ -97,9 +97,12 @@ console scripts (installed with the extra) cover both modes:
   server that configures the plugin set **once** at startup (a warm-up scan
   primes the cache before it binds, so a bound socket means ready). Wire protocol
   both directions: a 4-byte big-endian length prefix then that many bytes of
-  UTF-8 JSON. Request `{"text", "map", "web_ingress", "env_secrets"}`; response is
-  the one-shot result, JSON `null` when nothing is redacted, or `{"error": …}` on
-  a scan failure.
+  UTF-8 JSON, specified field by field in
+  `agent_sanitizer/secrets/data/redactor-protocol.json`. Every request field
+  (`text`, `map`, `web_ingress`, `env_secrets`) is required; the response is the
+  one-shot result, JSON `null` when nothing is redacted, or `{"error": …}` for a
+  malformed request or a scan failure. The daemon logs failures to `daemon.log`
+  beside the socket.
 
 Both console scripts import the engine on startup, so they fail loud if the
 `[secrets]` extra (hence `detect-secrets`) is not installed — fail closed, never

package/python/agent_sanitizer/secrets/data/redactor-protocol.json

@@ -0,0 +1,17 @@
+{
+  "description": "Wire protocol of the Layer-4 secret-redactor daemon. Both directions: a 4-byte big-endian unsigned length, then that many bytes of UTF-8 JSON, at most frame_cap bytes. The client (claude-hooks/lib/redactor-client.mjs) and the daemon (python/agent_sanitizer/secrets/daemon.py) both read this file. Every object has exactly the listed fields. Field types: string, boolean, index (a non-negative integer), string-list, string-map (an object whose values are strings), pair-list (a list of `pair` objects). A plain-mode reply may also be JSON null, meaning there was nothing to redact.",
+  "frame_cap": 16777216,
+  "request": {
+    "text": "string",
+    "map": "boolean",
+    "web_ingress": "boolean",
+    "env_secrets": "string-map"
+  },
+  "responses": {
+    "plain": { "text": "string", "found": "string-list" },
+    "map": { "text": "string", "pairs": "pair-list", "found": "string-list" },
+    "unmappable": { "unmappable": "string" },
+    "error": { "error": "string" }
+  },
+  "pair": { "placeholder": "string", "original": "string", "start": "index" }
+}

package/types/claude-hooks/lib/redactor-client.d.mts

@@ -38,38 +38,51 @@ export function classifySocket(socketPath: string, deps?: {
  * 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
- * socket present but not owned by us fails closed WITHOUT respawning (the error
- * carries no errno, so isRespawnable is false), so we never dial into a squat.
+ * 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
+ * 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
- * @param {{text: string, map: boolean, web_ingress: boolean}} request
+ * @param {Record<string, unknown>} request
  * @param {number} [deadlineMs] total exchange deadline; defaults to the env-tunable value
  * @returns {Promise<RedactResponse|null>}
  */
-export function connectAndRequest(socketPath: string, request: {
-    text: string;
-    map: boolean;
-    web_ingress: boolean;
-}, deadlineMs?: number): Promise<RedactResponse | null>;
+export function connectAndRequest(socketPath: string, request: Record<string, unknown>, deadlineMs?: number): Promise<RedactResponse | null>;
+/**
+ * A spawned daemon, as far as the spawning hook can see it.
+ * @typedef {object} DaemonHandle
+ * @property {() => string | undefined} failure why the daemon died before it was
+ *   ready (its exit status and stderr tail), or undefined while it may still bind
+ * @property {() => void} release stop reading its stderr
+ */
 /**
  * Spawn the daemon detached so it outlives this hook process. The daemon's bind()
- * is the cross-process mutex, so a racing second spawn just exits — the spawn is
- * idempotent and needs no lock here.
+ * is the cross-process mutex, so a racing second spawn just exits 0 — the spawn
+ * is idempotent and needs no lock here.
+ *
+ * Its stderr is piped back so a daemon that dies on startup (an import error, a
+ * refused cache directory) fails the call at once with its own reason rather than
+ * after the whole spawn wait with none. The daemon points its stderr at a log
+ * file before it publishes the socket, so the pipe is only read until then.
  * @param {string} socketPath
  * @param {string[]} [command] daemon command as [argv0, ...leadingArgs]
  * (injectable so tests can drive the missing-binary arm in-process;
  * production always uses daemonCommand())
+ * @returns {DaemonHandle}
  */
-export function spawnDaemon(socketPath: string, command?: string[]): void;
+export function spawnDaemon(socketPath: string, command?: string[]): DaemonHandle;
 /**
- * Poll until the daemon is accepting connections or the deadline passes. Probes by
- * connecting (not just existsSync) so it waits for listen(), not merely bind().
+ * Poll until the daemon is accepting connections, the deadline passes, or
+ * `abandon` reports the spawned daemon dead. Probes by connecting (not just
+ * existsSync) so it waits for listen(), not merely bind().
  * @param {string} socketPath
- * @param {{deadlineMs?: number, stepMs?: number}} [opts]
+ * @param {{deadlineMs?: number, stepMs?: number, abandon?: () => boolean}} [opts]
  * @returns {Promise<boolean>}
  */
-export function waitForSocket(socketPath: string, { deadlineMs, stepMs }?: {
+export function waitForSocket(socketPath: string, { deadlineMs, stepMs, abandon }?: {
     deadlineMs?: number;
     stepMs?: number;
+    abandon?: () => boolean;
 }): Promise<boolean>;
 /**
  * Redact `text` via the daemon. Returns the response object (`{text, found}` for
@@ -83,26 +96,31 @@ export function waitForSocket(socketPath: string, { deadlineMs, stepMs }?: {
  * budget fails CLOSED without dialing — never dial with a non-positive deadline,
  * which would race and could return the raw, unvetted secret (fail open). Omitted,
  * the redactor keeps its own per-call request deadline (the standalone default).
+ *
+ * `webIngress` is required: it chooses between the name-trusting heuristics for
+ * local output and the stricter ones for attacker-controlled text, and a
+ * default would make that choice silently for any caller that forgot it.
  * @param {string} text
- * @param {{map?: boolean, webIngress?: boolean, socketPath?: string,
+ * @param {{map?: boolean, webIngress: boolean, socketPath?: string,
  *   deadline?: {remainingMs: () => number},
- *   connect?: typeof connectAndRequest, spawn?: typeof spawnDaemon,
- *   waitForSocket?: typeof waitForSocket, now?: () => number}} [opts]
+ *   connect?: typeof connectAndRequest,
+ *   spawn?: (socketPath: string) => DaemonHandle | void,
+ *   waitForSocket?: typeof waitForSocket, now?: () => number}} opts
  * @returns {Promise<RedactResponse|null>}
  */
-export function redactViaDaemon(text: string, opts?: {
+export function redactViaDaemon(text: string, opts: {
     map?: boolean;
-    webIngress?: boolean;
+    webIngress: boolean;
     socketPath?: string;
     deadline?: {
         remainingMs: () => number;
     };
     connect?: typeof connectAndRequest;
-    spawn?: typeof spawnDaemon;
+    spawn?: (socketPath: string) => DaemonHandle | void;
     waitForSocket?: typeof waitForSocket;
     now?: () => number;
 }): Promise<RedactResponse | null>;
-export const FRAME_CAP: number;
+export { FRAME_CAP };
 export { positiveMsOr } from "./knobs.mjs";
 export const DEFAULT_SOCKET_PATH: string;
 /**
@@ -120,4 +138,19 @@ export type RedactResponse = {
     }[] | undefined;
     unmappable?: string | undefined;
 };
+/**
+ * A spawned daemon, as far as the spawning hook can see it.
+ */
+export type DaemonHandle = {
+    /**
+     * why the daemon died before it was
+     * ready (its exit status and stderr tail), or undefined while it may still bind
+     */
+    failure: () => string | undefined;
+    /**
+     * stop reading its stderr
+     */
+    release: () => void;
+};
 import { lstatSync } from "node:fs";
+import { FRAME_CAP } from "./redactor-wire.mjs";

package/types/claude-hooks/lib/redactor-wire.d.mts

@@ -0,0 +1,46 @@
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+export function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Whether `value` is an object with exactly `shape`'s fields, each of its
+ * declared protocol type.
+ * @param {unknown} value
+ * @param {Shape} shape
+ * @returns {boolean}
+ */
+export function conforms(value: unknown, shape: Shape): boolean;
+/**
+ * One frame carrying `value`. Throws (with no errno, so the client does not
+ * mistake it for a dead daemon) when the body exceeds the frame cap, which the
+ * peer would refuse unread.
+ * @param {unknown} value
+ * @returns {Buffer}
+ */
+export function encodeFrame(value: unknown): Buffer;
+export { PROTOCOL };
+export const FRAME_CAP: number;
+/**
+ * Reassembles one frame from the chunks a stream delivers. Holds a running
+ * byte total so the backlog is concatenated at most twice (header, then the
+ * whole frame) rather than on every chunk, which would be quadratic.
+ */
+export class FrameReader {
+    /**
+     * Feed one chunk. Returns `{ value }` once the whole frame has arrived and
+     * undefined before then; throws on a header over the frame cap or a body
+     * that is not JSON.
+     * @param {Buffer} chunk
+     * @returns {{ value: unknown } | undefined}
+     */
+    push(chunk: Buffer): {
+        value: unknown;
+    } | undefined;
+    #private;
+}
+/**
+ * protocol field name -> field type
+ */
+export type Shape = Record<string, string>;
+import PROTOCOL from "../../python/agent_sanitizer/secrets/data/redactor-protocol.json" with { type: "json" };