agent-sanitizer 2.9.0 → 2.10.0

package/README.md

@@ -145,11 +145,12 @@ surface is the `--hook=` CLI, so these move between minor versions.
 `cliMain`, so a composer that wraps `cliMain` gets the hook's exact fail-closed
 CLI wiring plus its own policy:
 
-| Field        | Runs                                                     | Does                                                                     |
-| ------------ | -------------------------------------------------------- | ------------------------------------------------------------------------ |
-| `postText`   | once per string **value** leaf, after Layers 1–4         | returns `{cleaned?, warning?}`; `cleaned` replaces the model-facing text |
-| `redactNote` | on the pre-redaction text of a leaf that tripped Layer 4 | returns a note appended to that leaf's redaction warning                 |
-| `audit`      | once per judged event carrying a tool response           | is handed the output the model will actually see                         |
+| Field        | Runs                                                     | Does                                                                                 |
+| ------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `postText`   | once per string **value** leaf, after Layers 1–4         | returns `{cleaned?, warning?}`; `cleaned` replaces the model-facing text             |
+| `redactNote` | on the pre-redaction text of a leaf that tripped Layer 4 | returns a note appended to that leaf's redaction warning                             |
+| `audit`      | once per judged event carrying a tool response           | is handed the output the model will actually see, and the `session_id` it belongs to |
+| `trace`      | on every exit, in place of the package's trace channel   | receives the engagement announcement (see the trace sink below)                      |
 
 Omit the bag and every seam is inert — the verdicts are byte-identical to this
 module alone. A callback that throws is **not** caught: it lands in the CLI's
@@ -172,6 +173,35 @@ secret-shaped output is suppressed, not shown unvetted. Layers 1–3 still run.
 never supply the `/output` seam's `filterInjection` callback, so nothing here
 calls a model or leaves the machine.
 
+**Every hook's trace sink is injectable.** Each one announces that it engaged —
+that is what makes a layer that stopped running loud rather than silent — and by
+default that announcement goes to `_AGENT_SANITIZER_TRACE` /
+`_AGENT_SANITIZER_TRACE_FILE`. A host that already runs a trace channel under
+its own variables passes its own sink instead, so the announcement lands where
+its detector actually reads:
+
+```js
+import { cliMain } from "agent-sanitizer/claude-hooks/scan-invisible-chars";
+await cliMain({ trace: (event, fields) => myChannel.emit(event, fields) });
+```
+
+The sink rides each hook's options bag — `cliMain({trace})` on
+`scan-invisible-chars` and `pretooluse-sanitize`, the extension bag's `trace` on
+`sanitize-output`, `main(read, write, {trace})` on `sanitize-user-prompt`. It
+receives the same `TraceEvent` names the default emits, and it **replaces** the
+default rather than running alongside it — the package channel goes silent, so
+there is one announcement to detect, not two. It may throw freely: each hook
+binds the sink it is given through `bestEffortTrace`, so an announcement can
+never be the thing that breaks a hook.
+
+**A host's own cold-start marker can replace the derived one.** The hooks wait
+out an in-flight dependency install by polling a marker file whose path they
+derive from `CLAUDE_PROJECT_DIR`; a host whose setup script already writes one
+calls `configureHookgateMarker(path)` (from `lib/hook-io`) before importing any
+hook module, and every consumer waits on that path instead. `lib/control-plane`
+resolves the marker at module scope, so a call that lands after that import
+warns on stderr — it cannot steer the wait that already started.
+
 Hook internals are tuned by `_AGENT_SANITIZER_*` variables (redactor daemon
 path/socket/timeouts, sanitize budget, trace channel, Layer-2 reveal dir). The
 leading underscore marks them unstable — the supported surface is the `--hook=`

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

