agent-sanitizer 2.9.1 → 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/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";
 
@@ -150,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;
 }
 
@@ -173,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 = [];
 
@@ -227,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,
     });
@@ -238,6 +245,7 @@ export async function buildPreToolUseResponse(
   }
 
   return emitTraced(
+    emitTrace,
     input.tool_name,
     assembleResponse({ changed, current, asks, contexts, pendingGateAck }),
   );
@@ -290,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
@@ -327,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 = {
@@ -419,15 +431,21 @@ export function failClosedFields(parsedOk, err, opts = {}) {
  * @param {{
  *   messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>,
  *   gates?: HostGate[],
+ *   trace?: import("./lib/trace.mjs").TraceFn,
  * }} [opts]
  * @returns {Promise<void>}
  */
 export async function cliMain(opts = {}) {
-  const { gates = [] } = 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

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,17 @@ 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
@@ -572,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,
@@ -716,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,

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

@@ -27,7 +27,7 @@ import {
   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
@@ -159,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 };
@@ -189,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.1",
+  "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,12 +74,14 @@ export function failClosedFields(parsedOk: boolean, err: unknown, opts?: {
  * @param {{
  *   messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>,
  *   gates?: HostGate[],
+ *   trace?: import("./lib/trace.mjs").TraceFn,
  * }} [opts]
  * @returns {Promise<void>}
  */
 export function cliMain(opts?: {
     messages?: Partial<typeof PRE_TOOL_USE_MESSAGES>;
     gates?: HostGate[];
+    trace?: import("./lib/trace.mjs").TraceFn;
 }): Promise<void>;
 /**
  * A host-supplied deny gate: given the PreToolUse input, the reason this call

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

@@ -27,9 +27,17 @@
  * @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
@@ -264,14 +272,25 @@ 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

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;
 /**

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 }}