agent-sanitizer 2.7.1 → 2.8.0

package/README.md

@@ -127,13 +127,42 @@ import {
 } from "agent-sanitizer/claude-hooks/lib/hook-io";
 ```
 
-`agent-sanitizer/claude-hooks/<module>` for the four hooks
+The exported set is deliberately small — the four hooks
 (`sanitize-output`, `pretooluse-sanitize`, `sanitize-user-prompt`,
-`scan-invisible-chars`) and `agent-sanitizer/claude-hooks/lib/<module>` for the
-shared libs. Importing one runs no CLI and reads no stdin. Same stability
-posture as the `_AGENT_SANITIZER_*` variables below: reachable and typed, but
-the supported surface is the `--hook=` CLI, so these move between minor
-versions.
+`scan-invisible-chars`) plus `lib/hook-io` and `lib/control-plane`. Everything
+else under `claude-hooks/` stays internal and is refused by the exports map, so
+it never becomes a surface this package owes compatibility on. `lib/hook-io` is
+exported because it must be _shared_ rather than copied: it owns the
+lazy-module registry and the CLI-slot singleton, and two copies in one bundle
+double-fire the inlined CLIs.
+
+Importing one runs no CLI and reads no stdin. Same stability posture as the
+`_AGENT_SANITIZER_*` variables below: reachable and typed, but the supported
+surface is the `--hook=` CLI, so these move between minor versions.
+
+**`sanitize-output` takes a host-extension bag** — an optional last argument on
+`sanitizeText`, `sanitizeValue`, `evaluateToolOutput`, `judgeSanitizeOutput`, and
+`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                         |
+
+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
+fail-closed catch and the tool output is suppressed, so a broken extension can
+never degrade into showing unvetted output. `postText` deliberately does not run
+on object field NAMES: a callback sees only the string and the tool, so it cannot
+tell a schema key from content, and rewriting a key can collapse two fields into
+one name — which this hook turns into whole-output suppression.
+
+Beyond the credential-shaped names it infers, the env-bound redaction set unions
+`_AGENT_SANITIZER_EXTRA_SECRET_VARS` — a comma-separated list of `[A-Z0-9_]`
+variable names whose values a deployment forwards under names of its own
+choosing. A malformed entry throws rather than being dropped.
 
 **Layer 4 needs the Python engine** — `pip install 'agent-sanitizer[secrets]'`,
 version-matched to the npm package. Without it `sanitize-output` fails closed:

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

@@ -3,16 +3,21 @@
  * share, so the set of variable names whose VALUES get masked has one definition
  * instead of a copy per hook that can silently drift.
  *
- * The three JSON configs are imported as modules, not read from disk at call
- * time: esbuild inlines them into the plugin bundle (which ships with no
- * config directory beside it) and Node resolves them natively from the package
- * when the hooks run from source. Their VALIDATION stays lazy — a malformed
- * credential vocabulary throws on first use, inside the consuming hook's
- * fail-closed catch, 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 credential-NAME vocabulary comes from the published
+ * `credential-names.json` — the same file `agent_sanitizer.secrets` renders in
+ * Python — so the JavaScript pre-gate and the Python redactor recognize the same
+ * set of credential-bearing variable names. A rendered second copy is what let
+ * this matcher fall twelve segments behind the engine.
+ *
+ * The JSON configs are imported as modules, not read from disk at call time:
+ * esbuild inlines them into the plugin bundle (which ships with no config
+ * directory beside it) and Node resolves them natively from the package when the
+ * hooks run from source. Their VALIDATION stays lazy — a malformed credential
+ * vocabulary throws on first use, inside the consuming hook's fail-closed catch,
+ * 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).
  */
-import credentialVarNames from "../config/credential-var-names.json" with { type: "json" };
+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" };
 
@@ -34,11 +39,91 @@ export function minEnvSecretLen() {
   return inferenceKeys.min_secret_len;
 }
 
