agent-sanitizer 2.8.0 → 2.9.1

package/claude-hooks/lib/control-plane.mjs

@@ -7,7 +7,16 @@
  * transport rule (nativeStdout), and the shared judge-CLI transport
  * (runJudgeCli).
  */
-import { errMessage, lazyImport, readStdinJson } from "./hook-io.mjs";
+import {
+  awaitLazyDependency,
+  errMessage,
+  hookgateMarkerPath,
+  lazyImport,
+  markerIsTrusted,
+  missingPackageError,
+  probeSetupAlive,
+  readStdinJson,
+} from "./hook-io.mjs";
 
 // Loaded via a *caught* dynamic import — never a bare static `import … from`.
 // A static npm import resolves before any try/catch, so a missing node_modules
@@ -26,20 +35,36 @@ let EventKind;
 /* c8 ignore start -- module-load boundary: the real import resolves in every
    in-process test and spawned CLI run, and a missing node_modules can't be
    simulated in-process, so this glue's failure arm is unobservable here. The
-   observable behaviour is controlPlane()'s throw, unit-tested directly. */
+   observable logic lives in awaitLazyDependency, unit-tested directly. */
 // Stryker disable all
-{
-  const { claudeAdapter: adapter } =
-    /** @type {Partial<typeof import("agent-control-plane-core/claude")>} */ (
-      await lazyImport("agent-control-plane-core/claude")
-    );
-  const { Decision: decision, EventKind: eventKind } =
-    /** @type {Partial<typeof import("agent-control-plane-core")>} */ (
-      await lazyImport("agent-control-plane-core")
+const marker = hookgateMarkerPath();
+const loaded = await awaitLazyDependency({
+  tryImport: async () => {
+    // lazyImport is the shared caught npm import (see hook-io): it returns the
+    // module on success and {} on a failed load, so a missing binding is the
+    // null signal the poll loop waits on — no bare import()/try-catch here.
+    const { claudeAdapter: adapter } =
+      /** @type {Partial<typeof import("agent-control-plane-core/claude")>} */ (
+        await lazyImport("agent-control-plane-core/claude")
+      );
+    const { Decision: decision, EventKind: eventKind } =
+      /** @type {Partial<typeof import("agent-control-plane-core")>} */ (
+        await lazyImport("agent-control-plane-core")
+      );
+    if (!adapter || !decision || !eventKind) return null;
+    return { claudeAdapter: adapter, Decision: decision, EventKind: eventKind };
+  },
+  markerPresent: () => markerIsTrusted(marker),
+  setupAlive: () => probeSetupAlive(marker),
+});
+if (loaded) {
+  const bound =
+    /** @type {{ claudeAdapter: typeof claudeAdapter, Decision: typeof Decision, EventKind: typeof EventKind }} */ (
+      loaded
     );
-  claudeAdapter = adapter;
-  Decision = decision;
-  EventKind = eventKind;
+  claudeAdapter = bound.claudeAdapter;
+  Decision = bound.Decision;
+  EventKind = bound.EventKind;
 }
 // Stryker restore all
 /* c8 ignore stop */
@@ -58,7 +83,7 @@ let EventKind;
 export function controlPlane(overrides = {}) {
   const bindings = { claudeAdapter, Decision, EventKind, ...overrides };
   if (!bindings.claudeAdapter || !bindings.Decision || !bindings.EventKind)
-    throw new Error("agent-control-plane-core is unavailable");
+    throw missingPackageError("agent-control-plane-core");
   return /** @type {ReturnType<typeof controlPlane>} */ (bindings);
 }
 

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

@@ -4,10 +4,12 @@ import {
   openSync,
   closeSync,
   lstatSync,
+  readFileSync,
   unlinkSync,
   writeFileSync,
 } from "node:fs";
 import { userInfo } from "node:os";
+import { createHash } from "node:crypto";
 import { pathToFileURL } from "node:url";
 
 let cliEntryClaimed = false;
@@ -154,6 +156,14 @@ export function registeredLazyModule(specifier) {
   return registeredLazyModules[specifier];
 }
 
+/**
+ * Last load error per specifier, recorded when {@link lazyImport} swallows a
+ * failed import. Read by {@link lazyImportErrorFor} so a fail-closed hook can
+ * say WHY its dependency is absent instead of a bare "unavailable".
+ * @type {Map<string, unknown>}
+ */
+const lazyImportErrors = new Map();
+
 /**
  * Dynamic-import `specifier`, yielding `{}` when the module cannot be loaded.
  * Hooks bind their npm packages through this instead of a bare static import: a
@@ -169,14 +179,121 @@ export function registeredLazyModule(specifier) {
  */
 export async function lazyImport(specifier) {
   const registered = registeredLazyModules[specifier];
-  if (registered) return registered;
+  if (registered) {
+    lazyImportErrors.delete(specifier);
+    return registered;
+  }
   try {
-    return await import(specifier);
-  } catch {
+    const loaded = await import(specifier);
+    lazyImportErrors.delete(specifier);
+    return loaded;
+  } catch (err) {
+    // Delete before set: a Map keeps a re-set key at its ORIGINAL insertion
+    // position, and both readers below are recency-ordered — so re-recording in
+    // place would let a stale first failure outrank the one that just happened.
+    lazyImportErrors.delete(specifier);
+    lazyImportErrors.set(specifier, err);
     return {};
   }
 }
 
+/**
+ * The most recently recorded load error for `pkg` under any of its specifiers —
+ * the bare package or a subpath export (`pkg/output`, `pkg/invisible`) — or
+ * undefined when none is recorded. Hooks import a package through several
+ * subpaths; any one of them names why the package is absent, and the newest
+ * record reflects the current failure when they differ.
+ * @param {string} pkg
+ * @returns {unknown}
+ */
+export function lazyImportErrorFor(pkg) {
+  for (const [specifier, err] of [...lazyImportErrors].reverse())
+    if (specifier === pkg || specifier.startsWith(`${pkg}/`)) return err;
+  return undefined;
+}
+
+/**
+ * Package names (never relative-path specifiers) with a recorded load error,
+ * newest first — so a fail-closed reason can name whichever dependency actually
+ * failed instead of consulting a hardcoded package list.
+ * @returns {string[]}
+ */
+export function failedLazyPackages() {
+  const pkgs = new Set();
+  for (const specifier of [...lazyImportErrors.keys()].reverse()) {
+    // Only bare package names: relative/absolute paths and URL specifiers
+    // (file:, node:) are not npm packages a reinstall could restore.
+    if (!/^[\w@]/.test(specifier) || specifier.includes(":")) continue;
+    const parts = specifier.split("/");
+    pkgs.add(
+      specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0],
+    );
+  }
+  return [...pkgs];
+}
+
+/**
+ * The remedy {@link missingPackageMessage} states when the host does not supply
+ * one of its own. A host whose install has a specific entry point (a setup
+ * script, a devcontainer rebuild) passes that instead, so the reason names the
+ * command the reader should actually run.
+ */
+export const DEFAULT_MISSING_PACKAGE_REMEDY =
+  "reinstall the hook dependencies (pnpm install) and retry.";
+
+/**
+ * The fail-closed reason for a package a hook could not load: the recorded
+ * loader error plus the remedy. The cause is scrubbed (it is spliced into
+ * reasons shown to user and model) and its cap is COMPUTED so that
+ * prefix + cause + remedy always fits the downstream 300-char safeErrMessage
+ * re-scrub — the remedy can never be truncated off, whatever the package name.
+ * A remedy that alone exceeds that budget (roughly 260 characters) leaves the
+ * cause nothing to spend and still overruns; keep host remedies to a sentence.
+ * @param {string} pkg
+ * @param {unknown} [err]
+ * @param {string} [remedy]
+ * @returns {string}
+ */
+export function missingPackageMessage(
+  pkg,
+  err = lazyImportErrorFor(pkg),
+  remedy = DEFAULT_MISSING_PACKAGE_REMEDY,
+) {
+  const prefix = `${pkg} is unavailable: `;
+  // 2 for the "; " joiner; 12 for safeErrMessage's own "…[truncated]" marker,
+  // which lands past its cap when the cause is cut. Clamped at 0 because the
+  // remedy is host text: a long one drives the budget negative, and
+  // safeErrMessage does not clamp — `slice(0, -n)` trims from the END, returning
+  // nearly the whole cause and pushing the joined message past 300, so the
+  // downstream re-scrub cuts the remedy off. At 0 the cause degrades to the
+  // truncation marker and the remedy always survives.
+  const causeCap = Math.max(0, 300 - prefix.length - remedy.length - 2 - 12);
+  const cause =
+    err === undefined
+      ? "no load error recorded — the package likely loaded but lacks an expected export (version skew)"
+      : safeErrMessage(err, causeCap);
+  return `${prefix}${cause}; ${remedy}`;
+}
+
+/**
+ * {@link missingPackageMessage} as a throwable, tagged `code: "DEP_UNAVAILABLE"`
+ * so downstream reason-builders can recognize it structurally and not append a
+ * second copy of the same cause.
+ * @param {string} pkg
+ * @param {unknown} [err]
+ * @param {string} [remedy]
+ * @returns {Error}
+ */
+export function missingPackageError(
+  pkg,
+  err = lazyImportErrorFor(pkg),
+  remedy = DEFAULT_MISSING_PACKAGE_REMEDY,
+) {
+  return Object.assign(new Error(missingPackageMessage(pkg, err, remedy)), {
+    code: "DEP_UNAVAILABLE",
+  });
+}
+
 /**
  * A monotonic wall-clock budget shared across one hook run's downstream blocking
  * calls. `remainingMs()` returns the milliseconds left until the budget is spent
@@ -274,6 +391,148 @@ export function emitHookResponse(hookEventName, fields) {
   );
 }
 
+/** The marker filename stem; the project directory is appended to it. */
+const HOOKGATE_MARKER_STEM = "agent-sanitizer-hookgate-inflight-";
+
+/**
+ * Path of the cold-start in-flight marker a host's setup script writes
+ * SYNCHRONOUSLY before it starts installing deps (its own PID as the contents)
+ * and removes once the hook dependencies are provisioned. A hook that fires
+ * before setup finishes finds the marker and WAITS for its dependency rather
+ * than failing closed on it — so the first turn is merely delayed, never
+ * blocked, for as long as setup is still alive (the PID lets the hook tell a
+ * live install from a stale marker left by a killed setup). Derived purely from
+ * the raw CLAUDE_PROJECT_DIR the harness sets for both processes (no
+ * canonicalization — the two must produce byte-identical paths), so no env has
+ * to propagate from setup to the hook. Null when CLAUDE_PROJECT_DIR is unset (no
+ * setup ran → nothing to wait on).
+ * @param {string | undefined} [projectDir]
+ * @param {string | undefined} [runtimeDir]
+ * @returns {string | null}
+ */
+export function hookgateMarkerPath(
+  projectDir = process.env.CLAUDE_PROJECT_DIR,
+  runtimeDir = process.env.XDG_RUNTIME_DIR,
+) {
+  if (!projectDir) return null;
+  // Prefer the per-user, mode-0700 runtime dir when the harness gives an
+  // absolute one; else the world-writable /tmp, where markerIsTrusted() — not
+  // the path — defends against a squatted marker.
+  const base = runtimeDir && runtimeDir.startsWith("/") ? runtimeDir : "/tmp";
+  // The flattened dir is for a human reading `ls /tmp`; the digest of the RAW
+  // dir is the identity. Flattening alone is lossy — /work/a-b, /work/a_b and
+  // "/work/a b" all collapse to one name — and two such projects on one machine
+  // would then share a marker: B's hook waits out A's install for a dependency A
+  // is not installing, and A clearing the marker aborts B's legitimate wait. Both
+  // directions are silent. A setup script reproduces the digest with sha256sum.
+  const digest = createHash("sha256")
+    .update(projectDir)
+    .digest("hex")
+    .slice(0, 8);
+  const flattened = projectDir.replace(/[^A-Za-z0-9]/g, "_");
+  return `${base}/${HOOKGATE_MARKER_STEM}${flattened}-${digest}`;
+}
+
+/**
+ * Is the setup process that wrote `markerPath` still alive? `process.kill(pid, 0)`
+ * probes liveness without signalling: it throws ESRCH once the process is gone (a
+ * killed setup → stale marker, so stop waiting) and EPERM when it exists but isn't
+ * ours (still alive). An unreadable / not-yet-written marker is treated as alive —
+ * favouring a brief wait over a premature give-up during setup's write race. A null
+ * markerPath (no project dir → no setup to wait on) reads as alive so the caller's
+ * own grace/ceiling bound governs.
+ * @param {string | null} markerPath
+ * @returns {boolean}
+ */
+export function probeSetupAlive(markerPath) {
+  if (markerPath === null) return true;
+  let pid;
+  try {
+    pid = parseInt(readFileSync(markerPath, "utf8"), 10);
+  } catch {
+    return true;
+  }
+  if (!Number.isInteger(pid) || pid <= 0) return true;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return /** @type {NodeJS.ErrnoException} */ (err).code === "EPERM";
+  }
+}
+
+/**
+ * Resolve a lazily-loaded dependency, blocking through the cold-start window while
+ * setup is still installing it. Returns the loaded value, or null once it gives up
+ * (the caller leaves its bindings undefined so the hook fails closed). It waits for
+ * as long as setup is genuinely alive, so a slow install is never cut off; the only
+ * bound on that wait is a backstop ceiling that stays under the hook's harness
+ * timeout — a hook killed for running over is a fail-OPEN, the opposite of what a
+ * gate wants. The give-up cases are the honest ones (setup finished/died without the
+ * dep, or no setup at all), so a genuinely-absent dep fails closed fast, never after
+ * a long block:
+ *   - import succeeds                 → return immediately (warm session: no wait).
+ *   - marker present AND setup alive  → setup is working; wait it out (ceilingMs is a
+ *                                        backstop only, for a hung-but-alive setup).
+ *   - was installing, now not (marker cleared, or a stale marker from a killed setup)
+ *                                     → settleMs grace for a just-orphaned install to
+ *                                        land, then give up: the dep is absent.
+ *   - no live setup ever seen         → wait only graceMs (tolerating setup not having
+ *                                        written the marker yet), then give up.
+ * @param {{
+ *   tryImport: () => Promise<object | null>,
+ *   markerPresent: () => boolean,
+ *   setupAlive: () => boolean,
+ *   now?: () => number,
+ *   sleep?: (ms: number) => Promise<void>,
+ *   graceMs?: number,
+ *   settleMs?: number,
+ *   ceilingMs?: number,
+ *   intervalMs?: number,
+ * }} deps
+ * @returns {Promise<object | null>}
+ */
+export async function awaitLazyDependency({
+  tryImport,
+  markerPresent,
+  setupAlive,
+  now = () => Date.now(),
+  sleep = (ms) =>
+    new Promise((resolve) => {
+      setTimeout(resolve, ms);
+    }),
+  graceMs = 5000,
+  settleMs = 1000,
+  ceilingMs = 900000,
+  intervalMs = 250,
+}) {
+  const start = now();
+  let sawInstalling = false;
+  let enteredDone = false;
+  let doneAt = 0;
+  for (;;) {
+    const bindings = await tryImport();
+    if (bindings) return bindings;
+    const installing = markerPresent() && setupAlive();
+    let giveUp;
+    if (installing) {
+      sawInstalling = true;
+      enteredDone = false;
+      giveUp = now() - start > ceilingMs;
+    } else if (sawInstalling) {
+      if (!enteredDone) {
+        enteredDone = true;
+        doneAt = now();
+      }
+      giveUp = now() - doneAt > settleMs;
+    } else {
+      giveUp = now() - start > graceMs;
+    }
+    if (giveUp) return null;
+    await sleep(intervalMs);
+  }
+}
+
 /**
  * Is the file at `path` one WE wrote — a regular file owned by this uid — rather
  * than a squat? These markers live at predictable, world-visible $TMPDIR paths, so

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

@@ -27,6 +27,10 @@ import { readFileSync } from "node:fs";
 import {
   isMain,
   lazyImport,
+  lazyImportErrorFor,
+  failedLazyPackages,
+  missingPackageMessage,
+  DEFAULT_MISSING_PACKAGE_REMEDY,
   registeredLazyModule,
   emitHookResponse,
   safeErrMessage,
@@ -50,6 +54,39 @@ import { trace, TraceEvent } from "./lib/trace.mjs";
 
 const HOOK_NAME = "pretooluse-sanitize";
 
+/**
+ * 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 = Object.freeze({
+  unknownEvent:
+    "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
 // its doc for the fail-OPEN hazard of a bare static npm import); a failed load
 // leaves these bindings undefined, so the layer calls below throw into the CLI's
@@ -253,9 +290,19 @@ function assembleResponse({
  * 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 async function judgePreToolUseSanitize(event, rehydrate) {
+export async function judgePreToolUseSanitize(event, rehydrate, opts = {}) {
+  const { gates = [] } = opts;
+  // MERGED over the defaults, never substituted for them. A host that overrides
+  // one field would otherwise leave the rest undefined, and the miss lands in
+  // the fail-closed path: failClosedFields runs inside runJudgeCli's catch, so a
+  // TypeError on a missing field escapes the handler, the hook exits with no
+  // stdout, and Claude reads a PreToolUse hook that produced no response as
+  // non-blocking — the fail-closed ask becomes a fail-OPEN pass.
+  const messages = { ...PRE_TOOL_USE_MESSAGES, ...opts.messages };
   const { Decision, EventKind } = controlPlane();
   // A payload the adapter cannot classify (a missing/unexpected hook_event_name)
   // would drive the pipeline with an empty event and no-op to ALLOW — a silent
@@ -264,15 +311,23 @@ export async function judgePreToolUseSanitize(event, rehydrate) {
   // never a real call: deny-when-blind. Rewarding an unclassifiable payload with
   // a pass is the one incentive a gate must never create.
   if (event.event === EventKind.UNKNOWN)
-    return {
-      decision: Decision.DENY,
-      reason:
-        "PreToolUse sanitization blocked (fail-closed): unrecognized hook payload.",
-    };
-  const fields = await buildPreToolUseResponse(
-    { tool_name: event.tool, tool_input: event.input },
-    rehydrate,
-  );
+    return { decision: Decision.DENY, reason: messages.unknownEvent };
+  // The session identity travels in `meta`, not alongside the tool input; a host
+  // gate keyed on the session (a once-per-session checkpoint) cannot tell two
+  // sessions apart without it.
+  const input = {
+    tool_name: event.tool,
+    tool_input: event.input,
+    session_id: event.meta?.session_id,
+  };
+  // Host gates run BEFORE any rewriting layer, because they decide whether the
+  // call may happen at all rather than what its input contains — and returning
+  // early keeps a denied call from also being reported as a sanitized one.
+  for (const gate of gates) {
+    const denyReason = gate(input);
+    if (denyReason) return { decision: Decision.DENY, reason: denyReason };
+  }
+  const fields = await buildPreToolUseResponse(input, rehydrate);
   if (fields === null) return { decision: Decision.ALLOW };
   /** @type {Record<string, unknown>} */
   const verdict = {
@@ -287,6 +342,42 @@ export async function judgePreToolUseSanitize(event, rehydrate) {
   return /** @type {import("agent-control-plane-core").Verdict} */ (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,
+  remedy = DEFAULT_MISSING_PACKAGE_REMEDY,
+  failedPackages = failedLazyPackages,
+  loadErrorFor = lazyImportErrorFor,
+) {
+  if (/** @type {{code?: unknown}} */ (err)?.code === "DEP_UNAVAILABLE")
+    return "";
+  // Only a TypeError. The recorded-failure set is process-wide and carries no
+  // link to THIS error, so naming a package from it is an inference — sound only
+  // for the failure this hint exists to explain, where an unloaded binding is
+  // called and V8 raises a TypeError ("X is not a function", "Cannot read
+  // properties of undefined"). Any other throw is a layer engine reporting its
+  // own problem, and appending a package name there sends the reader to a
+  // reinstall that fixes nothing.
+  if (!(err instanceof TypeError)) return "";
+  const [pkg] = failedPackages();
+  return pkg === undefined
+    ? ""
+    : ` ${missingPackageMessage(pkg, loadErrorFor(pkg), remedy)}`;
+}
+
 /**
  * The fail-closed hookSpecificOutput fields for a hook-level failure, chosen by
  * WHICH failure it was. Corrupt/unparsable INPUT (`parsedOk` false — a JSON parse
@@ -297,16 +388,22 @@ export async function judgePreToolUseSanitize(event, rehydrate) {
  * 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, err) {
+export function failClosedFields(parsedOk, err, opts = {}) {
+  const { hint = depLoadHint(err) } = opts;
+  // Merged, not substituted — see judgePreToolUseSanitize. This is the call site
+  // where a missing field would throw out of the catch and fail OPEN.
+  const messages = { ...PRE_TOOL_USE_MESSAGES, ...opts.messages };
+  const cause = `${safeErrMessage(err)}${hint}`;
   return {
     permissionDecision: parsedOk
       ? PermissionDecision.ASK
       : PermissionDecision.DENY,
     permissionDecisionReason: parsedOk
-      ? `PreToolUse sanitization failed (fail-closed): ${safeErrMessage(err)}`
-      : `PreToolUse input unparsable (fail-closed): ${safeErrMessage(err)}`,
+      ? messages.failed(cause)
+      : messages.unparsable(cause),
   };
 }
 
@@ -319,21 +416,34 @@ export function failClosedFields(parsedOk, err) {
  * 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 async function cliMain() {
-  await runJudgeCli("pretooluse-sanitize", judgePreToolUseSanitize, {
-    // Fail closed WITHOUT the package: unparsable INPUT (`input` undefined)
-    // hard-denies (adversary-inducible, no benefit to failing); any throw
-    // after a clean parse — a layer engine down or the control-plane package
-    // unavailable — asks to keep a human in the loop. emitHookResponse renders
-    // natively, so this posture holds even when the adapter never loaded.
-    onError: (err, input) =>
-      emitHookResponse(
-        HookEvent.PRE_TOOL_USE,
-        failClosedFields(input !== undefined, err),
-      ),
-  });
+export async function cliMain(opts = {}) {
+  const { gates = [] } = opts;
+  const messages = { ...PRE_TOOL_USE_MESSAGES, ...opts.messages };
+  await runJudgeCli(
+    HOOK_NAME,
+    (event) => judgePreToolUseSanitize(event, undefined, { messages, gates }),
+    {
+      // Fail closed WITHOUT the package: unparsable INPUT (`input` undefined)
+      // hard-denies (adversary-inducible, no benefit to failing); any throw
+      // after a clean parse — a layer engine down or the control-plane package
+      // unavailable — asks to keep a human in the loop. emitHookResponse renders
+      // natively, so this posture holds even when the adapter never loaded.
+      onError: (err, input) =>
+        emitHookResponse(
+          HookEvent.PRE_TOOL_USE,
+          failClosedFields(input !== undefined, err, {
+            messages,
+            hint: depLoadHint(err, messages.remedy),
+          }),
+        ),
+    },
+  );
 }
 
 if (isMain(import.meta.url)) {