agent-sanitizer 2.19.2 → 2.19.4

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

package/claude-hooks/sanitize-output.mjs

@@ -26,15 +26,13 @@ import {
   lazyImport,
   emitHookResponse,
   errMessage,
-  safeErrMessage,
-  failOpenEnabled,
-  failOpenContext,
   makeDeadline,
   lazyImportErrorFor,
   missingPackageMessage,
   DEFAULT_MISSING_PACKAGE_REMEDY,
   HookEvent,
 } from "./lib/hook-io.mjs";
+import { registerFaultPolicy, hookFaultOutcome } from "./lib/hook-fault.mjs";
 import { controlPlane, runJudgeCli } from "./lib/control-plane.mjs";
 import { bestEffortTrace, trace, TraceEvent } from "./lib/trace.mjs";
 import { hasEnvBoundSecret } from "./lib/secret-annotate.mjs";
@@ -552,19 +550,48 @@ export function emitFailClosed(
   message,
   emit = (fields) => emitHookResponse(HookEvent.POST_TOOL_USE, fields),
   remedy = DEFAULT_MISSING_PACKAGE_REMEDY,
+) {
+  const { fields, fallbackFields } = failClosedParts(input, message, remedy);
+  try {
+    emit(fields);
+  } catch {
+    emit(fallbackFields);
+  }
+}
+
+/**
+ * The fail-closed response fields plus the shallow fallback to emit if
+ * serializing them throws. Split out from {@link emitFailClosed} so the posture
+ * table can state this hook's CLOSED verdict as a VALUE — the table is what
+ * `test/claude-hooks-posture.test.mjs` compares each hook's emission against, so
+ * a verdict reachable only by running the emitter could not be pinned there.
+ * @param {any} input  parsed hook input, or undefined if parsing threw
+ * @param {string} message
+ * @param {string} [remedy]  what a reader should run; hosts pass their own
+ * @returns {{ fields: Record<string, unknown>, fallbackFields: Record<string, unknown> }}
+ */
+function failClosedParts(
+  input,
+  message,
+  remedy = DEFAULT_MISSING_PACKAGE_REMEDY,
 ) {
   // Threaded rather than defaulted here: this is the ONLY production caller of
   // failClosedContext, so a remedy it does not pass is a remedy no host can ever
   // reach — the parameter would be live only from tests.
   const additionalContext = failClosedContext(sanitizerDepsLoaded, remedy);
+  const fallbackFields = { updatedToolOutput: message, additionalContext };
+  let updatedToolOutput;
   try {
-    emit({
-      updatedToolOutput: failClosedReplacement(input, message),
-      additionalContext,
-    });
+    updatedToolOutput = failClosedReplacement(input, message);
   } catch {
-    emit({ updatedToolOutput: message, additionalContext });
+    // The shape-matching walk overflowed on a pathologically deep (but valid)
+    // tool_response. The bare string is shallow, always serializable, and still
+    // a valid string tool_response — so the hook stays CLOSED rather than
+    // throwing out of its own failure path, which would emit nothing and let
+    // the harness show the raw, unvetted output.
+    return { fields: fallbackFields, fallbackFields };
   }
+  return { fields: { updatedToolOutput, additionalContext }, fallbackFields };
 }
 
 /**
@@ -595,20 +622,40 @@ export function emitHookFailure(
   remedy = DEFAULT_MISSING_PACKAGE_REMEDY,
   env = process.env,
 ) {
-  if (failOpenEnabled(env)) {
-    emit({
-      additionalContext: failOpenContext("sanitize-output", "tool output", err),
-    });
-    return;
+  const outcome = hookFaultOutcome(HOOK_NAME, err, { input, remedy, env });
+  const fields = /** @type {Record<string, unknown>} */ (outcome.fields);
+  try {
+    emit(fields);
+  } catch (emitErr) {
+    // The open posture's fields are a lone string context — always
+    // serializable — so it declares no fallback, and a throw there is a real
+    // bug the caller must see rather than a suppression to retry.
+    if (outcome.fallbackFields === null) throw emitErr;
+    emit(outcome.fallbackFields);
   }
-  emitFailClosed(
-    input,
-    `[SANITIZATION FAILED — original output suppressed for safety. Hook error: ${safeErrMessage(err)}]`,
-    emit,
-    remedy,
-  );
 }
 
