agent-sanitizer 2.8.0 → 2.9.1

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

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

@@ -18,7 +18,14 @@
  * (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,
+  lazyImport,
+  missingPackageError,
+  DEFAULT_MISSING_PACKAGE_REMEDY,
+} from "./lib/hook-io.mjs";
 import { controlPlane, runJudgeCli } from "./lib/control-plane.mjs";
 import { trace, TraceEvent } from "./lib/trace.mjs";
 // classifyPrompt (the user-prompt verdict) and stripAnsiFully (its ANSI stripper)
@@ -26,34 +33,61 @@ import { trace, TraceEvent } from "./lib/trace.mjs";
 // import, never a bare top-level `import … from "…"`: a static npm import
 // resolves before any try/catch, so a missing node_modules would crash this hook
 // at load and let the prompt through UNSANITIZED (fail-open). A failed load
-// leaves the bindings undefined, which main()'s typeof guard turns into a
-// fail-closed block.
+// leaves that binding undefined, which the judge's typeof guards turn into a
+// fail-closed block — one guard each, since the two loads succeed or fail
+// independently.
 /** @type {typeof import("agent-sanitizer/prompt").classifyPrompt} */
 export let classifyPrompt;
 /** @type {typeof import("agent-sanitizer").stripAnsiFully} */
 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,
+ *   remedy: 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}`,
+  // What a reader should run when the package itself is what is missing. It
+  // rides in this table rather than a separate argument because it is host text
+  // exactly like the reasons above, and one channel means a host cannot supply
+  // its wording in one place and forget it in the other.
+  remedy: DEFAULT_MISSING_PACKAGE_REMEDY,
+});
 
 /* c8 ignore start — module-load boundary: the imports resolve in every real
  * run, and their failure (the package absent) can't be simulated in-process, so
- * neither arm is observable to the in-process tests. main()'s typeof guard
+ * neither arm is observable to the in-process tests. The judge's typeof guard
  * converts an undefined stripper into a fail-closed block — that guard IS tested. */
 // Stryker disable all
-try {
-  // The /prompt subpath is imported first: if it fails, the catch fires before
-  // stripAnsiFully is assigned, so a half-load can never leave the stripper set
-  // while the classifier is missing (main guards on the stripper alone).
-  ({ classifyPrompt } = await import("agent-sanitizer/prompt"));
-  ({ stripAnsiFully } = await import("agent-sanitizer"));
-} catch {
-  // Leave classifyPrompt/stripAnsiFully undefined so main()'s typeof guard fails
-  // closed — the prompt is blocked, never passed through with the package
-  // half-loaded.
-}
+// lazyImport rather than a bare `await import` in a try/catch: it RECORDS the
+// loader error, which is the only thing that can tell a missing install apart
+// from a present package missing an export. Discarding it leaves
+// missingPackageError with nothing to report but a guess.
+// The cast asserts the loaded SHAPE, not that it loaded: lazyImport yields {} on
+// failure, so either binding can still be undefined here — which is exactly what
+// the judge's typeof guard turns into a fail-closed block.
+({ classifyPrompt } = /** @type {typeof import("agent-sanitizer/prompt")} */ (
+  await lazyImport("agent-sanitizer/prompt")
+));
+({ stripAnsiFully } = /** @type {typeof import("agent-sanitizer")} */ (
+  await lazyImport("agent-sanitizer")
+));
 // Stryker restore all
 /* c8 ignore stop */
 
@@ -67,9 +101,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 +122,24 @@ 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.
+  // The module-load guard, one arm per binding. The two lazyImports are
+  // INDEPENDENT — each yields {} on its own failure — so a present stripper does
+  // not prove the classifier loaded, and guarding on it alone would let a
+  // classifier-only failure reach `classifyPrompt(...)` as a bare TypeError
+  // naming no package, no cause and no remedy: the exact diagnostic this hook
+  // now exists to produce. lazyImportErrorFor matches subpaths, so naming
+  // `agent-sanitizer/prompt` still recovers the recorded cause.
   if (typeof strip !== "function")
-    throw new Error("agent-sanitizer is unavailable");
+    throw missingPackageError("agent-sanitizer", undefined, messages.remedy);
+  if (typeof classifyPrompt !== "function")
+    throw missingPackageError(
+      "agent-sanitizer/prompt",
+      undefined,
+      messages.remedy,
+    );
   // The contract guarantees a string here: every adapter normalizes the
   // prompt-submit input (Claude's parse coerces a missing/non-string prompt to
   // "" via asString), so a defensive typeof re-check is a dead branch.
@@ -97,13 +148,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 +163,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 +186,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 +207,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.1",
   "description": "Defend an agent against hidden-content injection: strip payload-capable invisible Unicode and ANSI, splice out human-invisible HTML, and flag data-exfil URLs in untrusted text before any model sees it.",
   "type": "module",
   "repository": {
@@ -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.";