agent-sanitizer 2.8.0 → 2.9.1

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

@@ -19,9 +19,29 @@ export function buildPreToolUseResponse(input: any, rehydrate?: (tool: string, t
  * fail-closed posture holds even when the adapter never loaded.
  * @param {import("agent-control-plane-core").ToolCallEvent} event
  * @param {(tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>} [rehydrate]
+ * @param {{ messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>, gates?: HostGate[] }} [opts]
+ *   messages are merged over the defaults, so a partial table is supported
  * @returns {Promise<import("agent-control-plane-core").Verdict>}
  */
-export function judgePreToolUseSanitize(event: import("agent-control-plane-core").ToolCallEvent, rehydrate?: (tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>): Promise<import("agent-control-plane-core").Verdict>;
+export function judgePreToolUseSanitize(event: import("agent-control-plane-core").ToolCallEvent, rehydrate?: (tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>, opts?: {
+    messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>;
+    gates?: HostGate[];
+}): Promise<import("agent-control-plane-core").Verdict>;
+/**
+ * The dependency-load failure hiding behind a hook error, or "". A binding that
+ * never loaded surfaces at use time as a bare TypeError ("X is not a function")
+ * that names neither the package nor the remedy; when any lazily-loaded package
+ * has a recorded load error, name it — the failed set is derived from the
+ * loader's own records, so a future dependency is covered without editing a list
+ * here. An error already reporting a missing package (missingPackageError's
+ * `DEP_UNAVAILABLE` tag) gets no second copy.
+ * @param {unknown} err
+ * @param {string} [remedy]  what a reader should run; hosts pass their own
+ * @param {() => string[]} [failedPackages]
+ * @param {(pkg: string) => unknown} [loadErrorFor]
+ * @returns {string}
+ */
+export function depLoadHint(err: unknown, remedy?: string, failedPackages?: () => string[], loadErrorFor?: (pkg: string) => unknown): string;
 /**
  * The fail-closed hookSpecificOutput fields for a hook-level failure, chosen by
  * WHICH failure it was. Corrupt/unparsable INPUT (`parsedOk` false — a JSON parse
@@ -32,16 +52,64 @@ export function judgePreToolUseSanitize(event: import("agent-control-plane-core"
  * so it ASKS to keep a human in the loop rather than hard-block on infrastructure.
  * @param {boolean} parsedOk whether the input parsed before the failure
  * @param {unknown} err
+ * @param {{ messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>, hint?: string }} [opts]
  * @returns {Record<string, unknown>}
  */
-export function failClosedFields(parsedOk: boolean, err: unknown): Record<string, unknown>;
+export function failClosedFields(parsedOk: boolean, err: unknown, opts?: {
+    messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>;
+    hint?: string;
+}): Record<string, unknown>;
 /**
  * The hook's CLI: parse → judge → render, with this hook's fail-closed posture.
  * Exported so a bundle entry (which must claim the CLI slot before this module
  * loads) can run the exact same wiring instead of duplicating the onError
  * posture.
+ * @param {{
+ *   messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>,
+ *   gates?: HostGate[],
+ * }} [opts]
  * @returns {Promise<void>}
  */
-export function cliMain(): Promise<void>;
+export function cliMain(opts?: {
+    messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>;
+    gates?: HostGate[];
+}): Promise<void>;
+/**
+ * A host-supplied deny gate: given the PreToolUse input, the reason this call
+ * must be blocked, or null to let the pipeline continue. Hosts use these for
+ * policy the package has no view of (a required workflow step, a project-local
+ * rule); the package ships none.
+ * @typedef {(input: { tool_name: string | null, tool_input: any, session_id?: string })
+ *   => string | null | undefined} HostGate
+ */
+/**
+ * The reasons this hook emits, as a table a host overrides. A host that knows
+ * which of ITS files wires the adapter, and what a reader should do about a
+ * failure, can say so — the package cannot, since it has no idea where it is
+ * installed.
+ * @type {Readonly<{
+ *   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
+ * must be blocked, or null to let the pipeline continue. Hosts use these for
+ * policy the package has no view of (a required workflow step, a project-local
+ * rule); the package ships none.
+ */
+export type HostGate = (input: {
+    tool_name: string | null;
+    tool_input: any;
+    session_id?: string;
+}) => string | null | undefined;
 declare const rehydrateRedacted: typeof import("agent-sanitizer/rehydrate").rehydrateRedacted;
 export {};

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
@@ -118,12 +123,17 @@ export function failClosedReplacement(input: any, message: string): any;
  */
 export function sanitizerDepsLoaded(): boolean;
 /**
- * The model-facing note for a fail-closed emission, with the missing-dependency
- * remedy appended when the sanitizer's bindings are the thing that is absent.
+ * The model-facing note for a fail-closed emission. When the sanitizer's own
+ * bindings are what is absent — a broken INSTALL rather than a broken hook, and
+ * otherwise invisible because every later tool call then fails closed with no
+ * stated cause — the recorded loader error and its remedy ride along. The text
+ * comes from missingPackageMessage so this hook, the PreToolUse gate and the
+ * prompt gate cannot drift apart on what a missing dependency reads like.
  * @param {() => boolean} [depsLoaded]  injectable seam for testing
+ * @param {string} [remedy]  what a reader should run; hosts pass their own
  * @returns {string}
  */
-export function failClosedContext(depsLoaded?: () => boolean): string;
+export function failClosedContext(depsLoaded?: () => boolean, remedy?: string): string;
 /**
  * Emit a fail-closed PostToolUse response, robust to the suppression itself
  * throwing. The shape-matching replacement walks `input.tool_response` and the
@@ -137,9 +147,10 @@ export function failClosedContext(depsLoaded?: () => boolean): 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)
@@ -261,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

@@ -8,16 +8,41 @@
  * @param {import("agent-control-plane-core").ToolCallEvent} event
  * @param {((s: string) => string) | null} [strip]  the ANSI stripper (defaults
  *   to the package's stripAnsiFully; injectable so the fail-closed path is testable)
+ * @param {Partial<typeof USER_PROMPT_MESSAGES>} [overrides]  reason overrides,
+ *   merged over the defaults so a partial table can never leave a field unset
  * @returns {import("agent-control-plane-core").Verdict}
  */
-export function judgeSanitizeUserPrompt(event: import("agent-control-plane-core").ToolCallEvent, strip?: ((s: string) => string) | null): import("agent-control-plane-core").Verdict;
+export function judgeSanitizeUserPrompt(event: import("agent-control-plane-core").ToolCallEvent, strip?: ((s: string) => string) | null, overrides?: Partial<typeof USER_PROMPT_MESSAGES>): import("agent-control-plane-core").Verdict;
 /**
  * @param {() => Promise<any> | any} read
  * @param {(chunk: string) => void} write
  * @param {((s: string) => string) | null} [strip]  the ANSI stripper (defaults
  *   to the package's stripAnsiFully; injectable so the fail-closed path is testable)
+ * @param {Partial<typeof USER_PROMPT_MESSAGES>} [overrides]  reason overrides,
+ *   merged over the defaults so a partial table can never leave a field unset
  * @returns {Promise<void>}
  */
-export function main(read: () => Promise<any> | any, write: (chunk: string) => void, strip?: ((s: string) => string) | null): Promise<void>;
+export function main(read: () => Promise<any> | any, write: (chunk: string) => void, strip?: ((s: string) => string) | null, overrides?: Partial<typeof USER_PROMPT_MESSAGES>): Promise<void>;
 /** @type {typeof import("agent-sanitizer/prompt").classifyPrompt} */
 export let classifyPrompt: typeof import("agent-sanitizer/prompt").classifyPrompt;
+/**
+ * The reasons this gate emits, as a table a host overrides. A host that knows
+ * which of ITS files wires the adapter, and what a reader should do about a
+ * failure, can say so — the package cannot, since it has no idea where it is
+ * installed. Every field is a plain string or a string-returning function, so
+ * an override is auditable next to the default it replaces.
+ * @type {Readonly<{
+ *   unknownEvent: string,
+ *   blockContext: string,
+ *   sgrNote: string,
+ *   hookFailed: (cause: string) => string,
+ *   remedy: string,
+ * }>}
+ */
+export const USER_PROMPT_MESSAGES: Readonly<{
+    unknownEvent: string;
+    blockContext: string;
+    sgrNote: string;
+    hookFailed: (cause: string) => string;
+    remedy: string;
+}>;

package/types/claude-hooks/scan-invisible-chars.d.mts

@@ -42,9 +42,9 @@ export function scanFile(filePath: string): Array<{
 }>;
 import { ALERT_FILE } from "./lib/invisible-alert.mjs";
 import { ALERT_ACK_FILE } from "./lib/invisible-alert.mjs";
-export const LONG_RUN_RE: RegExp;
-export const LONG_RUN_THRESHOLD: 10;
-export const TOTAL_INVISIBLE_THRESHOLD: 30;
+export let LONG_RUN_RE: RegExp;
+export let LONG_RUN_THRESHOLD: 10;
+export let TOTAL_INVISIBLE_THRESHOLD: 30;
 /**
  * @param {Array<{
  *   file: string,