agent-sanitizer 2.9.0 → 2.9.1

package/claude-hooks/plugin-hooks.mjs

@@ -34,6 +34,7 @@ const LAZY_LOADERS = {
   "agent-sanitizer/confusables": () => import("agent-sanitizer/confusables"),
   "agent-sanitizer/invisible": () => import("agent-sanitizer/invisible"),
   "agent-sanitizer/output": () => import("agent-sanitizer/output"),
+  "agent-sanitizer/prompt": () => import("agent-sanitizer/prompt"),
   "agent-sanitizer/rehydrate": () => import("agent-sanitizer/rehydrate"),
   "namespace-guard": () => import("namespace-guard"),
 };

package/claude-hooks/pretooluse-sanitize.mjs

@@ -72,6 +72,7 @@ const HOOK_NAME = "pretooluse-sanitize";
  *   unknownEvent: string,
  *   failed: (cause: string) => string,
  *   unparsable: (cause: string) => string,
+ *   remedy: string,
  * }>}
  */
 export const PRE_TOOL_USE_MESSAGES = Object.freeze({
@@ -79,6 +80,11 @@ export const PRE_TOOL_USE_MESSAGES = Object.freeze({
     "PreToolUse sanitization blocked (fail-closed): unrecognized hook payload.",
   failed: (cause) => `PreToolUse sanitization failed (fail-closed): ${cause}`,
   unparsable: (cause) => `PreToolUse input unparsable (fail-closed): ${cause}`,
+  // What a reader should run when a dependency is what is missing. It rides in
+  // this table rather than a separate argument because it is host text exactly
+  // like the reasons above, and one channel means a host cannot supply its
+  // wording in one place and forget it in the other.
+  remedy: DEFAULT_MISSING_PACKAGE_REMEDY,
 });
 
 // Layers 2 & 4 come from the agent-sanitizer package, bound via lazyImport (see
@@ -413,12 +419,11 @@ export function failClosedFields(parsedOk, err, opts = {}) {
  * @param {{
  *   messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>,
  *   gates?: HostGate[],
- *   remedy?: string,
  * }} [opts]
  * @returns {Promise<void>}
  */
 export async function cliMain(opts = {}) {
-  const { gates = [], remedy } = opts;
+  const { gates = [] } = opts;
   const messages = { ...PRE_TOOL_USE_MESSAGES, ...opts.messages };
   await runJudgeCli(
     HOOK_NAME,
@@ -434,7 +439,7 @@ export async function cliMain(opts = {}) {
           HookEvent.PRE_TOOL_USE,
           failClosedFields(input !== undefined, err, {
             messages,
-            hint: depLoadHint(err, remedy),
+            hint: depLoadHint(err, messages.remedy),
           }),
         ),
     },

package/claude-hooks/sanitize-output.mjs

@@ -195,6 +195,11 @@ async function redactSecrets(text, webIngress = false, deadline) {
  * @property {(record: { tool: string | null, modified: boolean, output: unknown, context?: string }) => Promise<void> | void} [audit]
  *   Awaited once per judged event that carried a tool response, with the output
  *   the model will actually see.
+ * @property {string} [remedy]
+ *   What a reader should run when the sanitizer's own bindings are what is
+ *   missing. This hook's host channel is `ext`, where the other two gates use a
+ *   frozen message table; either way it is one channel per gate, so a host
+ *   cannot supply its wording somewhere the fail-closed context never reads.
  */
 
 /**
@@ -528,14 +533,19 @@ export function failClosedContext(
  * @param {any} input  parsed hook input, or undefined if parsing threw
  * @param {string} message
  * @param {(fields: Record<string, unknown>) => void} [emit]
+ * @param {string} [remedy]  what a reader should run; hosts pass their own
  * @returns {void}
  */
 export function emitFailClosed(
   input,
   message,
   emit = (fields) => emitHookResponse(HookEvent.POST_TOOL_USE, fields),
+  remedy = DEFAULT_MISSING_PACKAGE_REMEDY,
 ) {
-  const additionalContext = failClosedContext();
+  // 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);
   try {
     emit({
       updatedToolOutput: failClosedReplacement(input, message),
@@ -774,6 +784,8 @@ export async function cliMain(ext = {}) {
           "[SANITIZATION FAILED — original output suppressed for safety. Hook error: " +
             safeErrMessage(err) +
             "]",
+          undefined,
+          ext.remedy,
         ),
     },
   );

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

@@ -22,7 +22,9 @@ import {
   readStdinJson,
   safeErrMessage,
   isMain,
+  lazyImport,
   missingPackageError,
+  DEFAULT_MISSING_PACKAGE_REMEDY,
 } from "./lib/hook-io.mjs";
 import { controlPlane, runJudgeCli } from "./lib/control-plane.mjs";
 import { trace, TraceEvent } from "./lib/trace.mjs";
@@ -31,8 +33,9 @@ import { trace, TraceEvent } from "./lib/trace.mjs";
 // import, never a bare top-level `import … from "…"`: a static npm import
 // resolves before any try/catch, so a missing node_modules would crash this hook
 // at load and let the prompt through UNSANITIZED (fail-open). A failed load
-// leaves the bindings undefined, which main()'s typeof guard turns into a
-// fail-closed block.
+// leaves that binding undefined, which the judge's typeof guards turn into a
+// fail-closed block — one guard each, since the two loads succeed or fail
+// independently.
 /** @type {typeof import("agent-sanitizer/prompt").classifyPrompt} */
 export let classifyPrompt;
 /** @type {typeof import("agent-sanitizer").stripAnsiFully} */
@@ -49,6 +52,7 @@ let stripAnsiFully;
  *   blockContext: string,
  *   sgrNote: string,
  *   hookFailed: (cause: string) => string,
+ *   remedy: string,
  * }>}
  */
 export const USER_PROMPT_MESSAGES = Object.freeze({
@@ -59,24 +63,31 @@ export const USER_PROMPT_MESSAGES = Object.freeze({
     "The prompt contains ANSI SGR color codes (pasted terminal output). They are display-only formatting noise; read through them.",
   hookFailed: (cause) =>
     `sanitize-user-prompt hook failed (fail-closed): ${cause}`,
+  // What a reader should run when the package itself is what is missing. It
+  // rides in this table rather than a separate argument because it is host text
+  // exactly like the reasons above, and one channel means a host cannot supply
+  // its wording in one place and forget it in the other.
+  remedy: DEFAULT_MISSING_PACKAGE_REMEDY,
 });
 
 /* 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. main()'s typeof guard
+ * neither arm is observable to the in-process tests. The judge's typeof guard
  * converts an undefined stripper into a fail-closed block — that guard IS tested. */
 // Stryker disable all
-try {
-  // The /prompt subpath is imported first: if it fails, the catch fires before
-  // stripAnsiFully is assigned, so a half-load can never leave the stripper set
-  // while the classifier is missing (main guards on the stripper alone).
-  ({ classifyPrompt } = await import("agent-sanitizer/prompt"));
-  ({ stripAnsiFully } = await import("agent-sanitizer"));
-} catch {
-  // Leave classifyPrompt/stripAnsiFully undefined so main()'s typeof guard fails
-  // closed — the prompt is blocked, never passed through with the package
-  // half-loaded.
-}
+// lazyImport rather than a bare `await import` in a try/catch: it RECORDS the
+// loader error, which is the only thing that can tell a missing install apart
+// from a present package missing an export. Discarding it leaves
+// missingPackageError with nothing to report but a guess.
+// The cast asserts the loaded SHAPE, not that it loaded: lazyImport yields {} on
+// failure, so either binding can still be undefined here — which is exactly what
+// the judge's typeof guard turns into a fail-closed block.
+({ classifyPrompt } = /** @type {typeof import("agent-sanitizer/prompt")} */ (
+  await lazyImport("agent-sanitizer/prompt")
+));
+({ stripAnsiFully } = /** @type {typeof import("agent-sanitizer")} */ (
+  await lazyImport("agent-sanitizer")
+));
 // Stryker restore all
 /* c8 ignore stop */
 
@@ -114,11 +125,21 @@ export function judgeSanitizeUserPrompt(
     return { decision: Decision.DENY, reason: messages.unknownEvent };
   if (event.event !== EventKind.PROMPT_SUBMIT)
     return { decision: Decision.ALLOW };
-  // The module-load guard: a missing stripper means agent-sanitizer never
-  // loaded. Guarding on the stripper alone is sufficient — it loads AFTER
-  // classifyPrompt in the same try, so a present stripper proves the classifier
-  // loaded too.
-  if (typeof strip !== "function") throw missingPackageError("agent-sanitizer");
+  // The module-load guard, one arm per binding. The two lazyImports are
+  // INDEPENDENT — each yields {} on its own failure — so a present stripper does
+  // not prove the classifier loaded, and guarding on it alone would let a
+  // classifier-only failure reach `classifyPrompt(...)` as a bare TypeError
+  // naming no package, no cause and no remedy: the exact diagnostic this hook
+  // now exists to produce. lazyImportErrorFor matches subpaths, so naming
+  // `agent-sanitizer/prompt` still recovers the recorded cause.
+  if (typeof strip !== "function")
+    throw missingPackageError("agent-sanitizer", undefined, messages.remedy);
+  if (typeof classifyPrompt !== "function")
+    throw missingPackageError(
+      "agent-sanitizer/prompt",
+      undefined,
+      messages.remedy,
+    );
   // The contract guarantees a string here: every adapter normalizes the
   // prompt-submit input (Claude's parse coerces a missing/non-string prompt to
   // "" via asString), so a defensive typeof re-check is a dead branch.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.9.0",
+  "version": "2.9.1",
   "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/pretooluse-sanitize.d.mts

@@ -67,14 +67,12 @@ export function failClosedFields(parsedOk: boolean, err: unknown, opts?: {
  * @param {{
  *   messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>,
  *   gates?: HostGate[],
- *   remedy?: string,
  * }} [opts]
  * @returns {Promise<void>}
  */
 export function cliMain(opts?: {
     messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>;
     gates?: HostGate[];
-    remedy?: string;
 }): Promise<void>;
 /**
  * A host-supplied deny gate: given the PreToolUse input, the reason this call
@@ -93,12 +91,14 @@ export function cliMain(opts?: {
  *   unknownEvent: string,
  *   failed: (cause: string) => string,
  *   unparsable: (cause: string) => string,
+ *   remedy: string,
  * }>}
  */
 export const PRE_TOOL_USE_MESSAGES: Readonly<{
     unknownEvent: string;
     failed: (cause: string) => string;
     unparsable: (cause: string) => string;
+    remedy: string;
 }>;
 /**
  * A host-supplied deny gate: given the PreToolUse input, the reason this call

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

@@ -30,6 +30,11 @@
  * @property {(record: { tool: string | null, modified: boolean, output: unknown, context?: string }) => Promise<void> | void} [audit]
  *   Awaited once per judged event that carried a tool response, with the output
  *   the model will actually see.
+ * @property {string} [remedy]
+ *   What a reader should run when the sanitizer's own bindings are what is
+ *   missing. This hook's host channel is `ext`, where the other two gates use a
+ *   frozen message table; either way it is one channel per gate, so a host
+ *   cannot supply its wording somewhere the fail-closed context never reads.
  */
 /**
  * Run Layers 1-4 over a single text blob, delegated to the package's output seam
@@ -142,9 +147,10 @@ export function failClosedContext(depsLoaded?: () => boolean, remedy?: string):
  * @param {any} input  parsed hook input, or undefined if parsing threw
  * @param {string} message
  * @param {(fields: Record<string, unknown>) => void} [emit]
+ * @param {string} [remedy]  what a reader should run; hosts pass their own
  * @returns {void}
  */
-export function emitFailClosed(input: any, message: string, emit?: (fields: Record<string, unknown>) => void): void;
+export function emitFailClosed(input: any, message: string, emit?: (fields: Record<string, unknown>) => void, remedy?: string): void;
 /**
  * Run the sanitization pipeline over a tool output and return the contract-
  * shaped verdict fields — `mutated_output` (the shape-matching sanitized value)
@@ -266,4 +272,11 @@ export type SanitizeExtensions = {
         output: unknown;
         context?: string;
     }) => Promise<void> | void) | undefined;
+    /**
+     * What a reader should run when the sanitizer's own bindings are what is
+     * missing. This hook's host channel is `ext`, where the other two gates use a
+     * frozen message table; either way it is one channel per gate, so a host
+     * cannot supply its wording somewhere the fail-closed context never reads.
+     */
+    remedy?: string | undefined;
 };

package/types/claude-hooks/sanitize-user-prompt.d.mts

@@ -36,6 +36,7 @@ export let classifyPrompt: typeof import("agent-sanitizer/prompt").classifyPromp
  *   blockContext: string,
  *   sgrNote: string,
  *   hookFailed: (cause: string) => string,
+ *   remedy: string,
  * }>}
  */
 export const USER_PROMPT_MESSAGES: Readonly<{
@@ -43,4 +44,5 @@ export const USER_PROMPT_MESSAGES: Readonly<{
     blockContext: string;
     sgrNote: string;
     hookFailed: (cause: string) => string;
+    remedy: string;
 }>;