agent-sanitizer 2.58.10 → 2.58.11

package/claude-hooks/lib/knobs.mjs

@@ -0,0 +1,286 @@
+/**
+ * THE environment knobs the hooks and the CLI read, as one table.
+ *
+ * Every `AGENT_SANITIZER_*` / `_AGENT_SANITIZER_*` read goes through
+ * {@link readKnob}, which looks the name up here, parses the raw value with the
+ * entry's own grammar, and REPORTS a value the grammar does not recognize
+ * instead of silently treating it as unset. Seven hand-rolled parsers each
+ * decided that alone, and each failed the same way: `SECRETS_ENABLED=true`
+ * left the secret layer off, `FAIL_OPEN=FALSE` left the hooks open, and
+ * `MAX_INPUT_BYTES=0.5` became a zero-byte cap — all without a word.
+ *
+ * A bad value is reported, never thrown: these variables are set outside the
+ * session, so a throw (or a blocking verdict) would fail every tool call on a
+ * config value the session cannot edit. The entry's `fallback` is what the
+ * value then reads as, and `consequence` says so in the report.
+ *
+ * `test/claude-hooks-knobs.test.mjs` parses every hook module and the CLI and
+ * asserts the knobs they read are exactly this table, and that nothing reads
+ * one past {@link readKnob}.
+ */
+
+/**
+ * Values of AGENT_SANITIZER_FAIL_OPEN that select the fail-closed posture.
+ * Matched exactly: a case-insensitive match would need `tr`, which the launcher
+ * cannot reach (it runs its no-node arm on shell builtins alone).
+ *
+ * THE single source of truth for the closed set. The shell shims cannot import
+ * it, so `plugin/scripts/lib/fail-open.sh` is GENERATED from it by
+ * `scripts/gen-fail-open-lib.mjs` and committed; the round trip is asserted in
+ * plugin/test/fail-open-parity.test.mjs. Everything else that spells the set
+ * out by hand is an implementation that must appear in the parity table in
+ * tests/test_safe_launch.py.
+ */
+export const FAIL_CLOSED_VALUES = Object.freeze(["0", "false"]);
+
+/** What a parser returns for a value its grammar does not recognize. */
+const INVALID = Symbol("invalid knob value");
+
+/**
+ * One knob: its grammar, the value an unrecognized input reads as, and the two
+ * halves of the report naming it.
+ * @template T
+ * @typedef {{
+ *   parse: (raw: string | undefined) => T | typeof INVALID,
+ *   fallback: T,
+ *   expect: string,
+ *   consequence: string,
+ * }} Knob
+ */
+
+/**
+ * `spec`, checked against {@link Knob} so a grammar and its fallback agree in
+ * type; {@link on} freezes it.
+ * @template T
+ * @param {Knob<T>} spec
+ * @returns {Knob<T>}
+ */
+const knob = (spec) => spec;
+
+/**
+ * Who sets a knob, which is where it must be documented (asserted in
+ * test/claude-hooks-knobs.test.mjs):
+ *   - `hooks`: a Claude Code plugin operator — plugin/README.md's knob tables;
+ *   - `cli`: a caller of bin/sanitize-cli.mjs — README.md;
+ *   - `internal`: `_`-prefixed plumbing hooks.json and tests set — no stable
+ *     interface, so documented nowhere by name.
+ * @typedef {"hooks" | "cli" | "internal"} Surface
+ */
+
+/**
+ * `spec`, tagged with the surface that sets it.
+ * @template {Knob<any>} S
+ * @param {Surface} surface
+ * @param {S} spec
+ * @returns {Readonly<S & { surface: Surface }>}
+ */
+const on = (surface, spec) => Object.freeze({ ...spec, surface });
+
+/** Unset and empty are the same request: the default. */
+const unset = (/** @type {string | undefined} */ raw) =>
+  raw === undefined || raw === "";
+
+/**
+ * An on/off switch spelled `1`. Only `1` turns it on, so no typo can switch a
+ * layer on or off by accident; `0` and unset are the recognized off spellings,
+ * and anything else (`true`, `yes`) is reported and reads as off.
+ * @param {string} consequence  what an unrecognized value leaves in place
+ * @returns {Knob<boolean>}
+ */
+const flag = (consequence) =>
+  knob({
+    parse: (raw) => {
+      if (raw === "1") return true;
+      return unset(raw) || raw === "0" ? false : INVALID;
+    },
+    fallback: false,
+    expect: "1 to set it, 0 or unset to leave it off",
+    consequence,
+  });
+
+/**
+ * `raw` as a finite positive number of milliseconds, else `fallback`. A bare
+ * `Number(env) || fallback` silently accepts a NEGATIVE override (`-5 || 8000`
+ * is -5), and a non-positive deadline makes a fail-closed wait return at once.
+ * @param {string | undefined} raw
+ * @param {number} fallback
+ * @returns {number}
+ */
+export function positiveMsOr(raw, fallback) {
+  const ms = Number(raw);
+  return Number.isFinite(ms) && ms > 0 ? ms : fallback;
+}
+
+/**
+ * A duration override in milliseconds.
+ * @param {number} fallback
+ * @returns {Knob<number>}
+ */
+const milliseconds = (fallback) =>
+  knob({
+    parse: (raw) => {
+      if (unset(raw)) return fallback;
+      const ms = positiveMsOr(raw, Number.NaN);
+      return Number.isNaN(ms) ? INVALID : ms;
+    },
+    fallback,
+    expect: "a positive number of milliseconds",
+    consequence: `the ${fallback} ms default applies`,
+  });
+
+/**
+ * Free text the consumer interprets itself — a path, or a list whose entries
+ * it validates against its own vocabulary. Empty reads as unset.
+ * @returns {Knob<string | undefined>}
+ */
+const text = () =>
+  knob({
+    parse: (raw) => (unset(raw) ? undefined : raw),
+    fallback: undefined,
+    expect: "any text",
+    consequence: "it is ignored",
+  });
+
+/** Trace verbosity spellings, matched case-insensitively. */
+const TRACE_LEVELS = Object.freeze({
+  0: ["", "0", "off", "false"],
+  1: ["1", "info", "true", "on"],
+  2: ["2", "debug"],
+});
+
+/** Largest single CLI request, in UTF-8 bytes, when the knob is unset. */
+const DEFAULT_MAX_INPUT_BYTES = 10 * 1024 * 1024;
+
+/** Every knob, by variable name. */
+export const KNOBS = Object.freeze({
+  // Fail-open unless one of FAIL_CLOSED_VALUES; the documented open spellings
+  // are recognized too, so only a genuinely foreign value is reported.
+  AGENT_SANITIZER_FAIL_OPEN: on(
+    "hooks",
+    knob({
+      parse: (raw) => {
+        if (raw !== undefined && FAIL_CLOSED_VALUES.includes(raw)) return false;
+        return unset(raw) || raw === "1" || raw === "true" ? true : INVALID;
+      },
+      fallback: true,
+      expect: `${FAIL_CLOSED_VALUES.join(" or ")} to fail closed, 1/true/unset for the default`,
+      consequence: "the hooks stay fail-OPEN",
+    }),
+  ),
+  AGENT_SANITIZER_DISABLED_HOOKS: on("hooks", text()),
+  AGENT_SANITIZER_SECRETS_ENABLED: on(
+    "hooks",
+    flag("the secret layer stays OFF"),
+  ),
+  AGENT_SANITIZER_FLAG_DIGEST_VALUES: on(
+    "hooks",
+    flag("digest-shaped values stay exempt"),
+  ),
+  AGENT_SANITIZER_INVISIBLE_DISABLED: on(
+    "hooks",
+    flag("invisible-character stripping stays ON"),
+  ),
+  AGENT_SANITIZER_TERMINAL_DISABLED: on(
+    "hooks",
+    flag("terminal-control stripping stays ON"),
+  ),
+  AGENT_SANITIZER_OUTPUT_DISABLED: on(
+    "hooks",
+    flag("authored-content sanitizing stays ON"),
+  ),
+  AGENT_SANITIZER_MAX_INPUT_BYTES: on(
+    "cli",
+    knob({
+      parse: (raw) => {
+        if (unset(raw)) return DEFAULT_MAX_INPUT_BYTES;
+        const bytes = Number(raw);
+        return Number.isInteger(bytes) && bytes >= 1 ? bytes : INVALID;
+      },
+      fallback: DEFAULT_MAX_INPUT_BYTES,
+      expect: "a positive whole number of bytes",
+      consequence: `the ${DEFAULT_MAX_INPUT_BYTES}-byte default applies`,
+    }),
+  ),
+  _AGENT_SANITIZER_EXTRA_SECRET_VARS: on("internal", text()),
+  _AGENT_SANITIZER_TRACE: on(
+    "internal",
+    knob({
+      parse: (raw) => {
+        const value = (raw ?? "").toLowerCase();
+        const level = Object.entries(TRACE_LEVELS).find(([, spellings]) =>
+          spellings.includes(value),
+        );
+        return level === undefined ? INVALID : Number(level[0]);
+      },
+      fallback: 0,
+      expect: "off/0, info/1/on/true, or debug/2",
+      consequence: "tracing stays off",
+    }),
+  ),
+  _AGENT_SANITIZER_TRACE_FILE: on("internal", text()),
+  _AGENT_SANITIZER_REDACTOR_SOCKET: on("internal", text()),
+  _AGENT_SANITIZER_REDACTOR_DAEMON: on("internal", text()),
+  _AGENT_SANITIZER_REDACTOR_WAIT_MS: on("internal", milliseconds(8000)),
+  _AGENT_SANITIZER_REDACTOR_REQUEST_MS: on("internal", milliseconds(20000)),
+  _AGENT_SANITIZER_SANITIZE_BUDGET_MS: on("internal", milliseconds(120000)),
+  _AGENT_SANITIZER_REVEAL_DIR: on("internal", text()),
+});
+
+/**
+ * The operator knobs the plugin's shell launcher (plugin/scripts/) reads before
+ * any JS runs. They share plugin/README.md's knob tables with the `hooks`
+ * surface, so the tables document exactly these plus that surface; JS never
+ * reads them (the partition test holds JS reads to KNOBS).
+ */
+export const LAUNCHER_KNOBS = Object.freeze([
+  "AGENT_SANITIZER_NODE",
+  "AGENT_SANITIZER_HOOK_BINARY",
+  "AGENT_SANITIZER_COMPILE_CACHE",
+  "AGENT_SANITIZER_REPEAT_DEGRADED_CONTEXT",
+]);
+
+/** @typedef {typeof KNOBS} Knobs */
+
+/** `name=value` pairs already reported, so a per-leaf read reports once. */
+const reported = new Set();
+
+/**
+ * Write `message` to stderr the first time it is seen in this process.
+ * @param {string} message
+ * @returns {void}
+ */
+function reportOnce(message) {
+  if (reported.has(message)) return;
+  reported.add(message);
+  process.stderr.write(`${message}\n`);
+}
+
+/**
+ * The parsed value of knob `name` in `env`. An unrecognized value is reported
+ * through `report` and reads as the knob's fallback; a name missing from
+ * {@link KNOBS} throws, since it is a wiring bug in this package rather than
+ * operator input.
+ * @template {keyof Knobs} K
+ * @param {K} name
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ * @param {(message: string) => void} [report]
+ * @returns {Knobs[K]["fallback"]}
+ */
+export function readKnob(name, env = process.env, report = reportOnce) {
+  if (!Object.hasOwn(KNOBS, name))
+    throw new Error(
+      `unknown knob ${JSON.stringify(name)}: declare it in KNOBS ` +
+        "(claude-hooks/lib/knobs.mjs) before reading it",
+    );
+  /** @type {Knob<any>} */
+  const spec = KNOBS[name];
+  const raw = env[name];
+  const value = spec.parse(raw);
+  if (value !== INVALID) return value;
+  const shown = JSON.stringify(/** @type {string} */ (raw).slice(0, 80));
+  report(
+    `agent-sanitizer: ${name}=${shown} is not a recognized value ` +
+      `(${spec.expect}); ${spec.consequence}.`,
+  );
+  return spec.fallback;
+}

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

