agent-sanitizer 2.58.10 → 2.58.11

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.58.11",
   "description": "Defend an agent against hidden-content injection: strip payload-capable invisible Unicode and ANSI, splice out human-invisible HTML, and flag data-exfil URLs in untrusted text before any model sees it.",
   "type": "module",
   "repository": {

package/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

package/types/claude-hooks/lib/knobs.d.mts

@@ -0,0 +1,138 @@
+/**
+ * `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: string | undefined, fallback: number): number;
+/**
+ * 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<K extends keyof Knobs>(name: K, env?: NodeJS.ProcessEnv | Record<string, string | undefined>, report?: (message: string) => void): Knobs[K]["fallback"];
+/**
+ * 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: readonly string[];
+/** Every knob, by variable name. */
+export const KNOBS: Readonly<{
+    AGENT_SANITIZER_FAIL_OPEN: Readonly<Knob<boolean> & {
+        surface: Surface;
+    }>;
+    AGENT_SANITIZER_DISABLED_HOOKS: Readonly<Knob<string | undefined> & {
+        surface: Surface;
+    }>;
+    AGENT_SANITIZER_SECRETS_ENABLED: Readonly<Knob<boolean> & {
+        surface: Surface;
+    }>;
+    AGENT_SANITIZER_FLAG_DIGEST_VALUES: Readonly<Knob<boolean> & {
+        surface: Surface;
+    }>;
+    AGENT_SANITIZER_INVISIBLE_DISABLED: Readonly<Knob<boolean> & {
+        surface: Surface;
+    }>;
+    AGENT_SANITIZER_TERMINAL_DISABLED: Readonly<Knob<boolean> & {
+        surface: Surface;
+    }>;
+    AGENT_SANITIZER_OUTPUT_DISABLED: Readonly<Knob<boolean> & {
+        surface: Surface;
+    }>;
+    AGENT_SANITIZER_MAX_INPUT_BYTES: Readonly<Knob<number> & {
+        surface: Surface;
+    }>;
+    _AGENT_SANITIZER_EXTRA_SECRET_VARS: Readonly<Knob<string | undefined> & {
+        surface: Surface;
+    }>;
+    _AGENT_SANITIZER_TRACE: Readonly<Knob<number> & {
+        surface: Surface;
+    }>;
+    _AGENT_SANITIZER_TRACE_FILE: Readonly<Knob<string | undefined> & {
+        surface: Surface;
+    }>;
+    _AGENT_SANITIZER_REDACTOR_SOCKET: Readonly<Knob<string | undefined> & {
+        surface: Surface;
+    }>;
+    _AGENT_SANITIZER_REDACTOR_DAEMON: Readonly<Knob<string | undefined> & {
+        surface: Surface;
+    }>;
+    _AGENT_SANITIZER_REDACTOR_WAIT_MS: Readonly<Knob<number> & {
+        surface: Surface;
+    }>;
+    _AGENT_SANITIZER_REDACTOR_REQUEST_MS: Readonly<Knob<number> & {
+        surface: Surface;
+    }>;
+    _AGENT_SANITIZER_SANITIZE_BUDGET_MS: Readonly<Knob<number> & {
+        surface: Surface;
+    }>;
+    _AGENT_SANITIZER_REVEAL_DIR: Readonly<Knob<string | undefined> & {
+        surface: Surface;
+    }>;
+}>;
+/**
+ * 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: readonly string[];
+/**
+ * One knob: its grammar, the value an unrecognized input reads as, and the two
+ * halves of the report naming it.
+ */
+export type Knob<T> = {
+    parse: (raw: string | undefined) => T | typeof INVALID;
+    fallback: T;
+    expect: string;
+    consequence: string;
+};
+/**
+ * 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.
+ */
+export type Surface = "hooks" | "cli" | "internal";
+export type Knobs = typeof KNOBS;
+/** What a parser returns for a value its grammar does not recognize. */
+declare const INVALID: unique symbol;
+export {};

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

@@ -1,16 +1,3 @@
-/**
- * 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: string | undefined, fallback: number): number;
 /**
  * The shape the redactor returns: plain mode `{text, found}`, map mode
  * `{text, pairs, found}` or `{unmappable}`. All fields optional so a consumer
@@ -40,12 +27,12 @@ export function positiveMsOr(raw: string | undefined, fallback: number): number;
  * `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: string, deps?: {
     lstat?: typeof lstatSync;
-    uid?: number;
+    uid?: number | null;
 }): "absent" | "untrusted" | "ok";
 /**
  * Open one connection, send `request`, resolve with the parsed response object
@@ -116,6 +103,7 @@ export function redactViaDaemon(text: string, opts?: {
     now?: () => number;
 }): Promise<RedactResponse | null>;
 export const FRAME_CAP: number;
+export { positiveMsOr } from "./knobs.mjs";
 export const DEFAULT_SOCKET_PATH: string;
 /**
  * The shape the redactor returns: plain mode `{text, found}`, map mode

package/types/claude-hooks/lib/trace.d.mts

@@ -1,10 +1,23 @@
 /**
- * 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?: NodeJS.ProcessEnv): number;
+export function traceThreshold(env?: NodeJS.ProcessEnv | Record<string, string | undefined>): number;
+/**
+ * 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: string, fields: Record<string, unknown>, level: "info" | "debug", ts: number): Record<string, unknown>;
 /**
  * Emit one JSON trace line for `event` at `level` (default "info") carrying the
  * metadata `fields`. No-op when the channel is below `level`; best-effort on write.
@@ -70,6 +83,8 @@ export const TraceEvent: Readonly<{
     SCAN_INVISIBLE_CHARS_RAN: "scan_invisible_chars_ran";
     SCAN_LOADED_INSTRUCTIONS_RAN: "scan_loaded_instructions_ran";
 }>;
+/** The keys every trace line's envelope owns; a field cannot set them. */
+export const TRACE_RESERVED_KEYS: readonly string[];
 /**
  * The sink shape a hook emits through: the event name, its metadata fields, and
  * the level. A host implementation receives the same {@link TraceEvent} names the

package/types/claude-hooks/sanitize-output.d.mts

@@ -191,15 +191,14 @@ export function emitFailClosed(input: any, message: string, emit?: (fields: Reco
  * 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]