agent-sanitizer 2.8.0 → 2.9.0

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/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,33 @@ 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,
+ * }>}
+ */
+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}`,
+});
+
 // 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 +284,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 +305,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 +336,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 +382,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 +410,35 @@ 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[],
+ *   remedy?: string,
+ * }} [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 = [], remedy } = 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, remedy),
+          }),
+        ),
+    },
+  );
 }
 
 if (isMain(import.meta.url)) {

package/claude-hooks/sanitize-output.mjs

@@ -28,6 +28,9 @@ import {
   errMessage,
   safeErrMessage,
   makeDeadline,
+  lazyImportErrorFor,
+  missingPackageMessage,
+  DEFAULT_MISSING_PACKAGE_REMEDY,
   HookEvent,
 } from "./lib/hook-io.mjs";
 import { controlPlane, runJudgeCli } from "./lib/control-plane.mjs";
@@ -478,13 +481,6 @@ const FAIL_CLOSED_CONTEXT =
   "(replaced with a placeholder) to fail closed -- the unsanitized output was " +
   "not shown. Investigate the hook error before relying on this tool.";
 
-// The one cause that is a broken INSTALL rather than a broken hook: the
-// sanitizer's bindings are absent, so every subsequent tool call fails closed
-// with no visible cause. Name the remedy in the emission itself.
-const MISSING_DEPS_HINT =
-  " The cause is a missing dependency (agent-sanitizer did not load), not a" +
-  " hook defect: reinstall the plugin, then retry the tool call.";
-
 /**
  * Whether the sanitizer's bindings actually loaded. lazyImport swallows a
  * missing package and yields `{}`, so the absence shows up as an undefined
@@ -501,15 +497,22 @@ export function sanitizerDepsLoaded() {
 }
 
 /**
- * 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 = sanitizerDepsLoaded) {
-  return depsLoaded()
-    ? FAIL_CLOSED_CONTEXT
-    : FAIL_CLOSED_CONTEXT + MISSING_DEPS_HINT;
+export function failClosedContext(
+  depsLoaded = sanitizerDepsLoaded,
+  remedy = DEFAULT_MISSING_PACKAGE_REMEDY,
+) {
+  if (depsLoaded()) return FAIL_CLOSED_CONTEXT;
+  return `${FAIL_CLOSED_CONTEXT} ${missingPackageMessage("agent-sanitizer", lazyImportErrorFor("agent-sanitizer"), remedy)}`;
 }
 
 /**

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

@@ -18,7 +18,12 @@
  * (cursor movement, erase, OSC title-set, DCS/APC/PM) still blocks, as do the
  * invisible-char thresholds, which are the actual web-paste payload defense.
  */
-import { readStdinJson, safeErrMessage, isMain } from "./lib/hook-io.mjs";
+import {
+  readStdinJson,
+  safeErrMessage,
+  isMain,
+  missingPackageError,
+} from "./lib/hook-io.mjs";
 import { controlPlane, runJudgeCli } from "./lib/control-plane.mjs";
 import { trace, TraceEvent } from "./lib/trace.mjs";
 // classifyPrompt (the user-prompt verdict) and stripAnsiFully (its ANSI stripper)
@@ -33,10 +38,28 @@ export let classifyPrompt;
 /** @type {typeof import("agent-sanitizer").stripAnsiFully} */
 let stripAnsiFully;
 
-const BLOCK_CONTEXT =
-  "User prompt blocked: payload-capable invisible/ANSI characters detected.";
-const SGR_NOTE =
-  "The prompt contains ANSI SGR color codes (pasted terminal output). They are display-only formatting noise; read through them.";
+/**
+ * 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,
+ * }>}
+ */
+export const USER_PROMPT_MESSAGES = Object.freeze({
+  unknownEvent: "User prompt blocked (fail-closed): unrecognized hook payload.",
+  blockContext:
+    "User prompt blocked: payload-capable invisible/ANSI characters detected.",
+  sgrNote:
+    "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}`,
+});
 
 /* 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
@@ -67,9 +90,20 @@ try {
  * @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, strip = stripAnsiFully) {
+export function judgeSanitizeUserPrompt(
+  event,
+  strip = stripAnsiFully,
+  overrides = USER_PROMPT_MESSAGES,
+) {
+  // MERGED over the defaults, never substituted for them — a host that overrides
+  // one field would otherwise leave the rest undefined. main() threads the same
+  // object into its onError, where a missing field throws out of the catch and
+  // the gate emits nothing, which the harness reads as a pass: fail OPEN.
+  const messages = { ...USER_PROMPT_MESSAGES, ...overrides };
   const { Decision, EventKind } = controlPlane();
   // A payload the adapter cannot classify carries no readable prompt, so an
   // abstain would fail OPEN on harness contract drift; this gate's posture is
@@ -77,18 +111,14 @@ export function judgeSanitizeUserPrompt(event, strip = stripAnsiFully) {
   // channel — a non-PRE_TOOL event has no permissionDecision body — which Claude
   // honors on UserPromptSubmit.)
   if (event.event === EventKind.UNKNOWN)
-    return {
-      decision: Decision.DENY,
-      reason: "User prompt blocked (fail-closed): unrecognized hook payload.",
-    };
+    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 new Error("agent-sanitizer is unavailable");
+  if (typeof strip !== "function") throw missingPackageError("agent-sanitizer");
   // 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.
@@ -97,13 +127,13 @@ export function judgeSanitizeUserPrompt(event, strip = stripAnsiFully) {
   const verdict = classifyPrompt(prompt, strip);
   if (verdict.action === "pass") return { decision: Decision.ALLOW };
   if (verdict.action === "note")
-    return { decision: Decision.ALLOW, additional_context: SGR_NOTE };
+    return { decision: Decision.ALLOW, additional_context: messages.sgrNote };
   // block: carry the reason AND a context note — UserPromptSubmit can't rewrite
   // the prompt, so the context is the only forward signal about why it dropped.
   return {
     decision: Decision.DENY,
     reason: verdict.reason,
-    additional_context: BLOCK_CONTEXT,
+    additional_context: messages.blockContext,
   };
 }
 
@@ -112,9 +142,19 @@ export function judgeSanitizeUserPrompt(event, strip = stripAnsiFully) {
  * @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 async function main(read, write, strip = stripAnsiFully) {
+export async function main(
+  read,
+  write,
+  strip = stripAnsiFully,
+  overrides = USER_PROMPT_MESSAGES,
+) {
+  // Merged, not substituted — see judgeSanitizeUserPrompt. onError below is the
+  // call site where a missing field would throw out of the catch and fail OPEN.
+  const messages = { ...USER_PROMPT_MESSAGES, ...overrides };
   // Delegate the parse → judge → render → write contract to the shared
   // runJudgeCli so this hook doesn't re-implement the control-plane boundary:
   // runJudgeCli reads stdin BEFORE loading the control-plane package, so a
@@ -125,7 +165,7 @@ export async function main(read, write, strip = stripAnsiFully) {
   await runJudgeCli(
     "sanitize-user-prompt",
     (event) => {
-      const verdict = judgeSanitizeUserPrompt(event, strip);
+      const verdict = judgeSanitizeUserPrompt(event, strip, messages);
       // Announce engagement on the trace channel like the other stdin hooks —
       // a prompt gate that silently stopped running is otherwise invisible.
       trace(TraceEvent.HOOK_RAN, {
@@ -146,7 +186,7 @@ export async function main(read, write, strip = stripAnsiFully) {
         write(
           JSON.stringify({
             decision: "block",
-            reason: `sanitize-user-prompt hook failed (fail-closed): ${safeErrMessage(err)}`,
+            reason: messages.hookFailed(safeErrMessage(err)),
           }),
         ),
     },

package/claude-hooks/scan-invisible-chars.mjs

@@ -7,7 +7,15 @@
  */
 import { readFileSync, globSync, writeFileSync, unlinkSync } from "node:fs";
 import { join, relative } from "node:path";
