agent-sanitizer 2.13.0 → 2.14.0

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

@@ -12,7 +12,106 @@ import { userInfo } from "node:os";
 import { createHash } from "node:crypto";
 import { pathToFileURL } from "node:url";
 
-let cliEntryClaimed = false;
+/**
+ * EVERY process-wide slot these helpers keep — the four a host can observe or
+ * steer, so a second instance that adopts this object is steered in all four at
+ * once. A slot left off this object is one a host must configure per instance,
+ * and forgetting the second call fails silently; that is the whole failure class
+ * {@link adoptHookIoSharedState} exists to remove, so the object is complete
+ * rather than covering only the registry.
+ *
+ * - `lazyModules` — the namespaces {@link lazyImport} answers from. Empty when
+ *   the hooks run from source; a build-time BUNDLE (which ships with no
+ *   node_modules for the runtime `import()` to resolve) statically imports its
+ *   packages and registers them here before importing the hooks that lazy-load
+ *   them, so the same hook source runs unchanged in both worlds.
+ * - `cliEntryClaimed` — the CLI-entry latch {@link isMain} reads.
+ * - `missingPackageRemedy` — the host remedy {@link configureMissingPackageRemedy}
+ *   sets; null keeps {@link DEFAULT_MISSING_PACKAGE_REMEDY}.
+ * - `hookgateMarker` — the marker path {@link configureHookgateMarker} sets, and
+ *   `hookgateMarkerResolved`, the latch that makes a too-late call say so.
+ * @typedef {{
+ *   lazyModules: Record<string, Record<string, any>>,
+ *   cliEntryClaimed: boolean,
+ *   missingPackageRemedy: string | null,
+ *   hookgateMarker: string | null,
+ *   hookgateMarkerResolved: boolean,
+ * }} HookIoSharedState
+ */
+
+/** @type {HookIoSharedState} */
+let shared = {
+  lazyModules: Object.create(null),
+  cliEntryClaimed: false,
+  missingPackageRemedy: null,
+  hookgateMarker: null,
+  hookgateMarkerResolved: false,
+};
+
+/**
+ * This instance's state object, for a host to hand to another instance.
+ * @returns {HookIoSharedState}
+ */
+export function hookIoSharedState() {
+  return shared;
+}
+
+/**
+ * Route every slot of {@link HookIoSharedState} on this instance through `state`.
+ *
+ * A host that ships its OWN hook-io module beside the packaged hooks ends up
+ * with two instances of this file's state in one process, each with its own
+ * registry and its own latches. Without this seam the host configures each slot
+ * twice, and a slot it sets on only one instance is invisible to the readers on
+ * the other. For the registry that means those readers resolve a specifier at
+ * RUNTIME, inside a bundle with no node_modules, and the gate fails closed on
+ * every call. Adopting one state object removes that failure mode rather than
+ * policing it.
+ *
+ * WHY AN API AND NOT A BUNDLER ALIAS: collapsing the two module records at build
+ * time (an esbuild `alias` from the host's module to this one) is the cheaper
+ * fix and needs no API — but it works only when the host's module is a COPY of
+ * this one. The motivating host's is not: it exports names this module does not
+ * have and lacks names this one exports, so an alias breaks every call site of
+ * the difference. `test/claude-hooks-exports.test.mjs` still states the rule for
+ * a true copy — share this module, never duplicate it. This seam serves the
+ * other case, a host with its own module that must agree with ours on state.
+ *
+ * Call it before importing any module that reads a slot, for the same reason
+ * {@link registerLazyModules} carries that rule: a reader binds at its own
+ * module scope.
+ *
+ * Slots already set on EITHER side survive: this instance's registrations and
+ * latches carry over, and a value already present in `state` wins, since it is
+ * the adopted root's own choice. Adopting the state this instance already holds
+ * is a no-op.
+ *
+ * CONSTRAINT: every instance must adopt the same root object, and none may adopt
+ * a second, different one. `shared` is reassigned, so a later `B.adopt(C)` would
+ * leave an earlier `A.adopt(B)` pointing at an abandoned object whose readers
+ * nothing reaches. This is not enforced with a throw: callers are bundle entry
+ * points, and a throw at their top level kills the hook before it writes a
+ * response — a hook that emits nothing reads as non-blocking, which is the
+ * fail-OPEN this whole module is built to avoid.
+ * @param {HookIoSharedState} state
+ * @returns {void}
+ */
+export function adoptHookIoSharedState(state) {
+  if (state === shared) return;
+  for (const [specifier, namespace] of Object.entries(shared.lazyModules))
+    if (state.lazyModules[specifier] === undefined)
+      state.lazyModules[specifier] = namespace;
+  if (shared.cliEntryClaimed) state.cliEntryClaimed = true;
+  if (
+    shared.missingPackageRemedy !== null &&
+    state.missingPackageRemedy === null
+  )
+    state.missingPackageRemedy = shared.missingPackageRemedy;
+  if (shared.hookgateMarker !== null && state.hookgateMarker === null)
+    state.hookgateMarker = shared.hookgateMarker;
+  if (shared.hookgateMarkerResolved) state.hookgateMarkerResolved = true;
+  shared = state;
+}
 
 /**
  * True when this module is the process entry point (run directly as a CLI, not
@@ -29,7 +128,7 @@ export function isMain(importMetaUrl) {
   // alongside the real entry's and consume its stdin. An entry that claimed the
   // CLI slot (claimCliEntry) therefore makes every later isMain call answer
   // false — module bodies run in dependency order, so the claim lands first.
-  if (cliEntryClaimed) return false;
+  if (shared.cliEntryClaimed) return false;
   return (
     Boolean(process.argv[1]) &&
     importMetaUrl === pathToFileURL(process.argv[1]).href
@@ -43,7 +142,7 @@ export function isMain(importMetaUrl) {
  * @returns {void}
  */
 export function claimCliEntry() {
-  cliEntryClaimed = true;
+  shared.cliEntryClaimed = true;
 }
 
 /**
@@ -121,17 +220,6 @@ export async function readStdinJson(maxBytes = MAX_STDIN_BYTES) {
   return JSON.parse((await readAllBounded(process.stdin, maxBytes)).toString());
 }
 
-/**
- * Pre-registered module namespaces consulted by {@link lazyImport} before it
- * dials the loader. Empty when the hooks run from source; a build-time BUNDLE
- * (which ships with no node_modules for the runtime `import()` to resolve)
- * statically imports its packages and registers them here before importing the
- * hooks that lazy-load them, so the same hook source runs unchanged in both
- * worlds.
- * @type {Record<string, Record<string, any>>}
- */
-const registeredLazyModules = Object.create(null);
-
 /**
  * Register already-loaded module namespaces for {@link lazyImport} to return in
  * place of a runtime dynamic import. Call before importing any module that
@@ -140,7 +228,7 @@ const registeredLazyModules = Object.create(null);
  * @returns {void}
  */
 export function registerLazyModules(modules) {
-  Object.assign(registeredLazyModules, modules);
+  Object.assign(shared.lazyModules, modules);
 }
 
 /**
@@ -153,7 +241,7 @@ export function registerLazyModules(modules) {
  * @returns {Record<string, any> | undefined}
  */
 export function registeredLazyModule(specifier) {
-  return registeredLazyModules[specifier];
+  return shared.lazyModules[specifier];
 }
 
 /**
@@ -178,7 +266,7 @@ const lazyImportErrors = new Map();
  * @returns {Promise<Record<string, any>>}
  */
 export async function lazyImport(specifier) {
-  const registered = registeredLazyModules[specifier];
+  const registered = shared.lazyModules[specifier];
   if (registered) {
     lazyImportErrors.delete(specifier);
     return registered;
@@ -241,13 +329,6 @@ export function failedLazyPackages() {
 export const DEFAULT_MISSING_PACKAGE_REMEDY =
   "reinstall the hook dependencies (pnpm install) and retry.";
 
-/**
- * Host-supplied default remedy, replacing DEFAULT_MISSING_PACKAGE_REMEDY. Null
- * (the default) keeps the package's wording.
- * @type {string | null}
- */
-let missingPackageRemedyOverride = null;
-
 /**
  * Adopt a host's own remedy as the default {@link missingPackageMessage} and
  * {@link missingPackageError} state when their caller passes none. This refusal
@@ -265,7 +346,7 @@ let missingPackageRemedyOverride = null;
  * @returns {void}
  */
 export function configureMissingPackageRemedy(remedy) {
-  missingPackageRemedyOverride = remedy;
+  shared.missingPackageRemedy = remedy;
 }
 
 /**
@@ -284,7 +365,7 @@ export function configureMissingPackageRemedy(remedy) {
 export function missingPackageMessage(
   pkg,
   err = lazyImportErrorFor(pkg),
-  remedy = missingPackageRemedyOverride ?? DEFAULT_MISSING_PACKAGE_REMEDY,
+  remedy = shared.missingPackageRemedy ?? DEFAULT_MISSING_PACKAGE_REMEDY,
 ) {
   const prefix = `${pkg} is unavailable: `;
   // 2 for the "; " joiner; 12 for safeErrMessage's own "…[truncated]" marker,
@@ -314,7 +395,7 @@ export function missingPackageMessage(
 export function missingPackageError(
   pkg,
   err = lazyImportErrorFor(pkg),
-  remedy = missingPackageRemedyOverride ?? DEFAULT_MISSING_PACKAGE_REMEDY,
+  remedy = shared.missingPackageRemedy ?? DEFAULT_MISSING_PACKAGE_REMEDY,
 ) {
   return Object.assign(new Error(missingPackageMessage(pkg, err, remedy)), {
     code: "DEP_UNAVAILABLE",
@@ -421,16 +502,6 @@ 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
@@ -449,13 +520,13 @@ let hookgateMarkerResolved = false;
  * @returns {void}
  */
 export function configureHookgateMarker(path) {
-  if (hookgateMarkerResolved)
+  if (shared.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;
+  shared.hookgateMarker = path;
 }
 
 /**
@@ -479,8 +550,8 @@ export function hookgateMarkerPath(
   projectDir = process.env.CLAUDE_PROJECT_DIR,
   runtimeDir = process.env.XDG_RUNTIME_DIR,
 ) {
-  hookgateMarkerResolved = true;
-  if (hookgateMarkerOverride !== null) return hookgateMarkerOverride;
+  shared.hookgateMarkerResolved = true;
+  if (shared.hookgateMarker !== null) return shared.hookgateMarker;
   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/package.json

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

@@ -1,3 +1,49 @@
+/**
+ * This instance's state object, for a host to hand to another instance.
+ * @returns {HookIoSharedState}
+ */
+export function hookIoSharedState(): HookIoSharedState;
+/**
+ * Route every slot of {@link HookIoSharedState} on this instance through `state`.
+ *
+ * A host that ships its OWN hook-io module beside the packaged hooks ends up
+ * with two instances of this file's state in one process, each with its own
+ * registry and its own latches. Without this seam the host configures each slot
+ * twice, and a slot it sets on only one instance is invisible to the readers on
+ * the other. For the registry that means those readers resolve a specifier at
+ * RUNTIME, inside a bundle with no node_modules, and the gate fails closed on
+ * every call. Adopting one state object removes that failure mode rather than
+ * policing it.
+ *
+ * WHY AN API AND NOT A BUNDLER ALIAS: collapsing the two module records at build
+ * time (an esbuild `alias` from the host's module to this one) is the cheaper
+ * fix and needs no API — but it works only when the host's module is a COPY of
+ * this one. The motivating host's is not: it exports names this module does not
+ * have and lacks names this one exports, so an alias breaks every call site of
+ * the difference. `test/claude-hooks-exports.test.mjs` still states the rule for
+ * a true copy — share this module, never duplicate it. This seam serves the
+ * other case, a host with its own module that must agree with ours on state.
+ *
+ * Call it before importing any module that reads a slot, for the same reason
+ * {@link registerLazyModules} carries that rule: a reader binds at its own
+ * module scope.
+ *
+ * Slots already set on EITHER side survive: this instance's registrations and
+ * latches carry over, and a value already present in `state` wins, since it is
+ * the adopted root's own choice. Adopting the state this instance already holds
+ * is a no-op.
+ *
+ * CONSTRAINT: every instance must adopt the same root object, and none may adopt
+ * a second, different one. `shared` is reassigned, so a later `B.adopt(C)` would
+ * leave an earlier `A.adopt(B)` pointing at an abandoned object whose readers
+ * nothing reaches. This is not enforced with a throw: callers are bundle entry
+ * points, and a throw at their top level kills the hook before it writes a
+ * response — a hook that emits nothing reads as non-blocking, which is the
+ * fail-OPEN this whole module is built to avoid.
+ * @param {HookIoSharedState} state
+ * @returns {void}
+ */
+export function adoptHookIoSharedState(state: HookIoSharedState): void;
 /**
  * True when this module is the process entry point (run directly as a CLI, not
  * imported). Guards an undefined `process.argv[1]` (e.g. the REPL) before
@@ -349,3 +395,29 @@ export const MAX_STDIN_BYTES: number;
  * command the reader should actually run.
  */
 export const DEFAULT_MISSING_PACKAGE_REMEDY: "reinstall the hook dependencies (pnpm install) and retry.";
+/**
+ * EVERY process-wide slot these helpers keep — the four a host can observe or
+ * steer, so a second instance that adopts this object is steered in all four at
+ * once. A slot left off this object is one a host must configure per instance,
+ * and forgetting the second call fails silently; that is the whole failure class
+ * {@link adoptHookIoSharedState} exists to remove, so the object is complete
+ * rather than covering only the registry.
+ *
+ * - `lazyModules` — the namespaces {@link lazyImport} answers from. Empty when
+ *   the hooks run from source; a build-time BUNDLE (which ships with no
+ *   node_modules for the runtime `import()` to resolve) statically imports its
+ *   packages and registers them here before importing the hooks that lazy-load
+ *   them, so the same hook source runs unchanged in both worlds.
+ * - `cliEntryClaimed` — the CLI-entry latch {@link isMain} reads.
+ * - `missingPackageRemedy` — the host remedy {@link configureMissingPackageRemedy}
+ *   sets; null keeps {@link DEFAULT_MISSING_PACKAGE_REMEDY}.
+ * - `hookgateMarker` — the marker path {@link configureHookgateMarker} sets, and
+ *   `hookgateMarkerResolved`, the latch that makes a too-late call say so.
+ */
+export type HookIoSharedState = {
+    lazyModules: Record<string, Record<string, any>>;
+    cliEntryClaimed: boolean;
+    missingPackageRemedy: string | null;
+    hookgateMarker: string | null;
+    hookgateMarkerResolved: boolean;
+};