@@ -24,35 +24,24 @@ import {
 } from "./hook-timing.mjs";
 import { existsSync, lstatSync } from "node:fs";
 import { createConnection } from "node:net";
-import { tmpdir, userInfo } from "node:os";
+import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { envBoundSecretVars } from "./env-config.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;
 
-/**
- * Parse a millisecond deadline from an env override, falling back to `fallback`
- * unless the value is a finite positive number. A bare `Number(env) || fallback`
- * silently accepts a NEGATIVE override (`-5 || 8000` is -5) — a non-positive
- * deadline makes the fail-closed wait/request return immediately, defeating the
- * deadline. Unset/blank/NaN/<=0 all take the sane positive fallback; a load-time
- * throw is deliberately avoided so a misconfigured env can never crash these
- * fail-closed hooks into a fail-OPEN non-load.
- * @param {string|undefined} raw the env override value
- * @param {number} fallback the sane positive default
- * @returns {number}
- */
-export function positiveMsOr(raw, fallback) {
-  const ms = Number(raw);
-  return Number.isFinite(ms) && ms > 0 ? ms : fallback;
-}
+// Published here, where hosts already import it; the parser behind every
+// millisecond knob lives with the knob table.
+export { positiveMsOr } from "./knobs.mjs";
 
 // Per-session private socket. The daemon binds it 0600 under a 0700 dir AFTER
 // priming, so its mere existence means "ready". Overridable for tests.
 export const DEFAULT_SOCKET_PATH =