-import { isMain, lazyImport, writeFileNoFollow } from "./lib/hook-io.mjs";
+import {
+  awaitLazyDependency,
+  hookgateMarkerPath,
+  isMain,
+  lazyImport,
+  markerIsTrusted,
+  probeSetupAlive,
+  writeFileNoFollow,
+} from "./lib/hook-io.mjs";
 import {
   ALERT_FILE,
   ALERT_ACK_FILE,
@@ -17,9 +25,11 @@ import { trace, TraceEvent } from "./lib/trace.mjs";
 
 // Layer-1 primitives, bound via lazyImport (see its doc for the fail-OPEN
 // hazard of a bare static npm import — here the instruction files would load
-// UNSCANNED). A failed load leaves the bindings undefined, and cliMain's guard
-// below fails loud rather than silently passing.
-const {
+// UNSCANNED). A failed load leaves the bindings undefined; on a cold container
+// (node deps not yet installed) cliMain's guard below waits out session-setup
+// before giving up, and fails loud rather than silently passing.
+// `let`, not `const`: the cold-start poll re-binds these once the package loads.
+let {
   LONG_RUN_RE,
   LONG_RUN_THRESHOLD,
   SCATTERED_THRESHOLD: TOTAL_INVISIBLE_THRESHOLD,
@@ -29,6 +39,44 @@ const {
   await lazyImport("agent-sanitizer/invisible")
 );
 
+/**
+ * Re-attempt the sanitizer import, waiting out an in-flight session-setup before
+ * giving up. On a cold container the node deps this hook needs are still being
+ * installed when SessionStart fires; without this wait `stripInvisible` is
+ * undefined, the scan is skipped, and the instruction files load UNSCANNED for the
+ * whole session (fail open) — silently. Reuses the control-plane poll (marker +
+ * PID liveness) so the wait bound matches every other cold-start-aware gate.
+ * @returns {Promise<boolean>} whether the sanitizer is now bound
+ */
+async function ensureSanitizerLoaded() {
+  if (typeof stripInvisible === "function") return true;
+  /* c8 ignore start -- cold-start reload: only runs when the top-level
+     agent-sanitizer import above failed (node deps not yet installed), which
+     can't be simulated in-process or in the spawned-subprocess CLI run the tests
+     observe (the test env always has the deps, so the guard above early-returns).
+     The reload reuses awaitLazyDependency / markerIsTrusted /
+     probeSetupAlive, each unit-tested directly. */
+  const marker = hookgateMarkerPath();
+  const reloaded = await awaitLazyDependency({
+    tryImport: async () => {
+      const mod = await lazyImport("agent-sanitizer/invisible");
+      return typeof mod.stripInvisible === "function" ? mod : null;
+    },
+    markerPresent: () => markerIsTrusted(marker),
+    setupAlive: () => probeSetupAlive(marker),
+  });
+  if (!reloaded) return false;
+  ({
+    LONG_RUN_RE,
+    LONG_RUN_THRESHOLD,
+    SCATTERED_THRESHOLD: TOTAL_INVISIBLE_THRESHOLD,
+    STRIP,
+    stripInvisible,
+  } = /** @type {typeof import("agent-sanitizer/invisible")} */ (reloaded));
+  return true;
+  /* c8 ignore stop */
+}
+
 // Decoder
 
 /**
@@ -229,14 +277,15 @@ export async function cliMain() {
   /* c8 ignore start -- fail-closed module-load guard: only reachable when the
      agent-sanitizer import above failed, which can't be simulated in the
      spawned-subprocess CLI run the tests observe. */
-  if (typeof stripInvisible !== "function") {
+  if (!(await ensureSanitizerLoaded())) {
     // Emit the engagement event with a "skipped" outcome so the loss is LOUD on
     // the trace channel — a scan that never ran is otherwise invisible, and the
     // downstream PreToolUse sanitize gate then passes cleanly all session.
     trace(TraceEvent.SCAN_INVISIBLE_CHARS_RAN, { outcome: "skipped" });
     process.stderr.write(
-      "scan-invisible-chars: agent-sanitizer failed to load; instruction " +
-        "files were NOT scanned for hidden Unicode.\n",
+      "scan-invisible-chars: agent-sanitizer failed to load (node deps not " +
+        "installed and session-setup did not finish in time); instruction " +
+        "files were NOT scanned for hidden Unicode. Run `pnpm install`.\n",
     );
     process.exit(1);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.8.0",
+  "version": "2.9.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": {
@@ -153,6 +153,34 @@
     "./claude-hooks/lib/control-plane": {
       "types": "./types/claude-hooks/lib/control-plane.d.mts",
       "default": "./claude-hooks/lib/control-plane.mjs"
+    },
+    "./claude-hooks/lib/invisible-alert": {
+      "types": "./types/claude-hooks/lib/invisible-alert.d.mts",
+      "default": "./claude-hooks/lib/invisible-alert.mjs"
+    },
+    "./claude-hooks/lib/authored-content": {
+      "types": "./types/claude-hooks/lib/authored-content.d.mts",
+      "default": "./claude-hooks/lib/authored-content.mjs"
+    },
+    "./claude-hooks/lib/env-config": {
+      "types": "./types/claude-hooks/lib/env-config.d.mts",
+      "default": "./claude-hooks/lib/env-config.mjs"
+    },
+    "./claude-hooks/lib/secret-annotate": {
+      "types": "./types/claude-hooks/lib/secret-annotate.d.mts",
+      "default": "./claude-hooks/lib/secret-annotate.mjs"
+    },
+    "./claude-hooks/lib/reveal": {
+      "types": "./types/claude-hooks/lib/reveal.d.mts",
+      "default": "./claude-hooks/lib/reveal.mjs"
+    },
+    "./claude-hooks/lib/redactor-client": {
+      "types": "./types/claude-hooks/lib/redactor-client.d.mts",
+      "default": "./claude-hooks/lib/redactor-client.mjs"
+    },
+    "./claude-hooks/lib/trace": {
+      "types": "./types/claude-hooks/lib/trace.d.mts",
+      "default": "./claude-hooks/lib/trace.mjs"
     }
   },
   "files": [

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

@@ -62,6 +62,47 @@ export function registeredLazyModule(specifier: string): Record<string, any> | u
  * @returns {Promise<Record<string, any>>}
  */
 export function lazyImport(specifier: string): Promise<Record<string, any>>;
+/**
+ * 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: string): unknown;
+/**
+ * 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(): string[];
+/**
+ * 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: string, err?: unknown, remedy?: string): string;
+/**
+ * {@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: string, err?: unknown, remedy?: string): Error;
 /**
  * A monotonic wall-clock budget shared across one hook run's downstream blocking
  * calls. `remainingMs()` returns the milliseconds left until the budget is spent
@@ -126,6 +167,77 @@ export function safeErrMessage(err: unknown, cap?: number): string;
  * @returns {void}
  */
 export function emitHookResponse(hookEventName: string, fields: Record<string, unknown>): void;
+/**
+ * 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?: string | undefined, runtimeDir?: string | undefined): string | null;
+/**
+ * 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: string | null): boolean;
+/**
+ * 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 function awaitLazyDependency({ tryImport, markerPresent, setupAlive, now, sleep, graceMs, settleMs, ceilingMs, intervalMs, }: {
+    tryImport: () => Promise<object | null>;
+    markerPresent: () => boolean;
+    setupAlive: () => boolean;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    graceMs?: number;
+    settleMs?: number;
+    ceilingMs?: number;
+    intervalMs?: number;
+}): Promise<object | null>;
 /**
  * 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
@@ -194,3 +306,10 @@ export const PermissionDecision: Readonly<{
  * and take its own fail-closed output down with it.
  */
 export const MAX_STDIN_BYTES: number;
+/**
+ * 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.";

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[],
+ *   remedy?: string,
+ * }} [opts]
  * @returns {Promise<void>}
  */
-export function cliMain(): 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
+ * 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,
+ * }>}
+ */
+export const PRE_TOOL_USE_MESSAGES: Readonly<{
+    unknownEvent: string;
+    failed: (cause: string) => string;
+    unparsable: (cause: string) => 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

@@ -118,12 +118,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

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

@@ -8,16 +8,39 @@
  * @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,
+ * }>}
+ */
+export const USER_PROMPT_MESSAGES: Readonly<{
+    unknownEvent: string;
+    blockContext: string;
+    sgrNote: string;
+    hookFailed: (cause: string) => 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,