-// A token from credential-var-names.json. Restricting it to A-Z/_ is what lets
-// the regexes below interpolate it unescaped: a stray metacharacter (or an empty
+// 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.
-const CRED_TOKEN_RE = /^[A-Z_]+$/;
+// 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")));
+  const excludeSuffixes = nonSecret.flatMap((suffix) =>
+    segmentForms(parts(suffix, "nonSecretSuffixes[]")).map(
+      (form) => `_${form}`,
+    ),
+  );
+  return {
+    segments: [...new Set(segments)],
+    excludeSuffixes: [...new Set(excludeSuffixes)],
+    excludeNames: EXCLUDE_NAMES,
+  };
+}
+
+/**
+ * `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
@@ -51,17 +136,15 @@ const CRED_TOKEN_RE = /^[A-Z_]+$/;
 function credentialTokens(spec, field) {
   const group = spec[field];
   if (!Array.isArray(group) || group.length === 0)
-    throw new Error(`credential-var-names.json: ${field} is empty or missing`);
+    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(
-        `credential-var-names.json: bad token ${token} in ${field}`,
-      );
+      throw new Error(`${VOCAB_LABEL}: bad token ${token} in ${field}`);
   return group;
 }
 
 /**
- * Validate a credential-var-names spec and build its match/exclude regexes. Pure
+ * 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 }}
@@ -91,7 +174,9 @@ let _credentialNameRes;
  */
 function credentialNameRes() {
   if (_credentialNameRes !== undefined) return _credentialNameRes;
-  return (_credentialNameRes = buildCredentialNameRes(credentialVarNames));
+  return (_credentialNameRes = buildCredentialNameRes(
+    deriveCredentialVocabulary(credentialNames),
+  ));
 }
 
 /**
@@ -120,12 +205,44 @@ export function dynamicSecretVars(env = process.env) {
   );
 }
 
+// Operator-supplied additions to the env-bound redaction set, comma-separated.
+// The name-shape heuristic above only catches vars whose trailing segment reads
+// as a credential (`…_TOKEN`, `…_KEY`); a deployment that forwards a secret under
+// a name of its own choosing (`GLOVEBOX_ATTESTATION_SEED`) has no way to reach
+// 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.
+const EXTRA_TOKEN_RE = /^[A-Z0-9_]+$/;
+
+/**
+ * The operator-declared extra secret variable names, or throw. A malformed entry
+ * fails CLOSED — dropping it silently would leave the operator believing a
+ * forwarded credential is masked while its value flows to the model verbatim.
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {string[]}
+ */
+export function extraSecretVars(env = process.env) {
+  const raw = env[EXTRA_SECRET_VARS_ENV];
+  if (raw === undefined || raw.trim() === "") return [];
+  const tokens = raw.split(",").map((token) => token.trim());
+  for (const token of tokens)
+    if (!EXTRA_TOKEN_RE.test(token))
+      throw new Error(
+        `${EXTRA_SECRET_VARS_ENV}: ${JSON.stringify(token)} is not a variable name ` +
+          "(expected comma-separated [A-Z0-9_] names)",
+      );
+  return tokens;
+}
+
 /**
  * The env-bound redaction set: the UNION of the inference keys, the curated host
- * credentials, and any credential-shaped var present in the environment. The
- * redactor binds the same union; every consumer (the sanitize-output pre-gate,
- * the redactor client's per-request env snapshot) must mirror it exactly, else a
- * credential value would never trip the daemon.
+ * credentials, any credential-shaped var present in the environment, and the
+ * operator's declared extras. The redactor binds the same union; every consumer
+ * (the sanitize-output pre-gate, the redactor client's per-request env snapshot)
+ * must mirror it exactly, else a credential value would never trip the daemon.
  * @param {Record<string, string | undefined>} [env]
  * @returns {string[]}
  */
@@ -135,6 +252,7 @@ export function envBoundSecretVars(env = process.env) {
       ...inferenceKeyVars(),
       ...scrubbed.vars,
       ...dynamicSecretVars(env),
+      ...extraSecretVars(env),
     ]),
   ];
 }

package/claude-hooks/sanitize-output.mjs

@@ -160,6 +160,40 @@ async function redactSecrets(text, webIngress = false, deadline) {
   );
 }
 