+/**
+ * The suppression placeholder that replaces the tool output under the closed
+ * posture. Named so the posture table and {@link emitFailClosed} cannot drift on
+ * the wording the model sees.
+ * @param {string} cause  the scrubbed hook error
+ * @returns {string}
+ */
+function suppressionMessage(cause) {
+  return `[SANITIZATION FAILED — original output suppressed for safety. Hook error: ${cause}]`;
+}
+
+// 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.
+registerFaultPolicy(HOOK_NAME, {
+  event: HookEvent.POST_TOOL_USE,
+  guarded: "tool output",
+  closed: (ctx) =>
+    failClosedParts(ctx.input, suppressionMessage(ctx.message), ctx.remedy),
+});
+
 /**
  * Run the sanitization pipeline over a tool output and return the contract-
  * shaped verdict fields — `mutated_output` (the shape-matching sanitized value)

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

@@ -20,15 +20,17 @@
  */
 import {
   readStdinJson,
-  safeErrMessage,
-  failOpenEnabled,
-  failOpenContext,
   HookEvent,
   isMain,
   lazyImport,
   missingPackageError,
   DEFAULT_MISSING_PACKAGE_REMEDY,
 } from "./lib/hook-io.mjs";
+import {
+  registerFaultPolicy,
+  hookFaultOutcome,
+  writeFaultOutcome,
+} from "./lib/hook-fault.mjs";
 import { controlPlane, runJudgeCli } from "./lib/control-plane.mjs";
 import { bestEffortTrace, trace, TraceEvent } from "./lib/trace.mjs";
 // classifyPrompt (the user-prompt verdict) and stripAnsiFully (its ANSI stripper)
@@ -73,6 +75,27 @@ export const USER_PROMPT_MESSAGES = Object.freeze({
   remedy: DEFAULT_MISSING_PACKAGE_REMEDY,
 });
 
+const HOOK_NAME = "sanitize-user-prompt";
+
+// This hook's entry in the one posture table (lib/hook-fault.mjs). OPEN is the
+// shared default (a warning context alongside the prompt); CLOSED is a
+// top-level `decision: "block"`, NOT a hookSpecificOutput verdict —
+// UserPromptSubmit has no permissionDecision channel, so this envelope shape is
+// the gate's own and the table records it rather than a reader inferring it.
+registerFaultPolicy(HOOK_NAME, {
+  event: HookEvent.USER_PROMPT_SUBMIT,
+  guarded: "prompt",
+  closed: (ctx) => ({
+    envelope: {
+      decision: "block",
+      reason: {
+        ...USER_PROMPT_MESSAGES,
+        ...ctx.messages,
+      }.hookFailed(ctx.message),
+    },
+  }),
+});
+
 /* c8 ignore start — module-load boundary: the imports resolve in every real
  * run, and their failure (the package absent) can't be simulated in-process, so
  * neither arm is observable to the in-process tests. The judge's typeof guard
@@ -202,13 +225,13 @@ export async function main(read, write, opts = {}) {
   // exactly what may have failed to load. Either way this is the HOOK failing;
   // a prompt the working stripper flagged is still blocked in both postures.
   await runJudgeCli(
-    "sanitize-user-prompt",
+    HOOK_NAME,
     (event) => {
       const verdict = judgeSanitizeUserPrompt(event, strip, messages);
       // Announce engagement on the trace channel like the other stdin hooks —
       // a prompt gate that silently stopped running is otherwise invisible.
       emitTrace(TraceEvent.HOOK_RAN, {
-        hook: "sanitize-user-prompt",
+        hook: HOOK_NAME,
         outcome:
           verdict.decision === controlPlane().Decision.DENY
             ? "deny"
@@ -222,24 +245,9 @@ export async function main(read, write, opts = {}) {
       readInput: read,
       write,
       onError: (err) =>
-        write(
-          JSON.stringify(
-            failOpenEnabled(env)
-              ? {
-                  hookSpecificOutput: {
-                    hookEventName: HookEvent.USER_PROMPT_SUBMIT,
-                    additionalContext: failOpenContext(
-                      "sanitize-user-prompt",
-                      "prompt",
-                      err,
-                    ),
-                  },
-                }
-              : {
-                  decision: "block",
-                  reason: messages.hookFailed(safeErrMessage(err)),
-                },
-          ),
+        writeFaultOutcome(
+          hookFaultOutcome(HOOK_NAME, err, { messages, env }),
+          write,
         ),
     },
   );