agent-sanitizer 2.12.0 → 2.14.0

package/claude-hooks/lib/env-config.mjs

@@ -17,6 +17,10 @@
  * rather than at module load where a throw would abort before that catch installs
  * and let the harness pass the tool output through UNSANITIZED (fail OPEN).
  */
+// The package's own subpath, so the bundle resolves it through the pinned
+// engine alias and an external consumer resolves the same specifier.
+import { credentialNameMatcher } from "agent-sanitizer/credential-names-matcher";
+
 import credentialNames from "../../python/agent_sanitizer/secrets/data/credential-names.json" with { type: "json" };
 import inferenceKeys from "../config/inference-key-vars.json" with { type: "json" };
 import scrubbed from "../config/scrubbed-env-vars.json" with { type: "json" };
@@ -127,147 +131,29 @@ function hostExtraSecretVars() {
   return vars;
 }
 
-// A rendered vocabulary token. Restricting it to A-Z/0-9/_ is what lets the
-// regexes below interpolate it unescaped: a stray metacharacter (or an empty
-// list, which would make the match regex accept nothing and leak every forwarded
-// credential) fails closed here instead of silently under-matching. Digits are
-// admitted because a noun part may legitimately carry one (the vocabulary's parts
-// are `[a-z0-9]+`); a digit cannot be a metacharacter, so it is safe to embed.
-const CRED_TOKEN_RE = /^[A-Z0-9_]+$/;
-
-const VOCAB_LABEL = "credential-names.json";
-
-// Names ending in a credential noun whose value is not a secret. SSH_AUTH_SOCK
-// holds a filesystem path, and redacting it would strip the agent socket out of
-// tool output. Site-independent (anyone running an ssh-agent has it), so it lives
-// with the consumer rather than in the published vocabulary, which describes
-// which WORDS name a secret and cannot know about a specific variable.
-const EXCLUDE_NAMES = ["SSH_AUTH_SOCK"];
-
-// Which noun renderings apply to a variable NAME (the other use, `field-value`,
-// feeds the redactor's `field = value` matcher and is not a name matcher).
-const ENV_NAME_USE = "env-name";
-
-/**
- * The whole-name forms of `parts`: underscore-joined and bare-joined, upper-cased.
- * Both are emitted because both spellings occur in the wild (`API_KEY`, `APIKEY`)
- * and a matcher anchored on underscore-delimited segments sees them as different
- * tokens; a single-part noun collapses to one form. Mirrors the Python renderer
- * (`_segment_forms` in agent_sanitizer/secrets/credential_names.py) so the two
- * ecosystems derive the same vocabulary from the same file.
- * @param {string[]} parts
- * @returns {string[]}
- */
-function segmentForms(parts) {
-  return [
-    ...new Set([parts.join("_").toUpperCase(), parts.join("").toUpperCase()]),
-  ];
-}
-
-/**
- * Render the published credential-noun vocabulary into the name-matcher spec:
- * the credential segments, and the trailing suffixes that mark a
- * credential-shaped name as holding a non-secret.
- *
- * The vocabulary is the SINGLE source both ecosystems read — a curated second
- * copy of these renderings is what let this matcher fall twelve segments behind
- * the engine, so a variable named `…_ACCESS_TOKEN` was never recognized as
- * credential-bearing and its value was never handed to the redactor.
- * @param {Record<string, any>} spec
- * @returns {{ segments: string[], excludeSuffixes: string[], excludeNames: string[] }}
- */
-export function deriveCredentialVocabulary(spec) {
-  const nouns = spec?.nouns;
-  const nonSecret = spec?.nonSecretSuffixes;
-  if (!Array.isArray(nouns) || !Array.isArray(nonSecret))
-    throw new Error(`${VOCAB_LABEL}: nouns/nonSecretSuffixes missing`);
-  const segments = [];
-  for (const noun of nouns)
-    if (Array.isArray(noun?.uses) && noun.uses.includes(ENV_NAME_USE))
-      segments.push(...segmentForms(parts(noun.parts, "nouns[].parts")));
-  // Rendered WITHOUT a leading underscore; the boundary is applied in the regex
-  // below, symmetrically with the match pattern. Baking `_` into the token makes
-  // the exclusion reachable only when something precedes the run, so a variable
-  // named exactly `PUBLIC_KEY` matched on its trailing `KEY` and never reached
-  // its exclusion — its value was then cut out of every tool output carrying it.
-  const excludeSuffixes = nonSecret.flatMap((suffix) =>
-    segmentForms(parts(suffix, "nonSecretSuffixes[]")),
-  );
-  return {
-    segments: [...new Set(segments)],
-    excludeSuffixes: [...new Set(excludeSuffixes)],
-    excludeNames: EXCLUDE_NAMES,
-  };
-}
-
+/** @type {((name: string) => boolean) | undefined} */
+let _credentialRule;
 /**
- * `value` as a validated non-empty array of lower-case noun parts, or throw. A
- * malformed part must not render into a token that silently under-matches.
- * @param {unknown} value
- * @param {string} field
- * @returns {string[]}
- */
-function parts(value, field) {
-  if (!Array.isArray(value) || value.length === 0)
-    throw new Error(`${VOCAB_LABEL}: ${field} is empty or missing`);
-  for (const part of value)
-    if (typeof part !== "string" || !/^[a-z0-9]+$/u.test(part))
-      throw new Error(`${VOCAB_LABEL}: bad part ${part} in ${field}`);
-  return value;
-}
-
-/**
- * The validated token list under `field`, or throw. An absent, empty, or
- * metacharacter-bearing list must not degrade into a pattern that matches nothing,
- * which would leak every forwarded credential.
- * @param {Record<string, unknown>} spec
- * @param {string} field
- * @returns {string[]}
- */
-function credentialTokens(spec, field) {
-  const group = spec[field];
-  if (!Array.isArray(group) || group.length === 0)
-    throw new Error(`${VOCAB_LABEL}: ${field} is empty or missing`);
-  for (const token of group)
-    if (typeof token !== "string" || !CRED_TOKEN_RE.test(token))
-      throw new Error(`${VOCAB_LABEL}: bad token ${token} in ${field}`);
-  return group;
-}
-
-/**
- * Validate a rendered name-matcher spec and build its match/exclude regexes. Pure
- * and exported so the fail-closed paths can be driven directly with a bad spec.
- * @param {Record<string, unknown>} spec
- * @returns {{ match: RegExp, exclude: RegExp }}
- */
-export function buildCredentialNameRes(spec) {
-  const segments = credentialTokens(spec, "segments");
-  const excludeSuffixes = credentialTokens(spec, "excludeSuffixes");
-  const excludeNames = credentialTokens(spec, "excludeNames");
-  return {
-    match: new RegExp(`(?:^|_)(?:${segments.join("|")})$`, "i"),
-    exclude: new RegExp(
-      `(?:^|_)(?:${excludeSuffixes.join("|")})$|^(?:${excludeNames.join("|")})$`,
-      "i",
-    ),
-  };
-}
-
-/** @type {{ match: RegExp, exclude: RegExp } | undefined} */
-let _credentialNameRes;
-/**
- * The credential-var-NAME regexes, memoized after the first build. Matching by
+ * The credential-var-NAME predicate, memoized after the first build. Matching by
  * trailing segment lets the redaction set self-populate with any token the
  * process actually holds; a curated list drifts. The curated sets
  * (inferenceKeyVars + scrubbed vars) stay the guaranteed floor; this only ADDS
  * lookalikes.
- * @returns {{ match: RegExp, exclude: RegExp }}
- */
-function credentialNameRes() {
-  if (_credentialNameRes !== undefined) return _credentialNameRes;
-  return (_credentialNameRes = buildCredentialNameRes(
-    deriveCredentialVocabulary(credentialNames),
-  ));
+ *
+ * credentialNameMatcher is the package's one credential-name decision. A second
+ * derivation here is how this module came to apply the vocabulary's non-secret
+ * runs only when something preceded them, so a variable named exactly
+ * `PUBLIC_KEY` was reported credential-bearing and its value cut out of every
+ * tool output carrying it. One decision means the two cannot disagree again.
+ * @returns {(name: string) => boolean}
+ */
+function credentialRule() {
+  if (_credentialRule !== undefined) return _credentialRule;
+  return (_credentialRule = credentialNameMatcher({
+    spec: credentialNames,
+    scope: "trailing",
+    declineNonSecret: true,
+  }));
 }
 
 /**
@@ -277,8 +163,7 @@ function credentialNameRes() {
  * @returns {boolean}
  */
 export function looksLikeCredentialVar(name) {
-  const res = credentialNameRes();
-  return res.match.test(name) && !res.exclude.test(name);
+  return credentialRule()(name);
 }
 
 /**
@@ -303,9 +188,9 @@ export function dynamicSecretVars(env = process.env) {
 // the set without this.
 const EXTRA_SECRET_VARS_ENV = "_AGENT_SANITIZER_EXTRA_SECRET_VARS";
 
-// Digits allowed here but not in CRED_TOKEN_RE: that one gates regex-interpolated
-// name SEGMENTS, while these are whole variable names an operator typed, and real
-// ones carry digits (`AWS_S3_KEY2`). Both exclude metacharacters.
+// These are whole variable names an operator typed, and real ones carry digits
+// (`AWS_S3_KEY2`); metacharacters stay excluded so a malformed entry fails
+// closed rather than widening the set.
 const EXTRA_TOKEN_RE = /^[A-Z0-9_]+$/;
 
 /**

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.12.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": {
@@ -46,7 +46,7 @@
     ]
   },
   "devDependencies": {
-    "sanitizer-engine": "npm:agent-sanitizer@2.1.0",
+    "sanitizer-engine": "npm:agent-sanitizer@2.12.0",
     "@commitlint/cli": "^21.0.1",
     "@commitlint/config-conventional": "^21.0.1",
     "@eslint/js": "10.0.1",

package/types/claude-hooks/lib/env-config.d.mts

@@ -34,33 +34,6 @@ export function configureEnvConfigSource(source: {
  * @returns {number}
  */
 export function minEnvSecretLen(): number;
-/**
- * Render the published credential-noun vocabulary into the name-matcher spec:
- * the credential segments, and the trailing suffixes that mark a
- * credential-shaped name as holding a non-secret.
- *
- * The vocabulary is the SINGLE source both ecosystems read — a curated second
- * copy of these renderings is what let this matcher fall twelve segments behind
- * the engine, so a variable named `…_ACCESS_TOKEN` was never recognized as
- * credential-bearing and its value was never handed to the redactor.
- * @param {Record<string, any>} spec
- * @returns {{ segments: string[], excludeSuffixes: string[], excludeNames: string[] }}
- */
-export function deriveCredentialVocabulary(spec: Record<string, any>): {
-    segments: string[];
-    excludeSuffixes: string[];
-    excludeNames: string[];
-};
-/**
- * Validate a rendered name-matcher spec and build its match/exclude regexes. Pure
- * and exported so the fail-closed paths can be driven directly with a bad spec.
- * @param {Record<string, unknown>} spec
- * @returns {{ match: RegExp, exclude: RegExp }}
- */
-export function buildCredentialNameRes(spec: Record<string, unknown>): {
-    match: RegExp;
-    exclude: RegExp;
-};
 /**
  * True when `name` looks like a credential-bearing variable (and isn't a known
  * non-secret lookalike).

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