-  process.env._AGENT_SANITIZER_REDACTOR_SOCKET ||
+  readKnob("_AGENT_SANITIZER_REDACTOR_SOCKET") ??
   join(tmpdir(), "agent-sanitizer-redactor", "redactor.sock");
 
 /**
@@ -71,7 +60,7 @@ export const DEFAULT_SOCKET_PATH =
  * @returns {string[]}
  */
 function daemonCommand() {
-  const configured = process.env._AGENT_SANITIZER_REDACTOR_DAEMON;
+  const configured = readKnob("_AGENT_SANITIZER_REDACTOR_DAEMON");
   if (configured) return [configured];
   // Inside the built bundle import.meta.url is .../plugin/dist/hooks/<bundle>,
   // so the committed zipapp sits one level up; from the raw sources no such
@@ -83,10 +72,7 @@ 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.
-const WAIT_DEADLINE_MS = positiveMsOr(
-  process.env._AGENT_SANITIZER_REDACTOR_WAIT_MS,
-  8000,
-);
+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
@@ -100,7 +86,7 @@ const WAIT_DEADLINE_MS = positiveMsOr(
 // 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.
 function requestDeadlineMs() {
-  return positiveMsOr(process.env._AGENT_SANITIZER_REDACTOR_REQUEST_MS, 20000);
+  return readKnob("_AGENT_SANITIZER_REDACTOR_REQUEST_MS");
 }
 
 /**
@@ -196,18 +182,18 @@ function failClosed(cause) {
  * `lstat`/`uid` are injectable seams so a test can drive a stat shape the test
  * process cannot create (a dir owned by another uid); production binds the real ones.
  * @param {string} socketPath
- * @param {{lstat?: typeof lstatSync, uid?: number}} [deps]
+ * @param {{lstat?: typeof lstatSync, uid?: number | null}} [deps]
  * @returns {"absent" | "untrusted" | "ok"}
  */
 export function classifySocket(socketPath, deps = {}) {
-  const { lstat = lstatSync, uid = userInfo().uid } = deps;
+  const { lstat = lstatSync, uid = currentUid() } = deps;
   let st;
   try {
     st = lstat(socketPath);
   } catch {
     return "absent";
   }
-  if (!st.isSocket() || st.uid !== uid) return "untrusted";
+  if (!st.isSocket() || !ownedByCurrentUser(st, uid)) return "untrusted";
   let dir;
   try {
     dir = lstat(dirname(socketPath));
@@ -241,15 +227,11 @@ export function classifySocket(socketPath, deps = {}) {
  * root to hand it to: there the hook spawns the daemon as the ordinary user, which
  * binds under a 0700 dir it owns, and our own uid is not the adversary.
  * @param {import("node:fs").Stats} dir
- * @param {number} uid
+ * @param {number | null} uid
  * @returns {boolean}
  */
 function isTrustedSocketDir(dir, uid) {
-  return (
-    dir.isDirectory() &&
-    (dir.uid === uid || dir.uid === 0) &&
-    (dir.mode & 0o022) === 0
-  );
+  return isPrivateDir(dir, { uid, rootMayOwn: true });
 }
 
 /**

package/claude-hooks/lib/reveal.mjs

@@ -31,9 +31,10 @@ import {
   closeSync,
   constants,
 } from "node:fs";
-import { tmpdir, userInfo } from "node:os";
+import { tmpdir } from "node:os";
 import { join, resolve, sep } from "node:path";
-import { PROJECT_HASH, writeFileNoFollow } from "./hook-io.mjs";
+import { PROJECT_HASH, isPrivateDir, writeFileNoFollow } from "./hook-io.mjs";
+import { readKnob } from "./knobs.mjs";
 
 /**
  * Where reveal sidecars are stored. Exported so the PreToolUse placeholder
@@ -48,7 +49,7 @@ export function revealDir() {
   // instead. The 12-hex span KEY inside the directory is untouched — it is the
   // published placeholder grammar, not a path detail.
   return (
-    process.env._AGENT_SANITIZER_REVEAL_DIR ||
+    readKnob("_AGENT_SANITIZER_REVEAL_DIR") ??
     join(tmpdir(), `agent-sanitizer-layer2-reveal-${PROJECT_HASH}`)
   );
 }
@@ -131,13 +132,7 @@ function revealDirIsSafe(dir) {
     return false;
   }
   /* c8 ignore stop */
-  const groupOrOtherWritable = (st.mode & 0o022) !== 0;
-  return (
-    st.isDirectory() &&
-    !st.isSymbolicLink() &&
-    st.uid === userInfo().uid &&
-    !groupOrOtherWritable
-  );
+  return isPrivateDir(st);
 }
 
 /**

package/claude-hooks/lib/trace.mjs

@@ -20,6 +20,7 @@
 
 import { appendFileSync } from "node:fs";
 import { chargeHostExtensionSync } from "./hook-timing.mjs";
+import { readKnob } from "./knobs.mjs";
 
 /**
  * The sink shape a hook emits through: the event name, its metadata fields, and
@@ -42,16 +43,44 @@ export const TraceEvent = Object.freeze({
 const LEVELS = Object.freeze({ off: 0, info: 1, debug: 2 });
 
 /**
- * Numeric verbosity from _AGENT_SANITIZER_TRACE: 0 off, 1 info, 2 debug.
- * Unknown, empty, or "off" → 0.
- * @param {NodeJS.ProcessEnv} [env]
+ * Numeric verbosity from _AGENT_SANITIZER_TRACE: 0 off, 1 info, 2 debug. Empty
+ * or "off" → 0; an unrecognized value is reported and reads as 0.
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
  * @returns {number}
  */
 export function traceThreshold(env = process.env) {
-  const value = (env._AGENT_SANITIZER_TRACE ?? "").toLowerCase();
-  if (value === "debug" || value === "2") return LEVELS.debug;
-  if (["info", "1", "true", "on"].includes(value)) return LEVELS.info;
-  return LEVELS.off;
+  return readKnob("_AGENT_SANITIZER_TRACE", env);
+}
+
+/** The keys every trace line's envelope owns; a field cannot set them. */
+export const TRACE_RESERVED_KEYS = Object.freeze(["ts", "level", "event"]);
+
+/**
+ * THE trace line's record: the envelope ({@link TRACE_RESERVED_KEYS}) first,
+ * then `fields`. A field named like an envelope key cannot overwrite it — a
+ * reader buckets on `level` and `event`, so a producer field `level: "debug"`
+ * would misfile the line — and is not dropped silently either: its name lands in
+ * `shadowed`, so the producer bug is visible on the channel it broke.
+ * @param {string} event
+ * @param {Record<string, unknown>} fields
+ * @param {"info"|"debug"} level
+ * @param {number} ts
+ * @returns {Record<string, unknown>}
+ */
+export function traceRecord(event, fields, level, ts) {
+  const shadowed = TRACE_RESERVED_KEYS.filter((key) =>
+    Object.hasOwn(fields, key),
+  );
+  const rest = Object.fromEntries(
+    Object.entries(fields).filter(([key]) => !shadowed.includes(key)),
+  );
+  return {
+    ts,
+    level,
+    event,
+    ...rest,
+    ...(shadowed.length > 0 ? { shadowed } : {}),
+  };
 }
 
 /**
@@ -69,8 +98,8 @@ export function trace(event, fields = {}, level = "info") {
   const lvl = level === "debug" ? "debug" : "info";
   if (traceThreshold() < LEVELS[lvl]) return;
   const line =
-    JSON.stringify({ ts: Date.now(), level: lvl, event, ...fields }) + "\n";
-  const file = process.env._AGENT_SANITIZER_TRACE_FILE;
+    JSON.stringify(traceRecord(event, fields, lvl, Date.now())) + "\n";
+  const file = readKnob("_AGENT_SANITIZER_TRACE_FILE");
   try {
     if (file) appendFileSync(file, line);
     else process.stderr.write(line);

package/claude-hooks/plugin-hooks.mjs

@@ -26,6 +26,7 @@ import {
 } from "./lib/hook-io.mjs";
 import {
   registerFaultPolicy,
+  KNOB_DECIDES,
   hookFaultOutcome,
   writeFaultOutcome,
 } from "./lib/hook-fault.mjs";
@@ -54,6 +55,7 @@ const unknownMode = (/** @type {{ message: string }} */ ctx) => ({
 registerFaultPolicy(HOOK_NAME, {
   event: null,
   guarded: "hook payload",
+  alwaysClosed: KNOB_DECIDES,
   open: unknownMode,
   closed: unknownMode,
 });

package/claude-hooks/pretooluse-sanitize.mjs

@@ -45,6 +45,7 @@ import {
 } from "./lib/hook-io.mjs";
 import {
   registerFaultPolicy,
+  KNOB_DECIDES,
   hookFaultOutcome,
   defaultOpen,
 } from "./lib/hook-fault.mjs";
@@ -65,6 +66,7 @@ import {
 } from "./lib/authored-content.mjs";
 import { redactViaDaemon } from "./lib/redactor-client.mjs";
 import { secretsEnabled } from "./lib/env-config.mjs";
+import { readKnob } from "./lib/knobs.mjs";
 import { withSecretDropGuard } from "./lib/secret-drop-guard.mjs";
 import {
   placeholderNotice,
@@ -420,7 +422,7 @@ export function preToolUseLayers(rehydrate, env = process.env) {
       run: (tool, toolInput) => rehydrateLayer2(tool, toolInput),
     },
   ];
-  return env.AGENT_SANITIZER_OUTPUT_DISABLED === "1"
+  return readKnob("AGENT_SANITIZER_OUTPUT_DISABLED", env)
     ? layers.filter((layer) => layer.name !== "authored-content")
     : layers;
 }
@@ -848,6 +850,7 @@ export function hookFailureFields(parsedOk, err, opts = {}) {
 registerFaultPolicy(HOOK_NAME, {
   event: HookEvent.PRE_TOOL_USE,
   guarded: "tool input",
+  alwaysClosed: KNOB_DECIDES,
   open: (ctx) => {
     // Non-carve-out faults take the SHARED open rendering, not a copy of it —
     // hook-fault.mjs owns that body, and a restated one would silently drift.

package/claude-hooks/sanitize-output.mjs

@@ -24,7 +24,8 @@
  * Layer 3 and the strict secret mode run on all MCP connector output (see
  * isUntrustedIngress).
  */
-import { redactViaDaemon, positiveMsOr } from "./lib/redactor-client.mjs";
+import { redactViaDaemon } from "./lib/redactor-client.mjs";
+import { readKnob } from "./lib/knobs.mjs";
 import {
   chargeHostExtension,
   chargeHostExtensionSync,
@@ -49,7 +50,11 @@ import { registerFaultPolicy, hookFaultOutcome } from "./lib/hook-fault.mjs";
 import { controlPlane, runJudgeCli } from "./lib/control-plane.mjs";
 import { hookTrace, TraceEvent } from "./lib/trace.mjs";
 import { hasEnvBoundSecret } from "./lib/secret-annotate.mjs";
-import { digestFlaggingEnabled, secretsEnabled } from "./lib/env-config.mjs";
+import {
+  digestFlaggingEnabled,
+  secretsEnabled,
+  SECRETS_ENABLED_ENV,
+} from "./lib/env-config.mjs";
 import {
   persistReveal,
   persistSpan,
@@ -118,10 +123,7 @@ export const REVEAL_WITHHELD_WARNING = withheldWarning("reveal sidecar");
 // would be shown (fail OPEN). The default sits comfortably above one legitimately
 // slow leaf (a cold redactor respawn + a full scan) yet far under the hook
 // timeout; env-tunable so tests can drive the exhausted-budget path fast.
-const SANITIZE_BUDGET_MS = positiveMsOr(
-  process.env._AGENT_SANITIZER_SANITIZE_BUDGET_MS,
-  120000,
-);
+const SANITIZE_BUDGET_MS = readKnob("_AGENT_SANITIZER_SANITIZE_BUDGET_MS");
 
 // Web-ingress tools always get the Layer 2 HTML rewrite; local tools — Read,
 // Bash, Grep, gh — never do. A local HTML/markdown pass either rewrites bytes the
@@ -276,11 +278,11 @@ export async function sanitizeText(
     // Layer 4 — OPT-IN (secretsEnabled): with the knob unset the seam gets no
     // redact callback at all, so plain output never spawns the daemon and no
     // placeholder ever enters the model's view. When it runs, the seam rethrows
-    // a redactor throw wrapped, and the CLI applies the caller's posture to it.
-    // Surface the failure to the operator's terminal here first: whatever the
-    // CLI decides rides in additionalContext, which only the model sees, so a
-    // degraded redactor would otherwise be invisible to the human — and under
-    // the fail-open default this line is the ONLY signal the human gets.
+    // a redactor throw wrapped, and this hook's fault policy suppresses the
+    // output under either posture (alwaysClosed). Surface the failure to the
+    // operator's terminal here first: the suppression note rides in what only
+    // the model sees, so a degraded redactor would otherwise be invisible to
+    // the human.
     redact: !secretsEnabled()
       ? undefined
       : async (/** @type {string} */ content) => {
@@ -783,15 +785,14 @@ function failClosedParts(
  * fail-OPEN by default — a warning context and NO `updatedToolOutput`, leaving
  * the original tool output in the model's view — or the fail-closed
  * suppression of {@link emitFailClosed} when the caller set
- * AGENT_SANITIZER_FAIL_OPEN=0.
+ * AGENT_SANITIZER_FAIL_OPEN=0, or opted into Layer 4 (see the policy below).
  *
  * This is the hook where the two postures diverge the most, so state the open
  * one plainly: several of these layers throw on inputs an attacker composes (a
- * nesting depth that overflows the walk, a redaction budget spent on a thousand
- * secret-shaped leaves), and each of those throws is
- * guarding content the open posture hands to the model verbatim, secrets
- * included. An operator who cares more about withholding a secret than about
- * keeping the session moving sets the knob to `0`.
+ * nesting depth that overflows the walk), and each of those throws is guarding
+ * content the open posture hands to the model verbatim. An operator who cares
+ * more about withholding that than about keeping the session moving sets the
+ * knob to `0`.
  * @param {any} input  parsed hook input, or undefined if parsing threw
  * @param {unknown} err
  * @param {(fields: Record<string, unknown>) => void} [emit]
@@ -830,14 +831,29 @@ function suppressionMessage(cause) {
   return `[SANITIZATION FAILED — original output suppressed for safety. Hook error: ${cause}]`;
 }
 
+/** Why an open knob still suppressed: the secret layer's own guarantee. */
+const SECRETS_PIN_NOTE =
+  ` Secret redaction is on (${SECRETS_ENABLED_ENV}=1), so output it could ` +
+  "not vet is withheld under either AGENT_SANITIZER_FAIL_OPEN posture.";
+
 // This hook's entry in the one posture table (lib/hook-fault.mjs). OPEN is the
 // shared default (a warning context, the original output left in the model's
 // view); CLOSED replaces every string leaf of the output with the placeholder.
+// With Layer 4 opted in, a fault here means the output was never vetted for
+// secrets — a dead daemon, a spent budget, a walk that overflowed before the
+// redactor ran — so this pin is what keeps the open default from handing an
+// unredacted credential to the model.
 registerFaultPolicy(HOOK_NAME, {
   event: HookEvent.POST_TOOL_USE,
   guarded: "tool output",
+  alwaysClosed: secretsEnabled,
   closed: (ctx) =>
-    failClosedParts(ctx.input, suppressionMessage(ctx.message), ctx.remedy),
+    failClosedParts(
+      ctx.input,
+      suppressionMessage(ctx.message) +
+        (ctx.pinnedClosed ? SECRETS_PIN_NOTE : ""),
+      ctx.remedy,
+    ),
 });
 
 /**
@@ -1137,9 +1153,9 @@ export async function cliMain(ext = {}) {
       // back the parsed `input` even when the control-plane load failed, so the
       // suppression shape-matches the real tool_response). emitFailClosed itself
       // falls back to a bare string if that shape-matching replacement or its
-      // serialization throws, so even a pathological input fails closed. A caller
-      // that set AGENT_SANITIZER_FAIL_OPEN=1 gets the warning-only pass-through
-      // instead — see emitHookFailure.
+      // serialization throws, so even a pathological input fails closed. Under
+      // the open default with Layer 4 off the caller gets the warning-only
+      // pass-through instead — see emitHookFailure.
       onError: (err, input) =>
         emitHookFailure(input, err, undefined, ext.remedy),
     },