+/**
+ * Host-supplied extensions to this hook, threaded from {@link cliMain} down to
+ * each string leaf. Every field is optional and the bag defaults to `{}`, so a
+ * composer that supplies none gets exactly the behavior of this module alone —
+ * which is what lets the extension points ship without changing any shipped
+ * verdict. The callbacks own all policy: this module decides only WHERE they run,
+ * never WHETHER their result is applied.
+ *
+ * A callback that throws is not caught here. That is deliberate: the throw lands
+ * in the CLI's fail-closed catch and the tool output is suppressed, so a broken
+ * extension cannot degrade into showing unvetted output.
+ *
+ * These are NOT the Layer-5 injection-filter seam and do not inherit its
+ * delete-only, closed-enum restriction. (Its identifier is deliberately unspoken
+ * here: the plugin-bundle suite pins Layer 5 absent by asserting the name appears
+ * nowhere in this file, and that absolute check is worth more than the precision
+ * of one comment.) That restriction exists because such a
+ * filter is a MODEL, so its output is attacker-reachable and must not be able to
+ * inject text into the model-facing context. These callbacks are code the
+ * composer wrote and linked at build time — the same trust level as the injected
+ * redactor — so free-text warnings and arbitrary rewrites are theirs to own.
+ *
+ * @typedef {object} SanitizeExtensions
+ * @property {(cleaned: string, ctx: { toolName: string, webIngress: boolean, deadline: { remainingMs: () => number } }) => Promise<{ cleaned?: string, warning?: string } | null | undefined> | { cleaned?: string, warning?: string } | null | undefined} [postText]
+ *   Runs once per string leaf, AFTER Layers 1-4. Returning `cleaned` replaces the
+ *   model-facing text; `warning` joins this leaf's warnings.
+ * @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]
+ *   Awaited once per judged event that carried a tool response, with the output
+ *   the model will actually see.
+ */
+
 /**
  * Run Layers 1-4 over a single text blob, delegated to the package's output seam
  * (sanitizeTextSeam) bound here to this hook's per-tool policy: which tools get
@@ -171,12 +205,14 @@ async function redactSecrets(text, webIngress = false, deadline) {
  * @param {string} toolName  gates the SGR carve-out and the untrusted-ingress passes
  * @param {{remainingMs: () => number}} [deadline] shared wall-clock budget across
  *   all leaves of one hook run; a direct caller gets a fresh full budget
+ * @param {SanitizeExtensions} [ext]
  * @returns {Promise<{ cleaned: string, warnings: string[], modified: boolean, sgrNote: boolean, reveal?: string }>}
  */
 export async function sanitizeText(
   text,
   toolName,
   deadline = makeDeadline(SANITIZE_BUDGET_MS),
+  ext = {},
 ) {
   const webIngress = isUntrustedIngress(toolName);
   // Layer 2 (HTML rewrite) runs on WebFetch/WebSearch always, and on MCP output
@@ -211,12 +247,56 @@ export async function sanitizeText(
         );
         throw l4err;
       }
-      return secrets ? { text: secrets.text, found: secrets.found } : null;
+      if (!secrets) return null;
+      // The note is derived from the PRE-redaction text: the caller's reason for
+      // annotating (which variable, which provenance) is exactly what redaction
+      // is about to remove.
+      const note = ext.redactNote?.(content);
+      return note
+        ? { text: secrets.text, found: secrets.found, note }
+        : { text: secrets.text, found: secrets.found };
     },
   };
