agent-sanitizer 2.33.1 → 2.34.0

package/README.md

@@ -16,6 +16,7 @@ npm install agent-sanitizer
 **As a Claude Code plugin:**
 
 Enter one at a time:
+
 ```
 /plugin marketplace add AlexanderMattTurner/agent-sanitizer
 ```
@@ -23,6 +24,7 @@ Enter one at a time:
 ```
 /plugin install agent-sanitizer@agent-sanitizer
 ```
+
 ```
 /agent-sanitizer:enable-auto-update
 ```

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

@@ -242,6 +242,50 @@ export function failOpenEnabled(env = process.env) {
   return !FAIL_CLOSED_SET.has(env[FAIL_OPEN_ENV] ?? "");
 }
 
+/**
+ * The public knob that turns individual hooks off: a comma-separated list of
+ * hook names (the `--hook=` modes). The layer opt-outs
+ * (`AGENT_SANITIZER_*_DISABLED`) narrow what a hook rewrites; this one is for
+ * the deployment that wants a whole event unguarded — a session whose prompts
+ * legitimately carry escape sequences, or one where the SessionStart context
+ * scan is redundant because the instruction files are already vetted upstream.
+ * Without it the only way to drop one hook is to edit the shipped hooks.json,
+ * which the next plugin update overwrites.
+ */
+export const DISABLED_HOOKS_ENV = "AGENT_SANITIZER_DISABLED_HOOKS";
+
+/**
+ * The hook names an operator switched off, restricted to `known`.
+ *
+ * An unrecognized name is REPORTED and dropped rather than thrown on, and the
+ * direction of that choice is the point: this variable is set outside the
+ * session, so a throw here — or a blocking verdict — would leave every tool
+ * call failing on a config value the session cannot edit. Dropping it keeps the
+ * named hook running, which is the safe side, and `report` is what stops it
+ * being silent.
+ * @param {readonly string[]} known  every dispatchable hook name
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ * @param {(message: string) => void} [report]
+ * @returns {Set<string>}
+ */
+export function disabledHooks(
+  known,
+  env = process.env,
+  report = (message) => process.stderr.write(`${message}\n`),
+) {
+  const named = (env[DISABLED_HOOKS_ENV] ?? "")
+    .split(",")
+    .map((name) => name.trim())
+    .filter((name) => name !== "");
+  const unknown = named.filter((name) => !known.includes(name));
+  if (unknown.length > 0)
+    report(
+      `agent-sanitizer: ${DISABLED_HOOKS_ENV} names ${unknown.join(", ")}, ` +
+        `which is not a hook — it stays ENABLED. Known hooks: ${known.join(", ")}.`,
+    );
+  return new Set(named.filter((name) => known.includes(name)));
+}
+
 /**
  * The model-facing warning accompanying a fail-open pass-through. Emitted as
  * `additionalContext` so the transcript still carries the failure: the posture

package/claude-hooks/plugin-hooks.mjs

@@ -15,6 +15,10 @@
  */
 import {
   claimCliEntry,
+  disabledHooks,
+  DISABLED_HOOKS_ENV,
+  emitHookResponse,
+  HookEvent,
   isMain,
   registerLazyModules,
   readFlag,
@@ -102,67 +106,115 @@ async function registerAvailableModules() {
 }
 
 /**
- * Dispatch to the hook named by `--hook=<name>` in argv. Exported and guarded by
- * isMain below so importing this module (the published entry point) is a no-op:
- * only a direct `node plugin-hooks.mjs --hook=…` run consumes stdin and exits.
- * @returns {Promise<void>}
+ * Every dispatchable hook: its Claude Code event, and the loader that runs it.
+ *
+ * A table rather than a switch because the mode NAMES are read three ways — the
+ * dispatch, the {@link DISABLED_HOOKS_ENV} validation, and the tests that check
+ * hooks.json wires exactly these — and each hand-written copy is one that can
+ * drift into naming a hook nothing dispatches. The event is here because a
+ * disabled hook still has to answer in its own event's envelope.
+ *
+ * Each module is loaded through a LITERAL dynamic import: esbuild inlines only
+ * what it can read statically, so a computed specifier would survive into the
+ * bundle as a runtime dial against a node_modules the plugin does not ship.
+ * @type {Record<string, { event: string, run: () => Promise<void> }>}
  */
-export async function main() {
-  // This binder owns the process's CLI entry: inside the bundle every inlined
-  // module shares this file's import.meta.url, so without the claim the inlined
-  // hooks' own isMain-guarded CLIs would also fire and consume stdin.
-  claimCliEntry();
-  await registerAvailableModules();
-
-  const mode = readFlag(process.argv, "hook");
-  switch (mode) {
-    case "pretooluse-sanitize": {
+const HOOKS = {
+  "pretooluse-sanitize": {
+    event: HookEvent.PRE_TOOL_USE,
+    run: async () => {
       const { cliMain } =
         /** @type {typeof import("./pretooluse-sanitize.mjs")} */ (
           await import("./pretooluse-sanitize.mjs")
         );
       await cliMain();
-      break;
-    }
-    case "sanitize-output": {
+    },
+  },
+  "sanitize-output": {
+    event: HookEvent.POST_TOOL_USE,
+    run: async () => {
       const { cliMain } =
         /** @type {typeof import("./sanitize-output.mjs")} */ (
           await import("./sanitize-output.mjs")
         );
       await cliMain();
-      break;
-    }
-    case "sanitize-user-prompt": {
+    },
+  },
+  "sanitize-user-prompt": {
+    event: HookEvent.USER_PROMPT_SUBMIT,
+    run: async () => {
       const { main: promptMain } =
         /** @type {typeof import("./sanitize-user-prompt.mjs")} */ (
           await import("./sanitize-user-prompt.mjs")
         );
       await promptMain(readStdinJson, (chunk) => process.stdout.write(chunk));
-      break;
-    }
-    case "scan-invisible-chars": {
+    },
+  },
+  "scan-invisible-chars": {
+    event: HookEvent.SESSION_START,
+    run: async () => {
       const { cliMain } =
         /** @type {typeof import("./scan-invisible-chars.mjs")} */ (
           await import("./scan-invisible-chars.mjs")
         );
       await cliMain();
-      break;
-    }
-    default:
-      // 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)}`),
-          ),
+    },
+  },
+};
+
+/** The dispatchable hook names, in hooks.json's spelling. */
+export const HOOK_MODES = Object.freeze(Object.keys(HOOKS));
+
+/**
+ * Dispatch to the hook named by `--hook=<name>` in argv. Exported and guarded by
+ * isMain below so importing this module (the published entry point) is a no-op:
+ * only a direct `node plugin-hooks.mjs --hook=…` run consumes stdin and exits.
+ * @returns {Promise<void>}
+ */
+export async function main() {
+  // This binder owns the process's CLI entry: inside the bundle every inlined
+  // module shares this file's import.meta.url, so without the claim the inlined
+  // hooks' own isMain-guarded CLIs would also fire and consume stdin.
+  claimCliEntry();
+  await registerAvailableModules();
+
+  const mode = readFlag(process.argv, "hook");
+  const hook = mode === undefined ? undefined : HOOKS[mode];
+  if (mode === undefined || hook === undefined) {
+    // 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.
+    process.exit(
+      writeFaultOutcome(
+        hookFaultOutcome(
+          HOOK_NAME,
+          new Error(`unknown hook mode ${JSON.stringify(mode)}`),
         ),
-      );
+      ),
+    );
+  }
+
+  // An empty envelope is a verdict, not a crash: stdout stays non-empty, so the
+  // launcher's post-condition sees an answer and Claude Code records a clean
+  // run rather than a hook error. The operator asked for this hook not to
+  // guard, so there is nothing to warn the MODEL about — the stderr line is
+  // where an operator finds out which hooks are off.
+  if (disabledHooks(HOOK_MODES).has(mode)) {
+    process.stderr.write(
+      `agent-sanitizer: ${mode} is off via ${DISABLED_HOOKS_ENV}; this ` +
+        `${hook.event} event is UNGUARDED.\n`,
+    );
+    emitHookResponse(hook.event, {});
+    // Every other hook reads the payload to EOF. Exiting without doing so
+    // leaves Claude Code writing into a closed pipe — an EPIPE on the harness
+    // side for any payload past the pipe buffer, which is most of them.
+    // `resume()` with no data listener consumes and discards.
+    process.stdin.resume();
+    return;
   }
+
+  await hook.run();
 }
 
 // isMain is read BEFORE main() claims the CLI slot (the claim makes every later

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.33.1",
+  "version": "2.34.0",
   "description": "Defend an agent against hidden-content injection: strip payload-capable invisible Unicode and ANSI, splice out human-invisible HTML, and flag data-exfil URLs in untrusted text before any model sees it.",
   "type": "module",
   "repository": {

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

@@ -85,6 +85,21 @@ export function readFlag(argv: string[], name: string): string | undefined;
  * @returns {boolean}
  */
 export function failOpenEnabled(env?: NodeJS.ProcessEnv | Record<string, string | undefined>): boolean;
+/**
+ * The hook names an operator switched off, restricted to `known`.
+ *
+ * An unrecognized name is REPORTED and dropped rather than thrown on, and the
+ * direction of that choice is the point: this variable is set outside the
+ * session, so a throw here — or a blocking verdict — would leave every tool
+ * call failing on a config value the session cannot edit. Dropping it keeps the
+ * named hook running, which is the safe side, and `report` is what stops it
+ * being silent.
+ * @param {readonly string[]} known  every dispatchable hook name
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ * @param {(message: string) => void} [report]
+ * @returns {Set<string>}
+ */
+export function disabledHooks(known: readonly string[], env?: NodeJS.ProcessEnv | Record<string, string | undefined>, report?: (message: string) => void): Set<string>;
 /**
  * The model-facing warning accompanying a fail-open pass-through. Emitted as
  * `additionalContext` so the transcript still carries the failure: the posture
@@ -443,6 +458,17 @@ export const FAIL_OPEN_ENV: "AGENT_SANITIZER_FAIL_OPEN";
  * tests/test_safe_launch.py.
  */
 export const FAIL_CLOSED_VALUES: readonly string[];
+/**
+ * The public knob that turns individual hooks off: a comma-separated list of
+ * hook names (the `--hook=` modes). The layer opt-outs
+ * (`AGENT_SANITIZER_*_DISABLED`) narrow what a hook rewrites; this one is for
+ * the deployment that wants a whole event unguarded — a session whose prompts
+ * legitimately carry escape sequences, or one where the SessionStart context
+ * scan is redundant because the instruction files are already vetted upstream.
+ * Without it the only way to drop one hook is to edit the shipped hooks.json,
+ * which the next plugin update overwrites.
+ */
+export const DISABLED_HOOKS_ENV: "AGENT_SANITIZER_DISABLED_HOOKS";
 /**
  * Hard cap on hook stdin. A well-formed Claude Code hook payload is at most a
  * few MB (tool input plus the harness-truncated tool output); 64 MiB leaves

package/types/claude-hooks/plugin-hooks.d.mts

@@ -5,3 +5,5 @@
  * @returns {Promise<void>}
  */
 export function main(): Promise<void>;
+/** The dispatchable hook names, in hooks.json's spelling. */
+export const HOOK_MODES: readonly string[];