@@ -394,6 +394,43 @@ export function emitHookResponse(hookEventName, fields) {
 /** The marker filename stem; the project directory is appended to it. */
 const HOOKGATE_MARKER_STEM = "agent-sanitizer-hookgate-inflight-";
 
+/**
+ * Host-supplied marker path, replacing the derived one. Null (the default) keeps
+ * the derivation below.
+ * @type {string | null}
+ */
+let hookgateMarkerOverride = null;
+
+/** Whether {@link hookgateMarkerPath} has already handed a path to a caller. */
+let hookgateMarkerResolved = false;
+
+/**
+ * Adopt a host's own cold-start marker path in place of the derived one, so a
+ * host whose setup script already writes a marker under its own convention can
+ * use these hooks without running a second, disagreeing wait loop against a path
+ * nothing writes.
+ *
+ * ORDERING, same rule as {@link registerLazyModules}: call this before importing
+ * any hook module. `lib/control-plane.mjs` resolves the marker at MODULE scope,
+ * so a call that lands after that import cannot reach the wait it was meant to
+ * steer. A late call is reported on stderr rather than thrown: a throw at a
+ * bundle entry's top level kills the hook process before it writes a response,
+ * and a hook that emits nothing is read as non-blocking — the fail-OPEN this
+ * whole file is built to avoid. The late call still takes effect for every
+ * later resolution.
+ * @param {string | null} path  absolute marker path, or null to restore the derivation
+ * @returns {void}
+ */
+export function configureHookgateMarker(path) {
+  if (hookgateMarkerResolved)
+    process.stderr.write(
+      "agent-sanitizer: configureHookgateMarker called after a marker path was " +
+        "already resolved; whatever resolved it is using the previous path and " +
+        "cannot be re-steered. Call it before importing any hook module.\n",
+    );
+  hookgateMarkerOverride = path;
+}
+
 /**
  * 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)
@@ -405,7 +442,8 @@ const HOOKGATE_MARKER_STEM = "agent-sanitizer-hookgate-inflight-";
  * 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).
+ * setup ran → nothing to wait on), or whatever a host set via
+ * {@link configureHookgateMarker}.
  * @param {string | undefined} [projectDir]
  * @param {string | undefined} [runtimeDir]
  * @returns {string | null}
@@ -414,6 +452,8 @@ export function hookgateMarkerPath(
   projectDir = process.env.CLAUDE_PROJECT_DIR,
   runtimeDir = process.env.XDG_RUNTIME_DIR,
 ) {
+  hookgateMarkerResolved = true;
+  if (hookgateMarkerOverride !== null) return hookgateMarkerOverride;
   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

package/claude-hooks/lib/trace.mjs

@@ -9,10 +9,28 @@
  *
  * METADATA ONLY — never pass a tool_input body or secret material as a field; the
  * channel is not redaction-aware.
+ *
+ * The sink is INJECTABLE. A host that already runs a trace channel under its own
+ * environment variables — and a detector that reds when a defense layer stops
+ * announcing itself — passes its own {@link TraceFn} to each hook's entry point
+ * (`cliMain`, or `main` for the prompt gate) instead of forking this module. Left
+ * unsupplied, every hook uses {@link trace} below, so the shipped behavior is
+ * unchanged.
  */
 
 import { appendFileSync } from "node:fs";
 
+/**
+ * The sink shape a hook emits through: the event name, its metadata fields, and
+ * the level. A host implementation receives the same {@link TraceEvent} names the
+ * default emits, so it can remap them onto its own channel's vocabulary.
+ *
+ * A sink is NOT required to be total — throw freely. Every hook binds the one it
+ * was given through {@link bestEffortTrace}, which is what upholds the channel's
+ * never-breaks-a-hook posture on host code that cannot promise it.
+ * @typedef {(event: string, fields?: Record<string, unknown>, level?: "info"|"debug") => void} TraceFn
+ */
+
 /** Trace-channel event names. */
 export const TraceEvent = Object.freeze({
   HOOK_RAN: "hook_ran",
@@ -58,3 +76,31 @@ export function trace(event, fields = {}, level = "info") {
     // best-effort: a trace we can't write must never break a hook.
   }
 }
+
+/**
+ * `sink` with {@link trace}'s best-effort posture forced onto it: a throw is
+ * swallowed, so an announcement can never break the hook making it.
+ *
+ * This is what makes the sink safely injectable. The announcement call sites were
+ * placed under the guarantee that emitting cannot fail, and one of them relies on
+ * it outright: scan-invisible-chars announces BEFORE it auto-cleans the
+ * contaminated instruction files and arms the PreToolUse gate, with no catch
+ * above it, so a throwing sink there would abort the scan — leaving the payload on
+ * disk, the gate un-armed, and NO announcement on any channel. The loss the
+ * announcement exists to make loud would itself be silent.
+ *
+ * Swallowing is right here and is not licence to swallow elsewhere in this tree:
+ * a dropped announcement is already loud in the host's own detector — that is what
+ * a trace channel is — whereas a killed hook is loud nowhere.
+ * @param {TraceFn} sink
+ * @returns {TraceFn}
+ */
+export function bestEffortTrace(sink) {
+  return (event, fields, level) => {
+    try {
+      sink(event, fields, level);
+    } catch {
+      // See above: an announcement must never be the thing that breaks a hook.
+    }
+  };
+}

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

@@ -50,7 +50,7 @@ import {
   authoredContext,
 } from "./lib/authored-content.mjs";
 import { redactViaDaemon } from "./lib/redactor-client.mjs";
-import { trace, TraceEvent } from "./lib/trace.mjs";
+import { bestEffortTrace, trace, TraceEvent } from "./lib/trace.mjs";
 
 const HOOK_NAME = "pretooluse-sanitize";
 
@@ -72,6 +72,7 @@ const HOOK_NAME = "pretooluse-sanitize";
  *   unknownEvent: string,
  *   failed: (cause: string) => string,
  *   unparsable: (cause: string) => string,
+ *   remedy: string,
  * }>}
  */
 export const PRE_TOOL_USE_MESSAGES = Object.freeze({
@@ -79,6 +80,11 @@ export const PRE_TOOL_USE_MESSAGES = Object.freeze({
     "PreToolUse sanitization blocked (fail-closed): unrecognized hook payload.",
   failed: (cause) => `PreToolUse sanitization failed (fail-closed): ${cause}`,
   unparsable: (cause) => `PreToolUse input unparsable (fail-closed): ${cause}`,
+  // What a reader should run when a dependency is what is missing. It rides in
+  // this table rather than a separate argument because it is host text exactly
+  // like the reasons above, and one channel means a host cannot supply its
+  // wording in one place and forget it in the other.
+  remedy: DEFAULT_MISSING_PACKAGE_REMEDY,
 });
 
 // Layers 2 & 4 come from the agent-sanitizer package, bound via lazyImport (see
@@ -144,18 +150,19 @@ const defaultRehydrate = (tool, toolInput) =>
  * it unchanged. The trace lives on this in-process, mutation-tested path, not in
  * the CLI block, so engagement is announced (hook_ran — metadata only: hook
  * name, tool, outcome) for every exit.
+ * @param {import("./lib/trace.mjs").TraceFn} emitTrace
  * @param {string} toolName
  * @param {Record<string, unknown> | null} fields
  * @returns {Record<string, unknown> | null}
  */
-function emitTraced(toolName, fields) {
+function emitTraced(emitTrace, toolName, fields) {
   let outcome = "modified";
   if (fields === null) outcome = "noop";
   else if (fields.permissionDecision === PermissionDecision.DENY)
     outcome = "deny";
   else if (fields.permissionDecision === PermissionDecision.ASK)
     outcome = "ask";
-  trace(TraceEvent.HOOK_RAN, { hook: HOOK_NAME, tool: toolName, outcome });
+  emitTrace(TraceEvent.HOOK_RAN, { hook: HOOK_NAME, tool: toolName, outcome });
   return fields;
 }
 
@@ -167,12 +174,18 @@ function emitTraced(toolName, fields) {
  * @param {(tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>} [rehydrate]
  * injectable for tests; the default binds the real redactor-daemon io (the
  * layer reads the target file and maps secrets through the daemon)
+ * @param {import("./lib/trace.mjs").TraceFn} [sink]  where engagement is
+ * announced; a host with its own trace channel passes its sink (see lib/trace.mjs)
  * @returns {Promise<Record<string, unknown> | null>}
  */
 export async function buildPreToolUseResponse(
   input,
   rehydrate = defaultRehydrate,
+  sink = trace,
 ) {
+  // Every path into the announcement runs through here, so this is the one place
+  // a host sink has to be made best-effort (see bestEffortTrace).
+  const emitTrace = bestEffortTrace(sink);
   const asks = [];
   const contexts = [];
 
@@ -221,7 +234,7 @@ export async function buildPreToolUseResponse(
   // above, so it returns immediately.
   const rehydrated = await rehydrate(tool, current);
   if (rehydrated && "deny" in rehydrated)
-    return emitTraced(input.tool_name, {
+    return emitTraced(emitTrace, input.tool_name, {
       permissionDecision: PermissionDecision.DENY,
       permissionDecisionReason: rehydrated.deny,
     });
@@ -232,6 +245,7 @@ export async function buildPreToolUseResponse(
   }
 
   return emitTraced(
+    emitTrace,
     input.tool_name,
     assembleResponse({ changed, current, asks, contexts, pendingGateAck }),
   );
@@ -284,12 +298,16 @@ 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]
+ * @param {{
+ *   messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>,
+ *   gates?: HostGate[],
+ *   trace?: import("./lib/trace.mjs").TraceFn,
+ * }} [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, opts = {}) {
-  const { gates = [] } = opts;
+  const { gates = [], trace: emitTrace = trace } = 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
@@ -321,7 +339,7 @@ export async function judgePreToolUseSanitize(event, rehydrate, opts = {}) {
     const denyReason = gate(input);
     if (denyReason) return { decision: Decision.DENY, reason: denyReason };
   }
-  const fields = await buildPreToolUseResponse(input, rehydrate);
+  const fields = await buildPreToolUseResponse(input, rehydrate, emitTrace);
   if (fields === null) return { decision: Decision.ALLOW };
   /** @type {Record<string, unknown>} */
   const verdict = {
@@ -413,16 +431,21 @@ export function failClosedFields(parsedOk, err, opts = {}) {
  * @param {{
  *   messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>,
  *   gates?: HostGate[],
- *   remedy?: string,
+ *   trace?: import("./lib/trace.mjs").TraceFn,
  * }} [opts]
  * @returns {Promise<void>}
  */
 export async function cliMain(opts = {}) {
-  const { gates = [], remedy } = opts;
+  const { gates = [], trace: emitTrace = trace } = opts;
   const messages = { ...PRE_TOOL_USE_MESSAGES, ...opts.messages };
   await runJudgeCli(
     HOOK_NAME,
-    (event) => judgePreToolUseSanitize(event, undefined, { messages, gates }),
+    (event) =>
+      judgePreToolUseSanitize(event, undefined, {
+        messages,
+        gates,
+        trace: emitTrace,
+      }),
     {
       // Fail closed WITHOUT the package: unparsable INPUT (`input` undefined)
       // hard-denies (adversary-inducible, no benefit to failing); any throw
@@ -434,7 +457,7 @@ export async function cliMain(opts = {}) {
           HookEvent.PRE_TOOL_USE,
           failClosedFields(input !== undefined, err, {
             messages,
-            hint: depLoadHint(err, remedy),
+            hint: depLoadHint(err, messages.remedy),
           }),
         ),
     },

package/claude-hooks/sanitize-output.mjs

@@ -34,7 +34,7 @@ import {
   HookEvent,
 } from "./lib/hook-io.mjs";
 import { controlPlane, runJudgeCli } from "./lib/control-plane.mjs";
-import { trace, TraceEvent } from "./lib/trace.mjs";
+import { bestEffortTrace, trace, TraceEvent } from "./lib/trace.mjs";
 import { hasEnvBoundSecret } from "./lib/secret-annotate.mjs";
 import {
   persistReveal,
@@ -192,9 +192,22 @@ async function redactSecrets(text, webIngress = false, deadline) {
  * @property {(raw: string) => string | undefined} [redactNote]
  *   Given the pre-redaction text of a leaf that tripped Layer 4, returns a note
  *   appended to that leaf's "API keys/secrets redacted: …" warning.
- * @property {(record: { tool: string | null, modified: boolean, output: unknown, context?: string }) => Promise<void> | void} [audit]
+ * @property {(record: { tool: string | null, session_id?: string, 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.
+ *   the model will actually see. `session_id` is the harness's session identity,
+ *   lifted from the event's `meta` — an audit trail that cannot say WHICH session
+ *   produced a record cannot be read back per-session, and the tool fields alone
+ *   do not carry it. Absent when the payload omitted it.
+ * @property {import("./lib/trace.mjs").TraceFn} [trace]
+ *   Where this hook announces engagement. A host that already runs a trace
+ *   channel under its own environment variables passes its sink here, so the
+ *   announcement lands where its detector reads instead of on this package's
+ *   channel. Defaults to lib/trace.mjs's `trace`.
+ * @property {string} [remedy]
+ *   What a reader should run when the sanitizer's own bindings are what is
+ *   missing. This hook's host channel is `ext`, where the other two gates use a
+ *   frozen message table; either way it is one channel per gate, so a host
+ *   cannot supply its wording somewhere the fail-closed context never reads.
  */
 
 /**
@@ -528,14 +541,19 @@ export function failClosedContext(
  * @param {any} input  parsed hook input, or undefined if parsing threw
  * @param {string} message
  * @param {(fields: Record<string, unknown>) => void} [emit]
+ * @param {string} [remedy]  what a reader should run; hosts pass their own
  * @returns {void}
  */
 export function emitFailClosed(
   input,
   message,
   emit = (fields) => emitHookResponse(HookEvent.POST_TOOL_USE, fields),
+  remedy = DEFAULT_MISSING_PACKAGE_REMEDY,
 ) {
-  const additionalContext = failClosedContext();
+  // Threaded rather than defaulted here: this is the ONLY production caller of
+  // failClosedContext, so a remedy it does not pass is a remedy no host can ever
+  // reach — the parameter would be live only from tests.
+  const additionalContext = failClosedContext(sanitizerDepsLoaded, remedy);
   try {
     emit({
       updatedToolOutput: failClosedReplacement(input, message),
@@ -562,13 +580,16 @@ export function emitFailClosed(
  * @returns {Promise<{ mutated_output?: unknown, additional_context?: string } | null>}
  */
 export async function evaluateToolOutput(input, ext = {}) {
+  // Best-effort, like the default sink: a host callback that throws must not be
+  // the thing that suppresses a tool output (see bestEffortTrace).
+  const emitTrace = bestEffortTrace(ext.trace ?? trace);
   /**
    * @param {string} outcome  noop | clean | flagged | modified
    * @param {{ mutated_output?: unknown, additional_context?: string } | null} fields
    * @returns {{ mutated_output?: unknown, additional_context?: string } | null}
    */
   const emit = (outcome, fields) => {
-    trace(TraceEvent.HOOK_RAN, {
+    emitTrace(TraceEvent.HOOK_RAN, {
       hook: HOOK_NAME,
       tool: input.tool_name,
       outcome,
@@ -706,6 +727,10 @@ export async function judgeSanitizeOutput(event, ext = {}) {
     const modified = fields !== null && Object.hasOwn(fields, "mutated_output");
     await ext.audit({
       tool: event.tool,
+      // The session identity travels in `meta`, not alongside the tool fields, so
+      // a recorder filing one trail per session cannot reach it unless it is
+      // lifted here.
+      session_id: event.meta?.session_id,
       modified,
       output: modified ? fields?.mutated_output : event.response,
       context: fields?.additional_context,
@@ -774,6 +799,8 @@ export async function cliMain(ext = {}) {
           "[SANITIZATION FAILED — original output suppressed for safety. Hook error: " +
             safeErrMessage(err) +
             "]",
+          undefined,
+          ext.remedy,
         ),
     },
   );

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

@@ -22,17 +22,20 @@ 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";
+import { bestEffortTrace, trace, TraceEvent } from "./lib/trace.mjs";
 // classifyPrompt (the user-prompt verdict) and stripAnsiFully (its ANSI stripper)
 // come from the agent-sanitizer package. They are bound by a *caught* dynamic
 // import, never a bare top-level `import … from "…"`: a static npm import
 // resolves before any try/catch, so a missing node_modules would crash this hook
 // at load and let the prompt through UNSANITIZED (fail-open). A failed load
-// leaves the bindings undefined, which main()'s typeof guard turns into a
-// fail-closed block.
+// leaves that binding undefined, which the judge's typeof guards turn into a
+// fail-closed block — one guard each, since the two loads succeed or fail
+// independently.
 /** @type {typeof import("agent-sanitizer/prompt").classifyPrompt} */
 export let classifyPrompt;
 /** @type {typeof import("agent-sanitizer").stripAnsiFully} */
@@ -49,6 +52,7 @@ let stripAnsiFully;
  *   blockContext: string,
  *   sgrNote: string,
  *   hookFailed: (cause: string) => string,
+ *   remedy: string,
  * }>}
  */
 export const USER_PROMPT_MESSAGES = Object.freeze({
@@ -59,24 +63,31 @@ export const USER_PROMPT_MESSAGES = Object.freeze({
     "The prompt contains ANSI SGR color codes (pasted terminal output). They are display-only formatting noise; read through them.",
   hookFailed: (cause) =>
     `sanitize-user-prompt hook failed (fail-closed): ${cause}`,
+  // What a reader should run when the package itself is what is missing. It
+  // rides in this table rather than a separate argument because it is host text
+  // exactly like the reasons above, and one channel means a host cannot supply
+  // its wording in one place and forget it in the other.
+  remedy: DEFAULT_MISSING_PACKAGE_REMEDY,
 });
 
 /* c8 ignore start — module-load boundary: the imports resolve in every real
  * run, and their failure (the package absent) can't be simulated in-process, so
- * neither arm is observable to the in-process tests. main()'s typeof guard
+ * neither arm is observable to the in-process tests. The judge's typeof guard
  * converts an undefined stripper into a fail-closed block — that guard IS tested. */
 // Stryker disable all
-try {
-  // The /prompt subpath is imported first: if it fails, the catch fires before
-  // stripAnsiFully is assigned, so a half-load can never leave the stripper set
-  // while the classifier is missing (main guards on the stripper alone).
-  ({ classifyPrompt } = await import("agent-sanitizer/prompt"));
-  ({ stripAnsiFully } = await import("agent-sanitizer"));
-} catch {
-  // Leave classifyPrompt/stripAnsiFully undefined so main()'s typeof guard fails
-  // closed — the prompt is blocked, never passed through with the package
-  // half-loaded.
-}
+// lazyImport rather than a bare `await import` in a try/catch: it RECORDS the
+// loader error, which is the only thing that can tell a missing install apart
+// from a present package missing an export. Discarding it leaves
+// missingPackageError with nothing to report but a guess.
+// The cast asserts the loaded SHAPE, not that it loaded: lazyImport yields {} on
+// failure, so either binding can still be undefined here — which is exactly what
+// the judge's typeof guard turns into a fail-closed block.
+({ classifyPrompt } = /** @type {typeof import("agent-sanitizer/prompt")} */ (
+  await lazyImport("agent-sanitizer/prompt")
+));
+({ stripAnsiFully } = /** @type {typeof import("agent-sanitizer")} */ (
+  await lazyImport("agent-sanitizer")
+));
 // Stryker restore all
 /* c8 ignore stop */
 
@@ -114,11 +125,21 @@ export function judgeSanitizeUserPrompt(
     return { decision: Decision.DENY, reason: messages.unknownEvent };
   if (event.event !== EventKind.PROMPT_SUBMIT)
     return { decision: Decision.ALLOW };
-  // The module-load guard: a missing stripper means agent-sanitizer never
-  // loaded. Guarding on the stripper alone is sufficient — it loads AFTER
-  // classifyPrompt in the same try, so a present stripper proves the classifier
-  // loaded too.
-  if (typeof strip !== "function") throw missingPackageError("agent-sanitizer");
+  // The module-load guard, one arm per binding. The two lazyImports are
+  // INDEPENDENT — each yields {} on its own failure — so a present stripper does
+  // not prove the classifier loaded, and guarding on it alone would let a
+  // classifier-only failure reach `classifyPrompt(...)` as a bare TypeError
+  // naming no package, no cause and no remedy: the exact diagnostic this hook
+  // now exists to produce. lazyImportErrorFor matches subpaths, so naming
+  // `agent-sanitizer/prompt` still recovers the recorded cause.
+  if (typeof strip !== "function")
+    throw missingPackageError("agent-sanitizer", undefined, messages.remedy);
+  if (typeof classifyPrompt !== "function")
+    throw missingPackageError(
+      "agent-sanitizer/prompt",
+      undefined,
+      messages.remedy,
+    );
   // The contract guarantees a string here: every adapter normalizes the
   // prompt-submit input (Claude's parse coerces a missing/non-string prompt to
   // "" via asString), so a defensive typeof re-check is a dead branch.
@@ -138,20 +159,30 @@ export function judgeSanitizeUserPrompt(
 }
 
 /**
+ * `read` and `write` stay positional — every caller supplies both — while the
+ * injectable seams ride in one bag, so a host supplying only the last of them does
+ * not have to pass `undefined` for the others.
  * @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
+ * @param {{
+ *   strip?: ((s: string) => string) | null,
+ *   overrides?: Partial<typeof USER_PROMPT_MESSAGES>,
+ *   trace?: import("./lib/trace.mjs").TraceFn,
+ * }} [opts]
+ *   `strip` is the ANSI stripper (defaults to the package's stripAnsiFully;
+ *   injectable so the fail-closed path is testable); `overrides` are reason
+ *   overrides, merged over the defaults so a partial table can never leave a field
+ *   unset; `trace` is where engagement is announced, for a host with its own trace
+ *   channel (see lib/trace.mjs).
  * @returns {Promise<void>}
  */
-export async function main(
-  read,
-  write,
-  strip = stripAnsiFully,
-  overrides = USER_PROMPT_MESSAGES,
-) {
+export async function main(read, write, opts = {}) {
+  const {
+    strip = stripAnsiFully,
+    overrides = USER_PROMPT_MESSAGES,
+    trace: sink = trace,
+  } = opts;
+  const emitTrace = bestEffortTrace(sink);
   // 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 };
@@ -168,7 +199,7 @@ export async function main(
       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, {
+      emitTrace(TraceEvent.HOOK_RAN, {
         hook: "sanitize-user-prompt",
         outcome:
           verdict.decision === controlPlane().Decision.DENY

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

@@ -21,7 +21,7 @@ import {
   ALERT_ACK_FILE,
   PROJECT_DIR,
 } from "./lib/invisible-alert.mjs";
-import { trace, TraceEvent } from "./lib/trace.mjs";
+import { bestEffortTrace, 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
@@ -271,9 +271,16 @@ function scanProject() {
  * the alert for the PreToolUse gate otherwise. Exported so a bundle entry
  * (which must claim the CLI slot before this module loads) can run the exact
  * same scan instead of duplicating it.
+ * @param {{ trace?: import("./lib/trace.mjs").TraceFn }} [opts]  `trace` is where
+ *   this scan announces engagement; a host with its own trace channel passes its
+ *   sink so the announcement lands where its detector reads (see lib/trace.mjs).
  * @returns {Promise<void>}
  */
-export async function cliMain() {
+export async function cliMain({ trace: sink = trace } = {}) {
+  // Bound best-effort: the announcements below run BEFORE the auto-clean and
+  // the alert write, with no catch above them, so a throwing host sink would
+  // abort the scan silently (see bestEffortTrace).
+  const emitTrace = bestEffortTrace(sink);
   /* 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. */
@@ -281,7 +288,7 @@ export async function cliMain() {
     // 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" });
+    emitTrace(TraceEvent.SCAN_INVISIBLE_CHARS_RAN, { outcome: "skipped" });
     process.stderr.write(
       "scan-invisible-chars: agent-sanitizer failed to load (node deps not " +
         "installed and session-setup did not finish in time); instruction " +
@@ -304,10 +311,10 @@ export async function cliMain() {
   const allFindings = scanProject();
 
   if (allFindings.length === 0) {
-    trace(TraceEvent.SCAN_INVISIBLE_CHARS_RAN, { outcome: "clean" });
+    emitTrace(TraceEvent.SCAN_INVISIBLE_CHARS_RAN, { outcome: "clean" });
     return;
   }
-  trace(TraceEvent.SCAN_INVISIBLE_CHARS_RAN, {
+  emitTrace(TraceEvent.SCAN_INVISIBLE_CHARS_RAN, {
     outcome: "found",
     files: allFindings.length,
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.9.0",
+  "version": "2.10.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": {

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

@@ -167,6 +167,24 @@ export function safeErrMessage(err: unknown, cap?: number): string;
  * @returns {void}
  */
 export function emitHookResponse(hookEventName: string, fields: Record<string, unknown>): void;
+/**
+ * Adopt a host's own cold-start marker path in place of the derived one, so a
+ * host whose setup script already writes a marker under its own convention can
+ * use these hooks without running a second, disagreeing wait loop against a path
+ * nothing writes.
+ *
+ * ORDERING, same rule as {@link registerLazyModules}: call this before importing
+ * any hook module. `lib/control-plane.mjs` resolves the marker at MODULE scope,
+ * so a call that lands after that import cannot reach the wait it was meant to
+ * steer. A late call is reported on stderr rather than thrown: a throw at a
+ * bundle entry's top level kills the hook process before it writes a response,
+ * and a hook that emits nothing is read as non-blocking — the fail-OPEN this
+ * whole file is built to avoid. The late call still takes effect for every
+ * later resolution.
+ * @param {string | null} path  absolute marker path, or null to restore the derivation
+ * @returns {void}
+ */
+export function configureHookgateMarker(path: string | null): 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)
@@ -178,7 +196,8 @@ export function emitHookResponse(hookEventName: string, fields: Record<string, u
  * 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).
+ * setup ran → nothing to wait on), or whatever a host set via
+ * {@link configureHookgateMarker}.
  * @param {string | undefined} [projectDir]
  * @param {string | undefined} [runtimeDir]
  * @returns {string | null}

package/types/claude-hooks/lib/trace.d.mts

@@ -14,8 +14,47 @@ export function traceThreshold(env?: NodeJS.ProcessEnv): number;
  * @returns {void}
  */
 export function trace(event: string, fields?: Record<string, unknown>, level?: "info" | "debug"): void;
+/**
+ * `sink` with {@link trace}'s best-effort posture forced onto it: a throw is
+ * swallowed, so an announcement can never break the hook making it.
+ *
+ * This is what makes the sink safely injectable. The announcement call sites were
+ * placed under the guarantee that emitting cannot fail, and one of them relies on
+ * it outright: scan-invisible-chars announces BEFORE it auto-cleans the
+ * contaminated instruction files and arms the PreToolUse gate, with no catch
+ * above it, so a throwing sink there would abort the scan — leaving the payload on
+ * disk, the gate un-armed, and NO announcement on any channel. The loss the
+ * announcement exists to make loud would itself be silent.
+ *
+ * Swallowing is right here and is not licence to swallow elsewhere in this tree:
+ * a dropped announcement is already loud in the host's own detector — that is what
+ * a trace channel is — whereas a killed hook is loud nowhere.
+ * @param {TraceFn} sink
+ * @returns {TraceFn}
+ */
+export function bestEffortTrace(sink: TraceFn): TraceFn;
+/**
+ * The sink shape a hook emits through: the event name, its metadata fields, and
+ * the level. A host implementation receives the same {@link TraceEvent} names the
+ * default emits, so it can remap them onto its own channel's vocabulary.
+ *
+ * A sink is NOT required to be total — throw freely. Every hook binds the one it
+ * was given through {@link bestEffortTrace}, which is what upholds the channel's
+ * never-breaks-a-hook posture on host code that cannot promise it.
+ * @typedef {(event: string, fields?: Record<string, unknown>, level?: "info"|"debug") => void} TraceFn
+ */
 /** Trace-channel event names. */
 export const TraceEvent: Readonly<{
     HOOK_RAN: "hook_ran";
     SCAN_INVISIBLE_CHARS_RAN: "scan_invisible_chars_ran";
 }>;
+/**
+ * The sink shape a hook emits through: the event name, its metadata fields, and
+ * the level. A host implementation receives the same {@link TraceEvent} names the
+ * default emits, so it can remap them onto its own channel's vocabulary.
+ *
+ * A sink is NOT required to be total — throw freely. Every hook binds the one it
+ * was given through {@link bestEffortTrace}, which is what upholds the channel's
+ * never-breaks-a-hook posture on host code that cannot promise it.
+ */
+export type TraceFn = (event: string, fields?: Record<string, unknown>, level?: "info" | "debug") => void;

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

@@ -6,9 +6,11 @@
  * @param {(tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>} [rehydrate]
  * injectable for tests; the default binds the real redactor-daemon io (the
  * layer reads the target file and maps secrets through the daemon)
+ * @param {import("./lib/trace.mjs").TraceFn} [sink]  where engagement is
+ * announced; a host with its own trace channel passes its sink (see lib/trace.mjs)
  * @returns {Promise<Record<string, unknown> | null>}
  */
-export function buildPreToolUseResponse(input: any, rehydrate?: (tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>): Promise<Record<string, unknown> | null>;
+export function buildPreToolUseResponse(input: any, rehydrate?: (tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>, sink?: import("./lib/trace.mjs").TraceFn): Promise<Record<string, unknown> | null>;
 /**
  * Agent-agnostic judge over the four protections: consumes a control-plane
  * ToolCallEvent and returns a Verdict, so a non-Claude host can run the same
@@ -19,13 +21,18 @@ 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]
+ * @param {{
+ *   messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>,
+ *   gates?: HostGate[],
+ *   trace?: import("./lib/trace.mjs").TraceFn,
+ * }} [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>, opts?: {
     messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>;
     gates?: HostGate[];
+    trace?: import("./lib/trace.mjs").TraceFn;
 }): Promise<import("agent-control-plane-core").Verdict>;
 /**
  * The dependency-load failure hiding behind a hook error, or "". A binding that
@@ -67,14 +74,14 @@ export function failClosedFields(parsedOk: boolean, err: unknown, opts?: {
  * @param {{
  *   messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>,
  *   gates?: HostGate[],
- *   remedy?: string,
+ *   trace?: import("./lib/trace.mjs").TraceFn,
  * }} [opts]
  * @returns {Promise<void>}
  */
 export function cliMain(opts?: {
     messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>;
     gates?: HostGate[];
-    remedy?: string;
+    trace?: import("./lib/trace.mjs").TraceFn;
 }): Promise<void>;
 /**
  * A host-supplied deny gate: given the PreToolUse input, the reason this call
@@ -93,12 +100,14 @@ export function cliMain(opts?: {
  *   unknownEvent: string,
  *   failed: (cause: string) => string,
  *   unparsable: (cause: string) => string,
+ *   remedy: string,
  * }>}
  */
 export const PRE_TOOL_USE_MESSAGES: Readonly<{
     unknownEvent: string;
     failed: (cause: string) => string;
     unparsable: (cause: string) => string;
+    remedy: string;
 }>;
 /**
  * A host-supplied deny gate: given the PreToolUse input, the reason this call

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

@@ -27,9 +27,22 @@
  * @property {(raw: string) => string | undefined} [redactNote]
  *   Given the pre-redaction text of a leaf that tripped Layer 4, returns a note
  *   appended to that leaf's "API keys/secrets redacted: …" warning.
- * @property {(record: { tool: string | null, modified: boolean, output: unknown, context?: string }) => Promise<void> | void} [audit]
+ * @property {(record: { tool: string | null, session_id?: string, 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.
+ *   the model will actually see. `session_id` is the harness's session identity,
+ *   lifted from the event's `meta` — an audit trail that cannot say WHICH session
+ *   produced a record cannot be read back per-session, and the tool fields alone
+ *   do not carry it. Absent when the payload omitted it.
+ * @property {import("./lib/trace.mjs").TraceFn} [trace]
+ *   Where this hook announces engagement. A host that already runs a trace
+ *   channel under its own environment variables passes its sink here, so the
+ *   announcement lands where its detector reads instead of on this package's
+ *   channel. Defaults to lib/trace.mjs's `trace`.
+ * @property {string} [remedy]
+ *   What a reader should run when the sanitizer's own bindings are what is
+ *   missing. This hook's host channel is `ext`, where the other two gates use a
+ *   frozen message table; either way it is one channel per gate, so a host
+ *   cannot supply its wording somewhere the fail-closed context never reads.
  */
 /**
  * Run Layers 1-4 over a single text blob, delegated to the package's output seam
@@ -142,9 +155,10 @@ export function failClosedContext(depsLoaded?: () => boolean, remedy?: string):
  * @param {any} input  parsed hook input, or undefined if parsing threw
  * @param {string} message
  * @param {(fields: Record<string, unknown>) => void} [emit]
+ * @param {string} [remedy]  what a reader should run; hosts pass their own
  * @returns {void}
  */
-export function emitFailClosed(input: any, message: string, emit?: (fields: Record<string, unknown>) => void): void;
+export function emitFailClosed(input: any, message: string, emit?: (fields: Record<string, unknown>) => void, remedy?: string): void;
 /**
  * Run the sanitization pipeline over a tool output and return the contract-
  * shaped verdict fields — `mutated_output` (the shape-matching sanitized value)
@@ -258,12 +272,30 @@ export type SanitizeExtensions = {
     redactNote?: ((raw: string) => string | undefined) | undefined;
     /**
      * Awaited once per judged event that carried a tool response, with the output
-     * the model will actually see.
+     * the model will actually see. `session_id` is the harness's session identity,
+     * lifted from the event's `meta` — an audit trail that cannot say WHICH session
+     * produced a record cannot be read back per-session, and the tool fields alone
+     * do not carry it. Absent when the payload omitted it.
      */
     audit?: ((record: {
         tool: string | null;
+        session_id?: string;
         modified: boolean;
         output: unknown;
         context?: string;
     }) => Promise<void> | void) | undefined;
+    /**
+     * Where this hook announces engagement. A host that already runs a trace
+     * channel under its own environment variables passes its sink here, so the
+     * announcement lands where its detector reads instead of on this package's
+     * channel. Defaults to lib/trace.mjs's `trace`.
+     */
+    trace?: import("./lib/trace.mjs").TraceFn | undefined;
+    /**
+     * What a reader should run when the sanitizer's own bindings are what is
+     * missing. This hook's host channel is `ext`, where the other two gates use a
+     * frozen message table; either way it is one channel per gate, so a host
+     * cannot supply its wording somewhere the fail-closed context never reads.
+     */
+    remedy?: string | undefined;
 };

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

@@ -14,15 +14,28 @@
  */
 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;
 /**
+ * `read` and `write` stay positional — every caller supplies both — while the
+ * injectable seams ride in one bag, so a host supplying only the last of them does
+ * not have to pass `undefined` for the others.
  * @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
+ * @param {{
+ *   strip?: ((s: string) => string) | null,
+ *   overrides?: Partial<typeof USER_PROMPT_MESSAGES>,
+ *   trace?: import("./lib/trace.mjs").TraceFn,
+ * }} [opts]
+ *   `strip` is the ANSI stripper (defaults to the package's stripAnsiFully;
+ *   injectable so the fail-closed path is testable); `overrides` are reason
+ *   overrides, merged over the defaults so a partial table can never leave a field
+ *   unset; `trace` is where engagement is announced, for a host with its own trace
+ *   channel (see lib/trace.mjs).
  * @returns {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>;
+export function main(read: () => Promise<any> | any, write: (chunk: string) => void, opts?: {
+    strip?: ((s: string) => string) | null;
+    overrides?: Partial<typeof USER_PROMPT_MESSAGES>;
+    trace?: import("./lib/trace.mjs").TraceFn;
+}): Promise<void>;
 /** @type {typeof import("agent-sanitizer/prompt").classifyPrompt} */
 export let classifyPrompt: typeof import("agent-sanitizer/prompt").classifyPrompt;
 /**
@@ -36,6 +49,7 @@ export let classifyPrompt: typeof import("agent-sanitizer/prompt").classifyPromp
  *   blockContext: string,
  *   sgrNote: string,
  *   hookFailed: (cause: string) => string,
+ *   remedy: string,
  * }>}
  */
 export const USER_PROMPT_MESSAGES: Readonly<{
@@ -43,4 +57,5 @@ export const USER_PROMPT_MESSAGES: Readonly<{
     blockContext: string;
     sgrNote: string;
     hookFailed: (cause: string) => string;
+    remedy: string;
 }>;

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

@@ -3,9 +3,14 @@
  * the alert for the PreToolUse gate otherwise. Exported so a bundle entry
  * (which must claim the CLI slot before this module loads) can run the exact
  * same scan instead of duplicating it.
+ * @param {{ trace?: import("./lib/trace.mjs").TraceFn }} [opts]  `trace` is where
+ *   this scan announces engagement; a host with its own trace channel passes its
+ *   sink so the announcement lands where its detector reads (see lib/trace.mjs).
  * @returns {Promise<void>}
  */
-export function cliMain(): Promise<void>;
+export function cliMain({ trace: sink }?: {
+    trace?: import("./lib/trace.mjs").TraceFn;
+}): Promise<void>;
 /**
  * @param {string} run
  * @returns {{ method: string, decoded: string }}