agent-sanitizer 2.19.3 → 2.19.5

package/THREAT-MODEL.md

@@ -36,12 +36,24 @@ table](./README.md#entry-points) maps each to its import.
   neighbors clearly belong to the context, and it is disabled once the total
   invisible count crosses a scatter floor—over-stripping beats under-stripping.
 
-**Reassembly hardening.** Stripping an invisible char can reconstitute an ANSI
-escape its split had hidden, and removing one ANSI sequence can reconstitute
-another. Layer 1 strips ANSI to a fixed point and then sweeps any residual raw
-control introducer—7-bit ESC (U+001B) or 8-bit C1 CSI (U+009B)—outright, so the
-result carries no raw ANSI introducer for _any_ input and the operation is
-idempotent. OSC strings (titles, clickable-hyperlink URLs) are consumed as a
+**Reassembly hardening.** The two passes feed each other in _both_ directions:
+stripping an invisible char can reconstitute an ANSI escape its split had
+hidden, removing one ANSI sequence can reconstitute another, and removing an
+ANSI sequence can make two invisibles adjacent that were not—a joiner run the
+invisible pass treats as a payload channel rather than as linguistic. So Layer 1
+does not run a fixed sequence of passes; it iterates the whole
+{ANSI, invisible} composition to a fixed point (bounded, since each round
+deletes at least one character), and only once that is stable does it sweep any
+residual raw control introducer—7-bit ESC (U+001B) or any 8-bit C1 control
+(U+0080–U+009F)—outright. Sweeping earlier would strand a hidden control as
+visible text; a final unconditional sweep after the loop keeps the
+no-raw-introducer guarantee independent of the iteration bound. The result
+carries no raw ANSI introducer for _any_ input, and re-cleaning it reproduces
+it exactly—the idempotence the Edit-repair rehydrator's soundness gate assumes.
+One tokenizer answers every ANSI question (what to splice, and whether the only
+escape content is display-only SGR colour), so the stripper and the operator
+warning cannot disagree about what a sequence is. OSC strings (titles,
+clickable-hyperlink URLs) are consumed as a
 whole, for every terminator form—ST (`ESC\` or 8-bit C1 ST U+009C) and the
 legacy BEL—and for the 8-bit C1 OSC introducer (U+009D); an _unterminated_ OSC
 introducer is dropped through end-of-string (fail-closed), so no OSC body

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

@@ -0,0 +1,224 @@
+/**
+ * THE failure posture, in one place.
+ *
+ * Every hook in this package has to answer the same question when its own
+ * machinery breaks: does the guarded action proceed with a warning (fail OPEN,
+ * the shipped default) or is it withheld (fail CLOSED, what
+ * AGENT_SANITIZER_FAIL_OPEN=0 buys)? Before this module each hook answered it by
+ * hand — four hand-rolled renderings in three different envelope shapes, one
+ * hook (scan-invisible-chars) that never consulted the knob at all, and a
+ * dispatcher default arm that hard-exited past it. A posture that is re-derived
+ * per hook is a posture nobody can audit: the one hook that forgot is invisible
+ * until an operator who pinned the strict posture silently does not get it.
+ *
+ * So the posture becomes DATA. Each hook registers one policy — what it guards,
+ * which event it answers, and how its CLOSED verdict renders — and this module
+ * owns everything shared: the single {@link failOpenEnabled} read, the default
+ * OPEN rendering, and the shape of the outcome a hook then writes. A hook with
+ * no registered policy is a hard error at fault time rather than a silent
+ * default, and `test/claude-hooks-posture.test.mjs` enumerates the modules on
+ * disk so a hook added without a policy fails there first.
+ *
+ * WHY REGISTRATION AND NOT A LITERAL TABLE HERE: a closed verdict is
+ * hook-specific content (the PostToolUse suppression has to shape-match the tool
+ * response it replaces; the PreToolUse ask/deny split reads the host's message
+ * table), and every hook already imports this module's peer `hook-io.mjs`. A
+ * literal table would have to import the hooks back, which is a cycle. The list
+ * of hooks that MUST register is still declared here, as data, so the set is
+ * closed in both directions.
+ */
+import {
+  failOpenEnabled,
+  failOpenContext,
+  safeErrMessage,
+} from "./hook-io.mjs";
+
+/**
+ * The hook modules that must register a fault policy — every CLI entry point in
+ * `claude-hooks/*.mjs`. Declared here rather than discovered so registering an
+ * unknown name is an error instead of a typo nobody notices.
+ * @type {readonly string[]}
+ */
+export const FAULT_POLICY_HOOKS = Object.freeze([
+  "plugin-hooks",
+  "pretooluse-sanitize",
+  "sanitize-output",
+  "sanitize-user-prompt",
+  "scan-invisible-chars",
+]);
+
+/**
+ * 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 three values every hook derived by hand
+ * before — the hook name, the scrubbed error message, and the model-facing
+ * open-posture warning.
+ * @typedef {Record<string, any> & {
+ *   hook: string,
+ *   err: unknown,
+ *   message: string,
+ *   openContext: string,
+ * }} FaultContext
+ */
+
+/**
+ * A hook's declared posture.
+ * @typedef {{
+ *   event: string | null,
+ *   guarded: string,
+ *   open?: (ctx: FaultContext) => FaultParts,
+ *   closed: (ctx: FaultContext) => FaultParts,
+ * }} FaultPolicy
+ */
+
+/** @type {Map<string, FaultPolicy>} */
+const policies = new Map();
+
+/**
+ * Declare a hook's failure posture. Called at module scope by each hook, so
+ * importing the hook is what makes its posture reachable.
+ * @param {string} hook  a member of {@link FAULT_POLICY_HOOKS}
+ * @param {FaultPolicy} policy
+ * @returns {void}
+ */
+export function registerFaultPolicy(hook, policy) {
+  if (!FAULT_POLICY_HOOKS.includes(hook))
+    throw new Error(
+      `unknown hook ${JSON.stringify(hook)}: add it to FAULT_POLICY_HOOKS in ` +
+        "claude-hooks/lib/hook-fault.mjs before registering a posture for it",
+    );
+  policies.set(hook, policy);
+}
+
+/**
+ * The registered policy for `hook`. Throws rather than defaulting: a hook whose
+ * posture nobody declared has no defensible default — guessing OPEN would let
+ * the guarded action through on a hook an operator believed was strict, and
+ * guessing CLOSED would block a session on a wiring bug.
+ * @param {string} hook
+ * @returns {FaultPolicy}
+ */
+export function faultPolicy(hook) {
+  const policy = policies.get(hook);
+  if (policy === undefined)
+    throw new Error(
+      `no fault policy registered for hook ${JSON.stringify(hook)}; call ` +
+        "registerFaultPolicy at the hook module's scope",
+    );
+  return policy;
+}
+
+/**
+ * The default OPEN rendering: no verdict, and a non-empty `additionalContext`
+ * recording that the guarded content passed through unsanitized. Non-empty
+ * matters — an empty stdout is recorded by Claude Code as a CLEAN run rather
+ * than a degraded one, so the posture would give up visibility as well as
+ * enforcement.
+ * @param {FaultContext} ctx
+ * @returns {FaultParts}
+ */
+function defaultOpen(ctx) {
+  return { fields: { additionalContext: ctx.openContext } };
+}
+
+/**
+ * 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.
+ * @param {string} hook
+ * @param {unknown} err
+ * @param {Record<string, any> & {
+ *   env?: NodeJS.ProcessEnv | Record<string, string | undefined>,
+ * }} [ctx]  hook-specific inputs threaded to the builders (a message table, the
+ *   parsed input, a remedy). `env` selects the posture; it is threaded to the
+ *   builders along with the rest, though none reads it — the posture is resolved
+ *   here precisely so a builder never has to.
+ * @returns {FaultOutcome}
+ */
+export function hookFaultOutcome(hook, err, ctx = {}) {
+  const policy = faultPolicy(hook);
+  const open = failOpenEnabled(ctx.env);
+  /** @type {FaultContext} */
+  const full = {
+    ...ctx,
+    hook,
+    err,
+    message: safeErrMessage(err),
+    openContext: failOpenContext(hook, policy.guarded, err),
+  };
+  const parts = (open ? (policy.open ?? defaultOpen) : policy.closed)(full);
+  const fields = parts.fields ?? null;
+  // A policy that supplies `fields` but no event has nothing to wrap them in;
+  // that is a policy bug, not a runtime condition, so say so rather than
+  // silently emitting nothing (which reads as a clean run).
+  if (fields !== null && parts.envelope === undefined && policy.event === null)
+    throw new Error(
+      `fault policy for ${JSON.stringify(hook)} returns hookSpecificOutput ` +
+        "fields but declares no event to wrap them in",
+    );
+  return Object.freeze({
+    posture: open ? "open" : "closed",
+    fields,
+    fallbackFields: parts.fallbackFields ?? null,
+    envelope:
+      parts.envelope ??
+      (fields === null
+        ? null
+        : { hookSpecificOutput: { hookEventName: policy.event, ...fields } }),
+    stderr: parts.stderr ?? null,
+    exitCode: parts.exitCode ?? 0,
+    armAlert: parts.armAlert ?? false,
+  });
+}
+
+/**
+ * Render an outcome's stdout/stderr halves and return its exit code. The caller
+ * decides what to do with the code (a hook that must keep running ignores it),
+ * and performs `armAlert` itself — persisting the alert needs the hook's own
+ * report text, which this module has no view of.
+ * @param {FaultOutcome} outcome
+ * @param {(chunk: string) => void} [write]
+ * @param {(chunk: string) => void} [writeErr]
+ * @returns {number}
+ */
+export function writeFaultOutcome(
+  outcome,
+  write = (chunk) => process.stdout.write(chunk),
+  writeErr = (chunk) => process.stderr.write(chunk),
+) {
+  if (outcome.envelope !== null) write(JSON.stringify(outcome.envelope));
+  if (outcome.stderr !== null) writeErr(outcome.stderr);
+  return outcome.exitCode;
+}

package/claude-hooks/lib/layer-pipeline.mjs

@@ -0,0 +1,147 @@
+/**
+ * The PreToolUse layer chain as a DECLARED pipeline instead of a run of
+ * sequential statements.
+ *
+ * The confusable fold (Layer 2) carries a soundness precondition: it deliberately
+ * SKIPS a token that still holds an unmapped non-ASCII glyph, because such a
+ * token can never come out byte-equal to an ASCII deny-rule target, so folding it
+ * would only mangle real foreign-language text. That argument holds only while no
+ * later layer ERASES code points from the same field — if it does, the glyph the
+ * fold relied on can disappear after the decision was taken.
+ *
+ * Layer 3 (authored-content stripping) erases exactly that: payload-capable
+ * invisible characters. Running it after the fold made the precondition false,
+ * and the gap was reachable: `cat /etc/p<CYRILLIC A><12 x ZWSP>sswd` put the
+ * zero-width run inside the token, so the fold skipped it, then the strip removed
+ * the padding and emitted `cat /etc/p<CYRILLIC A>sswd` — the homoglyph intact and
+ * the evidence for skipping it gone. Zero-width padding suppressed the fold and
+ * the next layer erased the reason.
+ *
+ * The eliminator is structural: layers declare whether they ERASE code points and
+ * whether their decision is SKIP-BASED (suppressible by code points another layer
+ * erases), and this driver enforces the precondition rather than a comment
+ * asking a future reader to preserve it. When the table puts an erasing layer
+ * after a skip-based one, the driver re-runs the body to a FIXED POINT, so the
+ * emitted value is one every skip-based layer has seen in its final form. A table
+ * that needs no fixed point runs exactly once, so the cost is paid only by the
+ * ordering that creates the hazard.
+ *
+ * Layers may be `terminal`: run once, after the fixed point, never re-run. That
+ * is Layer 4 (rehydration), whose whole contract is that it sees the FINAL
+ * authored text and its restored secrets are not re-stripped by Layer 3. Terminal
+ * layers must be a suffix of the table, which the driver checks.
+ */
+
+/**
+ * A layer's result: the rewritten input plus the model-facing note, a `deny`
+ * verdict that ends the pipeline, or null when the layer changed nothing.
+ * @typedef {{ updatedInput: any, context: string } | { deny: string } | null} LayerResult
+ */
+
+/**
+ * One declared layer.
+ * - `erases` — may REMOVE code points from a field another layer reads. This is
+ *   the property that can invalidate a skip-based decision taken earlier.
+ * - `skipBased` — its decision can be suppressed by code points present at the
+ *   time it ran. Such a layer must be re-run after any erasure.
+ * - `terminal` — runs once after the fixed point and is never re-run.
+ * @typedef {{
+ *   name: string,
+ *   erases: boolean,
+ *   skipBased: boolean,
+ *   terminal?: boolean,
+ *   run: (tool: string, input: any) => LayerResult | Promise<LayerResult>,
+ * }} Layer
+ */
+
+/**
+ * Bound on fixed-point passes. Each pass either changes the input or ends the
+ * loop, and the layers are contractive in practice (folding and stripping both
+ * shrink the space of remaining findings), so a run that is still changing after
+ * this many passes is a layer that oscillates — a bug. Throwing hands it to the
+ * hook's fail-closed catch, which is the loud outcome; looping forever would be
+ * silently killed by the harness and read as a non-blocking pass (fail OPEN).
+ */
+export const MAX_PIPELINE_PASSES = 8;
+
+/**
+ * Whether `layers` places an erasing layer after a skip-based one — the ordering
+ * whose soundness needs a fixed point. Exported so the property is assertable
+ * about a table directly, not only through a run.
+ * @param {Layer[]} layers
+ * @returns {boolean}
+ */
+export function needsFixedPoint(layers) {
+  let sawSkipBased = false;
+  for (const layer of layers) {
+    if (layer.erases && sawSkipBased) return true;
+    if (layer.skipBased) sawSkipBased = true;
+  }
+  return false;
+}
+
+/**
+ * Run a declared layer chain over one tool input.
+ *
+ * Returns the final input, whether anything changed, and the model-facing notes
+ * in the order they were produced (deduplicated: a fixed-point re-run that
+ * repeats a layer's note would otherwise say the same thing twice). A layer that
+ * denies ends the run immediately, with `deny` set.
+ * @param {string} tool
+ * @param {any} toolInput
+ * @param {Layer[]} layers
+ * @returns {Promise<{ updatedInput: any, changed: boolean, contexts: string[], deny?: string }>}
+ */
+export async function runLayerPipeline(tool, toolInput, layers) {
+  const firstTerminal = layers.findIndex((layer) => layer.terminal === true);
+  const body = firstTerminal === -1 ? layers : layers.slice(0, firstTerminal);
+  const terminal = firstTerminal === -1 ? [] : layers.slice(firstTerminal);
+  // A non-terminal layer after a terminal one would run BEFORE it on the next
+  // pass and after it on this one — an ordering nobody declared. Reject the
+  // table rather than pick an interpretation.
+  if (terminal.some((layer) => layer.terminal !== true))
+    throw new Error("terminal layers must come last in the pipeline table");
+
+  let current = toolInput;
+  let changed = false;
+  /** @type {string[]} */
+  const contexts = [];
+  /** @param {{ updatedInput: any, context: string }} result */
+  const accept = (result) => {
+    current = result.updatedInput;
+    changed = true;
+    if (!contexts.includes(result.context)) contexts.push(result.context);
+  };
+
+  // Only the hazardous ordering pays for convergence: a table with no erasing
+  // layer after a skip-based one runs its single pass and is done, changes or
+  // not — there is no decision left to invalidate.
+  const requireFixedPoint = needsFixedPoint(body);
+  const passes = requireFixedPoint ? MAX_PIPELINE_PASSES : 1;
+  let settled = false;
+  for (let pass = 0; pass < passes && !settled; pass++) {
+    settled = true;
+    for (const layer of body) {
+      const result = await layer.run(tool, current);
+      if (result === null) continue;
+      if ("deny" in result)
+        return { updatedInput: current, changed, contexts, deny: result.deny };
+      accept(result);
+      settled = false;
+    }
+  }
+  if (requireFixedPoint && !settled)
+    throw new Error(
+      `layer pipeline did not reach a fixed point in ${passes} passes; a layer ` +
+        "is undoing another layer's rewrite",
+    );
+
+  for (const layer of terminal) {
+    const result = await layer.run(tool, current);
+    if (result === null) continue;
+    if ("deny" in result)
+      return { updatedInput: current, changed, contexts, deny: result.deny };
+    accept(result);
+  }
+  return { updatedInput: current, changed, contexts };
+}

package/claude-hooks/plugin-hooks.mjs

@@ -20,6 +20,39 @@ import {
   readFlag,
   readStdinJson,
 } from "./lib/hook-io.mjs";
+import {
+  registerFaultPolicy,
+  hookFaultOutcome,
+  writeFaultOutcome,
+} from "./lib/hook-fault.mjs";
+
+const HOOK_NAME = "plugin-hooks";
+
+// The dispatcher's entry in the one posture table (lib/hook-fault.mjs). It
+// answers no single event — it is the binder in front of all four — so it
+// carries no stdout envelope and both arms are process-level.
+//
+// BOTH ARMS BLOCK, and that is the declaration, not an oversight. The
+// AGENT_SANITIZER_FAIL_OPEN knob covers a hook that RAN and broke; an unknown
+// mode is static wiring corruption, which means no hook runs at all, silently,
+// for the life of the install — there is no run to degrade. Stating it here (and
+// pinning it in plugin/test/plugin-bundle.test.mjs) is the point of the table:
+// the arm that ignores the knob does so on the record, next to the four that
+// honor it, instead of by hard-exiting past the question.
+//
+// Exit 2 is the one non-zero code Claude Code treats as BLOCKING: it blocks
+// PreToolUse and UserPromptSubmit, surfaces stderr for PostToolUse, and is
+// harmless for SessionStart.
+const unknownMode = (/** @type {{ message: string }} */ ctx) => ({
+  stderr: `${HOOK_NAME}: ${ctx.message}\n`,
+  exitCode: 2,
+});
+registerFaultPolicy(HOOK_NAME, {
+  event: null,
+  guarded: "hook payload",
+  open: unknownMode,
+  closed: unknownMode,
+});
 
 // The packages the hooks lazy-load, each behind a thunk whose import specifier
 // is a LITERAL — esbuild only inlines `import("…")` it can read statically, so
@@ -114,16 +147,19 @@ export async function main() {
       break;
     }
     default:
-      // An unknown mode means broken hooks.json wiring — fail CLOSED, never fall
-      // through to some default hook and vet the wrong payload class. Exit 2 is
-      // the one non-zero code Claude Code treats as blocking (a plain exit 1 is
-      // a non-blocking hook error that lets the guarded action through
-      // unsanitized); it blocks PreToolUse and UserPromptSubmit, surfaces
-      // stderr for PostToolUse, and is harmless for SessionStart.
-      process.stderr.write(
-        `plugin-hooks: unknown hook mode ${JSON.stringify(mode)}\n`,
+      // An unknown mode means broken hooks.json wiring — never fall through to
+      // some default hook and vet the wrong payload class. WHICH way it fails is
+      // the operator's call, taken through the one posture table like every
+      // other hook fault (this arm used to hard-exit 2 unconditionally, so the
+      // knob an operator set was silently overruled here alone).
+      process.exit(
+        writeFaultOutcome(
+          hookFaultOutcome(
+            HOOK_NAME,
+            new Error(`unknown hook mode ${JSON.stringify(mode)}`),
+          ),
+        ),
       );
-      process.exit(2);
   }
 }
 

package/claude-hooks/pretooluse-sanitize.mjs

@@ -16,7 +16,9 @@
  * BOTH a confusable AND a stego payload had one fix non-deterministically
  * clobbered by the other. Composing them here makes the rewrite deterministic
  * (normalize, then strip the normalized text) and pays a single Node start
- * instead of three on the hottest path.
+ * instead of three on the hottest path. Layers 2-4 run through the declared
+ * pipeline in lib/layer-pipeline.mjs, which is what keeps the confusable fold's
+ * skip decisions sound once the erasing strip follows it.
  *
  * Layers 2 and 4 are the provider-agnostic transforms in the agent-sanitizer
  * package; this file binds its peers (namespace-guard, the redactor daemon, the
@@ -34,11 +36,11 @@ import {
   registeredLazyModule,
   emitHookResponse,
   safeErrMessage,
-  failOpenEnabled,
-  failOpenContext,
   HookEvent,
   PermissionDecision,
 } from "./lib/hook-io.mjs";
+import { registerFaultPolicy, hookFaultOutcome } from "./lib/hook-fault.mjs";
+import { runLayerPipeline } from "./lib/layer-pipeline.mjs";
 import { controlPlane, runJudgeCli } from "./lib/control-plane.mjs";
 import {
   invisibleCharAlert,
@@ -168,6 +170,83 @@ function emitTraced(emitTrace, toolName, fields) {
   return fields;
 }
 
+/**
+ * The declared layer chain, layers 2-4. Every entry states the two properties
+ * the driver reasons about — whether it ERASES code points another layer reads,
+ * and whether its own decision is SKIP-BASED and therefore invalidated by such
+ * an erasure — so the confusable fold's ordering precondition is enforced by the
+ * table instead of restated as a comment.
+ *
+ * Layer 3 is dropped from the table (not merely skipped at run time) when
+ * AGENT_SANITIZER_OUTPUT_DISABLED=1, so the driver sees the chain that will
+ * actually run: with no erasing layer left after the fold there is no fixed
+ * point to reach and no extra pass to pay for.
+ * @param {(tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>} rehydrate
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ * @returns {import("./lib/layer-pipeline.mjs").Layer[]}
+ */
+export function preToolUseLayers(rehydrate, env = process.env) {
+  /** @type {import("./lib/layer-pipeline.mjs").Layer[]} */
+  const layers = [
+    {
+      name: "confusables",
+      // Folding SUBSTITUTES a glyph for its ASCII canon, which drops the
+      // original code point; and it SKIPS any token still holding an unmapped
+      // glyph, which is the decision an erasure can invalidate.
+      erases: true,
+      skipBased: true,
+      run: (tool, toolInput) => {
+        const norm = normalizeConfusables(tool, toolInput, {
+          scan: confusableScan,
+        });
+        return norm === null
+          ? null
+          : {
+              updatedInput: norm.updatedInput,
+              context: normalizeContext(norm.normalized),
+            };
+      },
+    },
+    {
+      name: "authored-content",
+      // Erases payload-capable invisible characters, and skips below the
+      // payload-capable floor — the erasure that broke the fold's precondition.
+      erases: true,
+      skipBased: true,
+      run: (tool, toolInput) => {
+        const authored = sanitizeAuthoredContent(tool, toolInput);
+        return authored === null
+          ? null
+          : {
+              updatedInput: authored.updatedInput,
+              context: authoredContext(authored.changed),
+            };
+      },
+    },
+    {
+      name: "rehydrate",
+      erases: true,
+      skipBased: false,
+      // Terminal by contract, not by luck: it re-anchors Edit/Write inputs onto
+      // the on-disk bytes, and the secrets it restores must NOT be re-stripped
+      // by layer 3 or re-folded by layer 2 on a later pass.
+      terminal: true,
+      run: async (tool, toolInput) => {
+        const rehydrated = await rehydrate(tool, toolInput);
+        if (!rehydrated) return null;
+        if ("deny" in rehydrated) return { deny: rehydrated.deny };
+        return {
+          updatedInput: rehydrated.updatedInput,
+          context: rehydrated.context,
+        };
+      },
+    },
+  ];
+  return env.AGENT_SANITIZER_OUTPUT_DISABLED === "1"
+    ? layers.filter((layer) => layer.name !== "authored-content")
+    : layers;
+}
+
 /**
  * Compose the four protections. Returns the `hookSpecificOutput` fields to
  * emit, or null for a clean no-op. Throws only if a layer's engine throws; the
@@ -207,44 +286,21 @@ export async function buildPreToolUseResponse(
 
   const { tool_name: tool, tool_input: toolInput } = input;
 
-  // Layers 2 then 3, chained: normalize confusables first, then strip authored
-  // stego/terminal-control from the normalized text.
-  let current = toolInput;
-  let changed = false;
-
-  const norm = normalizeConfusables(tool, current, { scan: confusableScan });
-  if (norm) {
-    current = norm.updatedInput;
-    changed = true;
-    contexts.push(normalizeContext(norm.normalized));
-  }
-
-  if (process.env.AGENT_SANITIZER_OUTPUT_DISABLED !== "1") {
-    const authored = sanitizeAuthoredContent(tool, current);
-    if (authored) {
-      current = authored.updatedInput;
-      changed = true;
-      contexts.push(authoredContext(authored.changed));
-    }
-  }
-
-  // Layer 4: re-anchor Edit/Write inputs composed from a sanitized file view
-  // ([REDACTED…] placeholders, stripped invisible characters) back onto the
-  // on-disk bytes. Runs last so it sees the final authored text and its
-  // rehydrated secrets are not re-stripped by layer 3. An unresolvable or
-  // secret-exposing call is denied outright — that verdict outranks any ask
-  // above, so it returns immediately.
-  const rehydrated = await rehydrate(tool, current);
-  if (rehydrated && "deny" in rehydrated)
+  // Layers 2-4, run by the declared pipeline: the driver — not this call order —
+  // is what keeps the confusable fold's soundness precondition true once an
+  // erasing layer follows it (see lib/layer-pipeline.mjs).
+  const {
+    updatedInput: current,
+    changed,
+    contexts: layerContexts,
+    deny,
+  } = await runLayerPipeline(tool, toolInput, preToolUseLayers(rehydrate));
+  if (deny !== undefined)
     return emitTraced(emitTrace, input.tool_name, {
       permissionDecision: PermissionDecision.DENY,
-      permissionDecisionReason: rehydrated.deny,
+      permissionDecisionReason: deny,
     });
-  if (rehydrated) {
-    current = rehydrated.updatedInput;
-    changed = true;
-    contexts.push(rehydrated.context);
-  }
+  contexts.push(...layerContexts);
 
   return emitTraced(
     emitTrace,
@@ -447,11 +503,30 @@ export function failClosedFields(parsedOk, err, opts = {}) {
  * @returns {Record<string, unknown>}
  */
 export function hookFailureFields(parsedOk, err, opts = {}) {
-  if (failOpenEnabled(opts.env))
-    return { additionalContext: failOpenContext(HOOK_NAME, "tool input", err) };
-  return failClosedFields(parsedOk, err, opts);
+  return /** @type {Record<string, unknown>} */ (
+    hookFaultOutcome(HOOK_NAME, err, {
+      parsedOk,
+      env: opts.env,
+      messages: opts.messages,
+      hint: opts.hint,
+    }).fields
+  );
 }
 
+// This hook's entry in the one posture table (lib/hook-fault.mjs). The OPEN arm
+// is the shared default — a warning context and no verdict — so only the CLOSED
+// verdict, which is this hook's own ask/deny split, is stated here.
+registerFaultPolicy(HOOK_NAME, {
+  event: HookEvent.PRE_TOOL_USE,
+  guarded: "tool input",
+  closed: (ctx) => ({
+    fields: failClosedFields(ctx.parsedOk, ctx.err, {
+      messages: ctx.messages,
+      hint: ctx.hint,
+    }),
+  }),
+});
+
 // Stryker disable all: CLI wiring — it runs only in the spawned hook
 // subprocess, never in-process, so every mutant from here down is NoCoverage.
 // The exported judgePreToolUseSanitize and failClosedFields above carry the