-  return /** @type {{ cleaned: string, warnings: string[], modified: boolean, sgrNote: boolean, reveal?: string }} */ (
-    await sanitizeTextSeam(text, seamOptions)
-  );
+  const result =
+    /** @type {{ cleaned: string, warnings: string[], modified: boolean, sgrNote: boolean, reveal?: string }} */ (
+      await sanitizeTextSeam(text, seamOptions)
+    );
+  return ext.postText
+    ? applyPostText(
+        result,
+        await ext.postText(result.cleaned, {
+          toolName,
+          webIngress,
+          deadline,
+        }),
+      )
+    : result;
+}
+
+/**
+ * Fold a `postText` callback's result into the seam's, leaving the seam's result
+ * untouched when the callback declined (null/undefined) or returned no `cleaned`.
+ * `modified` widens to cover the callback's rewrite, and `sgrNote` is dropped
+ * when it does: that flag downgrades the model-facing banner to "display-only
+ * ANSI color stripped", which would be a false statement about bytes a callback
+ * has since rewritten for its own reasons.
+ * @param {{ cleaned: string, warnings: string[], modified: boolean, sgrNote: boolean, reveal?: string }} result
+ * @param {{ cleaned?: string, warning?: string } | null | undefined} post
+ * @returns {{ cleaned: string, warnings: string[], modified: boolean, sgrNote: boolean, reveal?: string }}
+ */
+function applyPostText(result, post) {
+  if (post === null || post === undefined) return result;
+  const cleaned = post.cleaned ?? result.cleaned;
+  const rewrote = cleaned !== result.cleaned;
+  return {
+    ...result,
+    cleaned,
+    warnings: post.warning
+      ? [...result.warnings, post.warning]
+      : result.warnings,
+    modified: result.modified || rewrote,
+    sgrNote: result.sgrNote && !rewrote,
+  };
 }
 
 /**
@@ -239,6 +319,7 @@ export async function sanitizeText(
  * @param {string[]} [reveals]
  * @param {{remainingMs: () => number}} [deadline] shared wall-clock budget across
  *   every leaf of this value (created once by the top-level caller)
+ * @param {SanitizeExtensions} [ext]
  * @returns {Promise<{ value: any, modified: boolean, sgrNote: boolean }>}
  */
 export async function sanitizeValue(
@@ -247,9 +328,10 @@ export async function sanitizeValue(
   warnings,
   reveals = [],
   deadline = makeDeadline(SANITIZE_BUDGET_MS),
+  ext = {},
 ) {
   if (typeof value === "string") {
-    const result = await sanitizeText(value, toolName, deadline);
+    const result = await sanitizeText(value, toolName, deadline, ext);
     warnings.push(...result.warnings);
     if (result.reveal !== undefined) reveals.push(result.reveal);
     return {
@@ -269,6 +351,7 @@ export async function sanitizeValue(
         warnings,
         reveals,
         deadline,
+        ext,
       );
       out.push(result.value);
       if (result.modified) modified = true;
@@ -277,7 +360,7 @@ export async function sanitizeValue(
     return { value: out, modified, sgrNote };
   }
   if (value !== null && typeof value === "object")
-    return sanitizeObject(value, toolName, warnings, reveals, deadline);
+    return sanitizeObject(value, toolName, warnings, reveals, deadline, ext);
   return { value, modified: false, sgrNote: false };
 }
 
@@ -291,14 +374,27 @@ export async function sanitizeValue(
  * @param {string[]} warnings
  * @param {string[]} reveals
  * @param {{remainingMs: () => number}} deadline shared wall-clock budget
+ * @param {SanitizeExtensions} ext
  * @returns {Promise<{ value: Record<string, any>, modified: boolean, sgrNote: boolean }>}
  */
-async function sanitizeObject(value, toolName, warnings, reveals, deadline) {
+async function sanitizeObject(
+  value,
+  toolName,
+  warnings,
+  reveals,
+  deadline,
+  ext,
+) {
   /** @type {Record<string, any>} */
   const out = {};
   let modified = false;
   let sgrNote = false;
   for (const [key, item] of Object.entries(value)) {
+    // Layers 1-4 only — `ext` is deliberately NOT passed for a field NAME. A
+    // callback sees just the string and the tool, so it cannot tell a schema key
+    // from content; a rewrite here can collapse two fields into one name, which
+    // the guard below turns into whole-output suppression. Extensions run on
+    // value leaves.
     const keyResult = await sanitizeText(key, toolName, deadline);
     warnings.push(...keyResult.warnings);
     if (keyResult.reveal !== undefined) reveals.push(keyResult.reveal);
@@ -310,6 +406,7 @@ async function sanitizeObject(value, toolName, warnings, reveals, deadline) {
       warnings,
       reveals,
       deadline,
+      ext,
     );
     // Two distinct raw keys can sanitize to the same name (e.g. `token` and a
     // `token` carrying a zero-width space stripped by Layer 1). Overwriting would
@@ -458,9 +555,10 @@ export function emitFailClosed(
  * fields unchanged. The trace lives here, not in the CLI block below, so it
  * rides the in-process, mutation-tested path.
  * @param {any} input  the tool_name / tool_input / tool_response to sanitize
+ * @param {SanitizeExtensions} [ext]
  * @returns {Promise<{ mutated_output?: unknown, additional_context?: string } | null>}
  */
-export async function evaluateToolOutput(input) {
+export async function evaluateToolOutput(input, ext = {}) {
   /**
    * @param {string} outcome  noop | clean | flagged | modified
    * @param {{ mutated_output?: unknown, additional_context?: string } | null} fields
@@ -504,6 +602,7 @@ export async function evaluateToolOutput(input) {
     warnings,
     reveals,
     deadline,
+    ext,
   );
   // Persist each leaf's pre-Layer-2 text (deduped by content) so the model can
   // Read back what the HTML splice removed; a successful write appends a hint
@@ -569,9 +668,10 @@ export async function evaluateToolOutput(input) {
  * translation. Throws only if a layer engine throws (or on an UNKNOWN event);
  * the CLI fails closed on any throw.
  * @param {import("agent-control-plane-core").ToolCallEvent} event
+ * @param {SanitizeExtensions} [ext]
  * @returns {Promise<import("agent-control-plane-core").Verdict>}
  */
-export async function judgeSanitizeOutput(event) {
+export async function judgeSanitizeOutput(event, ext = {}) {
   const { Decision, EventKind } = controlPlane();
   // Fail closed on a payload the adapter cannot classify (contract/harness
   // drift): this hook only ever receives PostToolUse, so an UNKNOWN event is an
@@ -584,11 +684,30 @@ export async function judgeSanitizeOutput(event) {
   // evaluateToolOutput keys its tool checks on the CANONICAL names (`Read`, the
   // WEB_INGRESS_TOOLS set, `mcp__…`), so it takes `event.tool` — the normalized
   // name — not the raw `meta.native_tool`.
-  const fields = await evaluateToolOutput({
-    tool_name: event.tool,
-    tool_input: event.input,
-    tool_response: event.response,
-  });
+  const fields = await evaluateToolOutput(
+    {
+      tool_name: event.tool,
+      tool_input: event.input,
+      tool_response: event.response,
+    },
+    ext,
+  );
+  // Audit sees what the MODEL will see, which is the whole point of putting the
+  // call here rather than beside the walk: `mutated_output` is present only when
+  // the sanitizer actually rewrote bytes, so its absence means the original
+  // response IS the model-facing output. Gated on a response existing, so an
+  // event with nothing to sanitize records nothing. Awaited (not fired and
+  // forgotten) so a recorder that throws fails the hook CLOSED — an audit trail
+  // with silent holes is worse than a suppressed tool output.
+  if (ext.audit && event.response !== null && event.response !== undefined) {
+    const modified = fields !== null && Object.hasOwn(fields, "mutated_output");
+    await ext.audit({
+      tool: event.tool,
+      modified,
+      output: modified ? fields?.mutated_output : event.response,
+      context: fields?.additional_context,
+    });
+  }
   /** @type {import("agent-control-plane-core").Verdict} */
   const verdict = { decision: Decision.ALLOW };
   return fields === null ? verdict : { ...verdict, ...fields };
@@ -627,27 +746,34 @@ export function withPostToolUseDefault(input) {
  * The hook's CLI: parse → judge → render, with this hook's fail-closed posture.
  * Exported so a bundle entry (which must claim the CLI slot before this module
  * loads) can run the exact same wiring instead of duplicating the onError
- * posture.
+ * posture. That entry is also the only place a host's {@link SanitizeExtensions}
+ * can be injected, which is why the bag enters here and not through the
+ * environment: a callback is code, and code belongs to the composer.
+ * @param {SanitizeExtensions} [ext]
  * @returns {Promise<void>}
  */
-export async function cliMain() {
-  await runJudgeCli("sanitize-output", judgeSanitizeOutput, {
-    transformInput: withPostToolUseDefault,
-    // Fail closed: replace every string leaf of the original output with the
-    // placeholder, preserving shape so the harness honors the suppression
-    // instead of falling back to the raw, unvetted output (runJudgeCli hands
-    // back the parsed `input` even when the control-plane load failed, so the
-    // suppression shape-matches the real tool_response). emitFailClosed itself
-    // falls back to a bare string if that shape-matching replacement or its
-    // serialization throws, so even a pathological input fails closed.
-    onError: (err, input) =>
-      emitFailClosed(
-        input,
-        "[SANITIZATION FAILED — original output suppressed for safety. Hook error: " +
-          safeErrMessage(err) +
-          "]",
-      ),
-  });
+export async function cliMain(ext = {}) {
+  await runJudgeCli(
+    "sanitize-output",
+    (event) => judgeSanitizeOutput(event, ext),
+    {
+      transformInput: withPostToolUseDefault,
+      // Fail closed: replace every string leaf of the original output with the
+      // placeholder, preserving shape so the harness honors the suppression
+      // instead of falling back to the raw, unvetted output (runJudgeCli hands
+      // back the parsed `input` even when the control-plane load failed, so the
+      // suppression shape-matches the real tool_response). emitFailClosed itself
+      // falls back to a bare string if that shape-matching replacement or its
+      // serialization throws, so even a pathological input fails closed.
+      onError: (err, input) =>
+        emitFailClosed(
+          input,
+          "[SANITIZATION FAILED — original output suppressed for safety. Hook error: " +
+            safeErrMessage(err) +
+            "]",
+        ),
+    },
+  );
 }
 
 // Guard so importing (e.g. property tests) doesn't block on stdin.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.7.1",
+  "version": "2.8.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": {
@@ -130,9 +130,29 @@
       "types": "./types/claude-hooks/plugin-hooks.d.mts",
       "default": "./claude-hooks/plugin-hooks.mjs"
     },
-    "./claude-hooks/*": {
-      "types": "./types/claude-hooks/*.d.mts",
-      "default": "./claude-hooks/*.mjs"
+    "./claude-hooks/pretooluse-sanitize": {
+      "types": "./types/claude-hooks/pretooluse-sanitize.d.mts",
+      "default": "./claude-hooks/pretooluse-sanitize.mjs"
+    },
+    "./claude-hooks/sanitize-output": {
+      "types": "./types/claude-hooks/sanitize-output.d.mts",
+      "default": "./claude-hooks/sanitize-output.mjs"
+    },
+    "./claude-hooks/sanitize-user-prompt": {
+      "types": "./types/claude-hooks/sanitize-user-prompt.d.mts",
+      "default": "./claude-hooks/sanitize-user-prompt.mjs"
+    },
+    "./claude-hooks/scan-invisible-chars": {
+      "types": "./types/claude-hooks/scan-invisible-chars.d.mts",
+      "default": "./claude-hooks/scan-invisible-chars.mjs"
+    },
+    "./claude-hooks/lib/hook-io": {
+      "types": "./types/claude-hooks/lib/hook-io.d.mts",
+      "default": "./claude-hooks/lib/hook-io.mjs"
+    },
+    "./claude-hooks/lib/control-plane": {
+      "types": "./types/claude-hooks/lib/control-plane.d.mts",
+      "default": "./claude-hooks/lib/control-plane.mjs"
     }
   },
   "files": [

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

@@ -11,7 +11,24 @@ export function inferenceKeyVars(): string[];
  */
 export function minEnvSecretLen(): number;
 /**
- * Validate a credential-var-names spec and build its match/exclude regexes. Pure
+ * 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 }}
@@ -36,12 +53,20 @@ export function looksLikeCredentialVar(name: string): boolean;
  * @returns {string[]}
  */
 export function dynamicSecretVars(env?: Record<string, string | undefined>): string[];
+/**
+ * The operator-declared extra secret variable names, or throw. A malformed entry
+ * fails CLOSED — dropping it silently would leave the operator believing a
+ * forwarded credential is masked while its value flows to the model verbatim.
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {string[]}
+ */
+export function extraSecretVars(env?: Record<string, string | undefined>): string[];
 /**
  * The env-bound redaction set: the UNION of the inference keys, the curated host
- * credentials, and any credential-shaped var present in the environment. The
- * redactor binds the same union; every consumer (the sanitize-output pre-gate,
- * the redactor client's per-request env snapshot) must mirror it exactly, else a
- * credential value would never trip the daemon.
+ * credentials, any credential-shaped var present in the environment, and the
+ * operator's declared extras. The redactor binds the same union; every consumer
+ * (the sanitize-output pre-gate, the redactor client's per-request env snapshot)
+ * must mirror it exactly, else a credential value would never trip the daemon.
  * @param {Record<string, string | undefined>} [env]
  * @returns {string[]}
  */

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

@@ -1,3 +1,36 @@
+/**
+ * Host-supplied extensions to this hook, threaded from {@link cliMain} down to
+ * each string leaf. Every field is optional and the bag defaults to `{}`, so a
+ * composer that supplies none gets exactly the behavior of this module alone —
+ * which is what lets the extension points ship without changing any shipped
+ * verdict. The callbacks own all policy: this module decides only WHERE they run,
+ * never WHETHER their result is applied.
+ *
+ * A callback that throws is not caught here. That is deliberate: the throw lands
+ * in the CLI's fail-closed catch and the tool output is suppressed, so a broken
+ * extension cannot degrade into showing unvetted output.
+ *
+ * These are NOT the Layer-5 injection-filter seam and do not inherit its
+ * delete-only, closed-enum restriction. (Its identifier is deliberately unspoken
+ * here: the plugin-bundle suite pins Layer 5 absent by asserting the name appears
+ * nowhere in this file, and that absolute check is worth more than the precision
+ * of one comment.) That restriction exists because such a
+ * filter is a MODEL, so its output is attacker-reachable and must not be able to
+ * inject text into the model-facing context. These callbacks are code the
+ * composer wrote and linked at build time — the same trust level as the injected
+ * redactor — so free-text warnings and arbitrary rewrites are theirs to own.
+ *
+ * @typedef {object} SanitizeExtensions
+ * @property {(cleaned: string, ctx: { toolName: string, webIngress: boolean, deadline: { remainingMs: () => number } }) => Promise<{ cleaned?: string, warning?: string } | null | undefined> | { cleaned?: string, warning?: string } | null | undefined} [postText]
+ *   Runs once per string leaf, AFTER Layers 1-4. Returning `cleaned` replaces the
+ *   model-facing text; `warning` joins this leaf's warnings.
+ * @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]
+ *   Awaited once per judged event that carried a tool response, with the output
+ *   the model will actually see.
+ */
 /**
  * Run Layers 1-4 over a single text blob, delegated to the package's output seam
  * (sanitizeTextSeam) bound here to this hook's per-tool policy: which tools get
@@ -9,11 +42,12 @@
  * @param {string} toolName  gates the SGR carve-out and the untrusted-ingress passes
  * @param {{remainingMs: () => number}} [deadline] shared wall-clock budget across
  *   all leaves of one hook run; a direct caller gets a fresh full budget
+ * @param {SanitizeExtensions} [ext]
  * @returns {Promise<{ cleaned: string, warnings: string[], modified: boolean, sgrNote: boolean, reveal?: string }>}
  */
 export function sanitizeText(text: string, toolName: string, deadline?: {
     remainingMs: () => number;
-}): Promise<{
+}, ext?: SanitizeExtensions): Promise<{
     cleaned: string;
     warnings: string[];
     modified: boolean;
@@ -40,11 +74,12 @@ export function sanitizeText(text: string, toolName: string, deadline?: {
  * @param {string[]} [reveals]
  * @param {{remainingMs: () => number}} [deadline] shared wall-clock budget across
  *   every leaf of this value (created once by the top-level caller)
+ * @param {SanitizeExtensions} [ext]
  * @returns {Promise<{ value: any, modified: boolean, sgrNote: boolean }>}
  */
 export function sanitizeValue(value: any, toolName: string, warnings: string[], reveals?: string[], deadline?: {
     remainingMs: () => number;
-}): Promise<{
+}, ext?: SanitizeExtensions): Promise<{
     value: any;
     modified: boolean;
     sgrNote: boolean;
@@ -117,9 +152,10 @@ export function emitFailClosed(input: any, message: string, emit?: (fields: Reco
  * fields unchanged. The trace lives here, not in the CLI block below, so it
  * rides the in-process, mutation-tested path.
  * @param {any} input  the tool_name / tool_input / tool_response to sanitize
+ * @param {SanitizeExtensions} [ext]
  * @returns {Promise<{ mutated_output?: unknown, additional_context?: string } | null>}
  */
-export function evaluateToolOutput(input: any): Promise<{
+export function evaluateToolOutput(input: any, ext?: SanitizeExtensions): Promise<{
     mutated_output?: unknown;
     additional_context?: string;
 } | null>;
@@ -134,9 +170,10 @@ export function evaluateToolOutput(input: any): Promise<{
  * translation. Throws only if a layer engine throws (or on an UNKNOWN event);
  * the CLI fails closed on any throw.
  * @param {import("agent-control-plane-core").ToolCallEvent} event
+ * @param {SanitizeExtensions} [ext]
  * @returns {Promise<import("agent-control-plane-core").Verdict>}
  */
-export function judgeSanitizeOutput(event: import("agent-control-plane-core").ToolCallEvent): Promise<import("agent-control-plane-core").Verdict>;
+export function judgeSanitizeOutput(event: import("agent-control-plane-core").ToolCallEvent, ext?: SanitizeExtensions): Promise<import("agent-control-plane-core").Verdict>;
 /**
  * Default a raw payload's `hook_event_name` to PostToolUse when it is absent.
  * sanitize-output is wired ONLY to the PostToolUse event, so a payload that
@@ -155,10 +192,13 @@ export function withPostToolUseDefault(input: unknown): unknown;
  * The hook's CLI: parse → judge → render, with this hook's fail-closed posture.
  * Exported so a bundle entry (which must claim the CLI slot before this module
  * loads) can run the exact same wiring instead of duplicating the onError
- * posture.
+ * posture. That entry is also the only place a host's {@link SanitizeExtensions}
+ * can be injected, which is why the bag enters here and not through the
+ * environment: a callback is code, and code belongs to the composer.
+ * @param {SanitizeExtensions} [ext]
  * @returns {Promise<void>}
  */
-export function cliMain(): Promise<void>;
+export function cliMain(ext?: SanitizeExtensions): Promise<void>;
 export const applyLayer1: typeof import("agent-sanitizer").applyLayer1;
 export const matchesSecretHint: typeof import("agent-sanitizer").matchesSecretHint;
 export const SECRET_HINT: RegExp;
@@ -166,3 +206,59 @@ export const SECRET_HINT_EXT: RegExp;
 export const describeRemoved: typeof import("agent-sanitizer/output").describeRemoved;
 export const describeWarned: typeof import("agent-sanitizer/output").describeWarned;
 export const suppressToolOutput: typeof import("agent-sanitizer/output").suppressToolOutput;
+/**
+ * Host-supplied extensions to this hook, threaded from {@link cliMain} down to
+ * each string leaf. Every field is optional and the bag defaults to `{}`, so a
+ * composer that supplies none gets exactly the behavior of this module alone —
+ * which is what lets the extension points ship without changing any shipped
+ * verdict. The callbacks own all policy: this module decides only WHERE they run,
+ * never WHETHER their result is applied.
+ *
+ * A callback that throws is not caught here. That is deliberate: the throw lands
+ * in the CLI's fail-closed catch and the tool output is suppressed, so a broken
+ * extension cannot degrade into showing unvetted output.
+ *
+ * These are NOT the Layer-5 injection-filter seam and do not inherit its
+ * delete-only, closed-enum restriction. (Its identifier is deliberately unspoken
+ * here: the plugin-bundle suite pins Layer 5 absent by asserting the name appears
+ * nowhere in this file, and that absolute check is worth more than the precision
+ * of one comment.) That restriction exists because such a
+ * filter is a MODEL, so its output is attacker-reachable and must not be able to
+ * inject text into the model-facing context. These callbacks are code the
+ * composer wrote and linked at build time — the same trust level as the injected
+ * redactor — so free-text warnings and arbitrary rewrites are theirs to own.
+ */
+export type SanitizeExtensions = {
+    /**
+     * Runs once per string leaf, AFTER Layers 1-4. Returning `cleaned` replaces the
+     * model-facing text; `warning` joins this leaf's warnings.
+     */
+    postText?: ((cleaned: string, ctx: {
+        toolName: string;
+        webIngress: boolean;
+        deadline: {
+            remainingMs: () => number;
+        };
+    }) => Promise<{
+        cleaned?: string;
+        warning?: string;
+    } | null | undefined> | {
+        cleaned?: string;
+        warning?: string;
+    } | null | undefined) | undefined;
+    /**
+     * 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.
+     */
+    redactNote?: ((raw: string) => string | undefined) | undefined;
+    /**
+     * Awaited once per judged event that carried a tool response, with the output
+     * the model will actually see.
+     */
+    audit?: ((record: {
+        tool: string | null;
+        modified: boolean;
+        output: unknown;
+        context?: string;
+    }) => Promise<void> | void) | undefined;
+};

package/claude-hooks/config/credential-var-names.json

@@ -1,23 +0,0 @@
-{
-  "comment": "The credential-shaped ENV-VAR NAME vocabulary the hook-side pre-gate builds its regexes from (looksLikeCredentialVar in lib/env-config.mjs). `segments`: a var whose trailing underscore-delimited segment is one of these is treated as credential-bearing (matched as `(?:^|_)(?:<segment>)$`, case-insensitive). `excludeSuffixes` / `excludeNames`: names that end like a credential but hold a non-secret (an identifier, a public key, the ssh-agent socket path) and must NOT be redacted out of tool output. Every token is restricted to A-Z and _ so it carries no regex metacharacter; the consumer enforces that and fails closed on a violation, an empty list, or a missing field.",
-  "segments": [
-    "TOKEN",
-    "SECRET",
-    "SECRETS",
-    "PASSWORD",
-    "PASSWD",
-    "PASSPHRASE",
-    "APIKEY",
-    "API_KEY",
-    "ACCESS_KEY",
-    "SECRET_KEY",
-    "PRIVATE_KEY",
-    "AUTH_TOKEN",
-    "PAT",
-    "CREDENTIAL",
-    "CREDENTIALS",
-    "KEY"
-  ],
-  "excludeSuffixes": ["_KEY_ID", "_PUBLIC_KEY"],
-  "excludeNames": ["SSH_AUTH_SOCK"]
-}