agent-sanitizer 2.19.2 → 2.19.4

package/README.md

@@ -94,6 +94,11 @@ owns each message, and any value outside the enum makes `sanitizeText` **throw**
 | `filter-flagged`      | The filter flagged the output as a possible injection without deleting (content intact) |
 | `filter-error`        | The filter reported a non-fatal internal error while scanning (a fatal filter throws)   |
 
+Every span is matched against the **original** text and the deletions applied in
+a single ordered pass, so the bytes a filter can remove are exactly the bytes its
+spans matched in the input — an earlier deletion can never manufacture a match
+for a later span (overlapping spans resolve first-match-wins).
+
 ## What installing entails
 
 Installing the plugin puts four hooks on every session, and this is what they

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
@@ -169,8 +181,12 @@ fail-closed path: a redactor that throws makes the pipeline rethrow, so the
 caller suppresses the output rather than emit an unvetted value. Layer 5 is a
 deliberately thin, safe slot: the injected filter returns **verbatim spans to
 delete** (never replacement text), so even a compromised filter can only remove
-legitimate content—it can never inject bytes into the model’s view. A live
-second-LLM injection filter is the caller’s to wire behind that contract.
+legitimate content—it can never inject bytes into the model’s view. That removal
+is bounded to the spans the filter actually named: every span is matched against
+the **original** text and the deletions applied in a single ordered pass, so an
+earlier deletion cannot join two kept regions into a match for a later span and
+erase text neither span occurred in. A live second-LLM injection filter is the
+caller’s to wire behind that contract.
 
 The same "never inject" property governs the filter’s `warning`: it is a
 **closed enum code** (`FILTER_WARNING`: `spans-removed` / `filter-flagged` /

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);
   }
 }