agent-sanitizer 2.58.10 → 2.59.0

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,
@@ -159,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;
   },
 };
@@ -420,7 +424,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 +852,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
@@ -169,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
@@ -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),
     },

package/claude-hooks/sanitize-user-prompt.mjs

@@ -28,6 +28,7 @@ import {
 } from "./lib/hook-io.mjs";
 import {
   registerFaultPolicy,
+  KNOB_DECIDES,
   hookFaultOutcome,
   writeFaultOutcome,
 } from "./lib/hook-fault.mjs";
@@ -85,6 +86,7 @@ const HOOK_NAME = "sanitize-user-prompt";
 registerFaultPolicy(HOOK_NAME, {
   event: HookEvent.USER_PROMPT_SUBMIT,
   guarded: "prompt",
+  alwaysClosed: KNOB_DECIDES,
   closed: (ctx) => ({
     envelope: {
       decision: "block",

package/claude-hooks/scan-invisible-chars.mjs

@@ -39,6 +39,7 @@ import {
 } from "./lib/hook-io.mjs";
 import {
   registerFaultPolicy,
+  KNOB_DECIDES,
   hookFaultOutcome,
   writeFaultOutcome,
 } from "./lib/hook-fault.mjs";
@@ -163,6 +164,7 @@ function faultLine(ctx) {
 registerFaultPolicy(HOOK_NAME, {
   event: HookEvent.SESSION_START,
   guarded: "instruction files",
+  alwaysClosed: KNOB_DECIDES,
   open: (ctx) => ({
     stderr: `${faultLine(ctx)} Passing through unguarded; set AGENT_SANITIZER_FAIL_OPEN=0 to arm the tool-call gate instead.\n`,
     exitCode: 1,

package/claude-hooks/scan-loaded-instructions.mjs

@@ -32,6 +32,7 @@ import {
 } from "./lib/hook-io.mjs";
 import {
   registerFaultPolicy,
+  KNOB_DECIDES,
   hookFaultOutcome,
   writeFaultOutcome,
 } from "./lib/hook-fault.mjs";
@@ -121,6 +122,7 @@ function emptyPayloadParts(ctx) {
 registerFaultPolicy(HOOK_NAME, {
   event: HookEvent.INSTRUCTIONS_LOADED,
   guarded: "a loaded instruction file",
+  alwaysClosed: KNOB_DECIDES,
   open: (ctx) =>
     emptyPayloadParts(ctx) ?? {
       stderr: `${faultLine(ctx)} Passing through unguarded; set AGENT_SANITIZER_FAIL_OPEN=0 to arm the tool-call gate instead.\n`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.58.10",
+  "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/src/instructions.mjs

@@ -362,8 +362,13 @@ function keepContained(absPath, realRoot, literalRoot, pattern) {
  */
 export function walkContextGlobs(globs, cwd, exclude) {
   const root = resolve(cwd);
+  // Resolved against `root`, never joined: for a literal path segment (the
+  // `.claude` of `.claude/*.md`) Node hands `exclude` a Dirent whose
+  // parentPath is RELATIVE to the glob's cwd, and `relative()` would resolve
+  // it against process.cwd() — pruning `.claude` whenever the process runs
+  // under a `.claude/worktrees/` checkout.
   /** @param {import("node:fs").Dirent} dirent @returns {string} */
-  const absolute = (dirent) => join(dirent.parentPath, dirent.name);
+  const absolute = (dirent) => resolve(root, dirent.parentPath, dirent.name);
   return globSync(globs, {
     cwd,
     withFileTypes: true,

package/types/claude-hooks/lib/env-config.d.mts

@@ -59,18 +59,19 @@ export function dynamicSecretVars(env?: Record<string, string | undefined>): str
  */
 export function extraSecretVars(env?: Record<string, string | undefined>): string[];
 /**
- * True when the operator opted into the secret-redaction layer. `=== "1"`
- * matches the other public knobs (`AGENT_SANITIZER_*_DISABLED`): any other
- * value — unset, "true", "yes" — keeps the layer off, so a typo can only fail
- * toward the default (no secret machinery), never silently enable it.
+ * True when the operator opted into the secret-redaction layer. Only `1`
+ * enables it, matching the other public switches (`AGENT_SANITIZER_*_DISABLED`)
+ * and the SessionStart provisioning gate in provision-redactor.sh, so the hooks
+ * never redact through an engine that was not provisioned. Any other value
+ * keeps the layer off — reported, so `true` is not silently a no-op.
  * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
  * @returns {boolean}
  */
 export function secretsEnabled(env?: NodeJS.ProcessEnv | Record<string, string | undefined>): boolean;
 /**
- * True when the operator opted into flagging digest-shaped URL values. `=== "1"`
- * for the reason {@link secretsEnabled} gives: a typo fails toward the default,
- * which is the exemption the precision rule prefers.
+ * True when the operator opted into flagging digest-shaped URL values. Only
+ * `1`, for the reason {@link secretsEnabled} gives: a typo fails toward the
+ * default (reported), which is the exemption the precision rule prefers.
  * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
  * @returns {boolean}
  */

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

@@ -32,7 +32,8 @@ export function defaultOpen(ctx: FaultContext): FaultParts;
 /**
  * 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.
+ * knob cannot be honored in three hooks and skipped in the fourth — and the
+ * only place a policy's `alwaysClosed` can override it.
  * @param {string} hook
  * @param {unknown} err
  * @param {Record<string, any> & {
@@ -64,6 +65,63 @@ export function writeFaultOutcome(outcome: FaultOutcome, write?: (chunk: string)
  * @type {readonly string[]}
  */
 export const FAULT_POLICY_HOOKS: readonly string[];
+/**
+ * What a hook's fault renders to. `fields`/`envelope` are the stdout response
+ * (`fields` is the `hookSpecificOutput` body, wrapped with the policy's event;
+ * `envelope` is a hook that answers with a top-level shape instead, like
+ * UserPromptSubmit's `{decision:"block"}`); `stderr` and `exitCode` are the
+ * process-level halves a hook with no stdout channel uses; `armAlert` asks the
+ * caller to persist its cross-hook alert so a LATER gate carries the closed
+ * posture the faulting hook could not express itself.
+ * @typedef {{
+ *   posture: "open" | "closed",
+ *   fields: Record<string, unknown> | null,
+ *   fallbackFields: Record<string, unknown> | null,
+ *   envelope: object | null,
+ *   stderr: string | null,
+ *   exitCode: number,
+ *   armAlert: boolean,
+ * }} FaultOutcome
+ */
+/**
+ * What a policy's `open`/`closed` builder returns: any subset of a
+ * {@link FaultOutcome}'s renderable slots. Everything omitted takes its default
+ * (no output, exit 0, no alert).
+ * @typedef {{
+ *   fields?: Record<string, unknown>,
+ *   fallbackFields?: Record<string, unknown>,
+ *   envelope?: object,
+ *   stderr?: string,
+ *   exitCode?: number,
+ *   armAlert?: boolean,
+ * }} FaultParts
+ */
+/**
+ * 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.
+ * @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: AlwaysClosed;
 /**
  * What a hook's fault renders to. `fields`/`envelope` are the stdout response
  * (`fields` is the `hookSpecificOutput` body, wrapped with the policy's event;
@@ -97,22 +155,34 @@ export type FaultParts = {
 };
 /**
  * The context a builder is handed: the caller's own inputs (whatever it passed
- * to {@link hookFaultOutcome}) plus the three values every hook derived by hand
+ * 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.
+ * open-posture warning — and `pinnedClosed`, true when the policy's
+ * `alwaysClosed` overrode an open knob, so the closed arm can say why.
  */
 export type FaultContext = Record<string, any> & {
     hook: string;
     err: unknown;
     message: string;
     openContext: string;
+    pinnedClosed: boolean;
 };
 /**
- * A hook's declared posture.
+ * Whether a hook's faults are withheld whatever AGENT_SANITIZER_FAIL_OPEN says,
+ * for the caller's environment.
+ */
+export type AlwaysClosed = (env: NodeJS.ProcessEnv | Record<string, string | undefined> | undefined) => boolean;
+/**
+ * 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.
  */
 export type FaultPolicy = {
     event: string | null;
     guarded: string;
+    alwaysClosed: AlwaysClosed;
     open?: (ctx: FaultContext) => FaultParts;
     closed: (ctx: FaultContext) => FaultParts;
 };

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

@@ -80,7 +80,8 @@ export function readFlag(argv: string[], name: string): string | undefined;
  * mistake is reversed: those default to the safe side, so an unrecognized value
  * there costs nothing, while here it leaves an operator who asked for
  * strictness without it. `"false"` is the one spelling reached for by reflex,
- * so it is honored; everything else (`""`, `"no"`, `"off"`) is the open posture.
+ * so it is honored; everything else (`""`, `"no"`, `"off"`) is the open posture,
+ * and a value that is neither a closed nor an open spelling is reported.
  * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
  * @returns {boolean}
  */
@@ -423,6 +424,58 @@ export function awaitLazyDependency({ tryImport, markerPresent, setupAlive, now,
  * @returns {boolean}
  */
 export function markerIsTrusted(path: string | null): boolean;
+/**
+ * This process's real uid, or null on a platform with no POSIX uid model.
+ *
+ * `process.getuid()` and never `os.userInfo().uid`: userInfo() resolves the
+ * uid through the passwd database and THROWS (ENOENT) when the uid has no entry
+ * — the ordinary state of a container started with `--user 54321` — so every
+ * ownership check built on it crashed the hook that asked, and a crashed hook
+ * is non-blocking. The uid is a kernel fact; the passwd name is not needed.
+ *
+ * Null is explicit rather than the -1 userInfo() reports on Windows: callers
+ * test ownership through {@link ownedByCurrentUser}, which reads null as "cannot
+ * prove ownership" — the untrusted side every caller already handles.
+ * @returns {number | null}
+ */
+export function currentUid(): number | null;
+/**
+ * Whether `st` (an lstat result) is owned by this process's uid. THE ownership
+ * predicate for every $TMPDIR store these hooks trust — a second spelling is how
+ * four call sites came to share the passwd-lookup crash {@link currentUid}
+ * documents. False when the platform has no uid model: ownership that cannot be
+ * proven is not granted. `uid` is a seam for a test that must model another
+ * uid's file; production takes the default.
+ * @param {{ uid: number }} st
+ * @param {number | null} [uid]
+ * @returns {boolean}
+ */
+export function ownedByCurrentUser(st: {
+    uid: number;
+}, uid?: number | null): boolean;
+/**
+ * Whether `st` (an lstat result) is a directory no untrusted uid can change: a
+ * real directory (lstat, so a planted symlink is not one), owned by this uid —
+ * or by root where `rootMayOwn` — with no group/other write bit. THE trust test
+ * for every private directory these hooks keep in $TMPDIR. Write is the
+ * property because creating, unlinking or replacing an entry needs write on its
+ * parent: a co-tenant holding it can delete the finding a gate needs, swap a
+ * reveal file, or rebind the redactor socket to a listener that redacts nothing.
+ * Root ownership is strictly stronger than ours, so a deployment may hand a dir
+ * to root (`rootMayOwn`); with no uid model nothing is trusted, root included.
+ * @param {{ isDirectory(): boolean, uid: number, mode: number }} st
+ * @param {{ uid?: number | null, rootMayOwn?: boolean }} [opts]  `uid` as in
+ *   {@link ownedByCurrentUser}
+ * @returns {boolean}
+ */
+export function isPrivateDir(st: {
+    isDirectory(): boolean;
+    uid: number;
+    mode: number;
+}, { uid, rootMayOwn }?: {
+    uid?: number | null;
+    rootMayOwn?: boolean;
+}): boolean;
 /**
  * Create a presence sentinel at `path` without following a symlink a co-tenant
  * may have pre-planted there. These sentinels live at predictable, world-visible
@@ -486,19 +539,7 @@ export const PermissionDecision: Readonly<{
  * by construction, not by remembering to set an env var.
  */
 export const FAIL_OPEN_ENV: "AGENT_SANITIZER_FAIL_OPEN";
-/**
- * Values that turn the default posture back to fail-closed. 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: readonly string[];
+export { FAIL_CLOSED_VALUES } from "./knobs.mjs";
 /**
  * The public knob that turns individual hooks off: a comma-separated list of
  * hook names (the `--hook=` modes). The layer opt-outs