agent-sanitizer 2.4.1 → 2.5.0

package/README.md

@@ -113,6 +113,28 @@ To wire them yourself instead, one entry dispatches all four modes on `--hook=`:
 `require.resolve("agent-sanitizer/claude-hooks")` gives the path without
 hardcoding a layout. Importing the module rather than spawning it is a no-op.
 
+**To compose the hooks instead of spawning them**, each module is a subpath of
+its own, typed, with the pieces exported individually:
+
+```js
+import {
+  sanitizeText,
+  evaluateToolOutput,
+} from "agent-sanitizer/claude-hooks/sanitize-output";
+import {
+  lazyImport,
+  makeDeadline,
+} from "agent-sanitizer/claude-hooks/lib/hook-io";
+```
+
+`agent-sanitizer/claude-hooks/<module>` for 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.
+
 **Layer 4 needs the Python engine** — `pip install 'agent-sanitizer[secrets]'`,
 version-matched to the npm package. Without it `sanitize-output` fails closed:
 secret-shaped output is suppressed, not shown unvetted. Layers 1–3 still run.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.4.1",
+  "version": "2.5.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": {
@@ -122,7 +122,14 @@
       "default": "./src/rehydrate.mjs"
     },
     "./credential-names": "./python/agent_sanitizer/secrets/data/credential-names.json",
-    "./claude-hooks": "./claude-hooks/plugin-hooks.mjs"
+    "./claude-hooks": {
+      "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"
+    }
   },
   "files": [
     "src/*.mjs",
@@ -153,7 +160,7 @@
     "coverage": "c8 node --test",
     "check": "tsc --noEmit && tsc -p tsconfig.hooks.json --noEmit",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.hooks.json --noEmit",
-    "build:types": "tsc -p tsconfig.build.json",
+    "build:types": "tsc -p tsconfig.build.json && tsc -p tsconfig.build-hooks.json",
     "gen:joining-type": "node scripts/gen-joining-type.mjs",
     "lint": "eslint .",
     "test:mutation": "stryker run",

package/types/claude-hooks/lib/authored-content.d.mts

@@ -0,0 +1,15 @@
+/** @param {string[]} changed */
+export function authoredContext(changed: string[]): string;
+/**
+ * Strip authored stego / terminal-control sequences from the model-authored
+ * fields of a tool call. Returns the updated input plus a per-field description
+ * of what was stripped, or null when nothing changed. Throws on internal error
+ * (caller fails closed).
+ * @param {string} tool
+ * @param {any} toolInput
+ * @returns {{ updatedInput: any, changed: string[] } | null}
+ */
+export function sanitizeAuthoredContent(tool: string, toolInput: any): {
+    updatedInput: any;
+    changed: string[];
+} | null;

package/types/claude-hooks/lib/control-plane.d.mts

@@ -0,0 +1,62 @@
+/**
+ * The loaded control-plane bindings, narrowed to non-undefined — or a throw
+ * the calling hook's catch converts into its own failure posture. Overrides
+ * exist so tests can drive the unavailable arm in-process.
+ * @param {{ claudeAdapter?: unknown, Decision?: unknown, EventKind?: unknown }} [overrides]
+ * @returns {{
+ *   claudeAdapter: typeof import("agent-control-plane-core/claude").claudeAdapter,
+ *   Decision: typeof import("agent-control-plane-core").Decision,
+ *   EventKind: typeof import("agent-control-plane-core").EventKind,
+ * }}
+ */
+export function controlPlane(overrides?: {
+    claudeAdapter?: unknown;
+    Decision?: unknown;
+    EventKind?: unknown;
+}): {
+    claudeAdapter: typeof import("agent-control-plane-core/claude").claudeAdapter;
+    Decision: typeof import("agent-control-plane-core").Decision;
+    EventKind: typeof import("agent-control-plane-core").EventKind;
+};
+/**
+ * Serialize a rendered NativeResponse for Claude Code's stdout, or null when
+ * the body carries nothing a silent exit 0 doesn't already say. The adapter's
+ * exit_code is deliberately NOT honored by the hooks: Claude Code parses hook
+ * stdout as JSON only on exit 0 — under the adapter's exit-2 enforced-deny
+ * channel it discards stdout and reads the (empty) stderr instead, so the
+ * deny would land without its reason. For this host the stdout JSON's
+ * permissionDecision IS the enforcement channel, and hooks always exit 0.
+ * @param {{ stdout?: unknown }} response a NativeResponse from adapter.render
+ * @returns {string | null}
+ */
+export function nativeStdout(response: {
+    stdout?: unknown;
+}): string | null;
+/**
+ * Run a judge hook's CLI transport: read the native payload from stdin, parse
+ * it through the claude adapter, render the judge's verdict, and write the
+ * native response. This encodes the two transport invariants every gate hook
+ * shares: stdin is read BEFORE the control-plane bindings are touched, so a
+ * package-load failure still lands in `onError` with the parsed input in hand;
+ * and the process always exits 0 with the verdict in the stdout JSON (see
+ * nativeStdout — exit-code enforcement is deliberately not used). Any throw —
+ * unparsable stdin, missing package, a judge error — is reported on stderr and
+ * routed to `onError(err, input)` (`input` undefined when stdin never parsed),
+ * where the hook applies its declared fail posture.
+ * @param {string} hookName  prefix for the stderr diagnostic
+ * @param {(event: import("agent-control-plane-core").ToolCallEvent) =>
+ *   import("agent-control-plane-core").Verdict |
+ *   Promise<import("agent-control-plane-core").Verdict>} judge
+ * @param {object} opts
+ * @param {(err: unknown, input: unknown) => void} opts.onError  fail-posture emitter
+ * @param {(input: unknown) => unknown} [opts.transformInput]  raw-payload normalization before adapter.parse
+ * @param {() => Promise<unknown>} [opts.readInput]  injectable stdin reader
+ * @param {(chunk: string) => void} [opts.write]  injectable stdout writer
+ * @returns {Promise<void>}
+ */
+export function runJudgeCli(hookName: string, judge: (event: import("agent-control-plane-core").ToolCallEvent) => import("agent-control-plane-core").Verdict | Promise<import("agent-control-plane-core").Verdict>, { onError, transformInput, readInput, write, }: {
+    onError: (err: unknown, input: unknown) => void;
+    transformInput?: ((input: unknown) => unknown) | undefined;
+    readInput?: (() => Promise<unknown>) | undefined;
+    write?: ((chunk: string) => void) | undefined;
+}): Promise<void>;

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

@@ -0,0 +1,48 @@
+/**
+ * The inference-provider key env vars. Their values authenticate the agent to a
+ * model backend, so they are masked like any other credential.
+ * @returns {string[]}
+ */
+export function inferenceKeyVars(): string[];
+/**
+ * The placeholder floor: a candidate value shorter than this is too short to be a
+ * real secret and is skipped by the env-bound redaction pre-gate.
+ * @returns {number}
+ */
+export function minEnvSecretLen(): number;
+/**
+ * Validate a credential-var-names 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).
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function looksLikeCredentialVar(name: string): boolean;
+/**
+ * Credential-shaped env-var names present in `env` with a value long enough to be
+ * a real secret (the min_secret_len floor the daemon also applies), beyond the
+ * curated set. Reads the live environment so a newly-forwarded token is redacted
+ * without a code change.
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {string[]}
+ */
+export function dynamicSecretVars(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.
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {string[]}
+ */
+export function envBoundSecretVars(env?: Record<string, string | undefined>): string[];

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

@@ -0,0 +1,196 @@
+/**
+ * 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
+ * resolving it: the bare `import.meta.url === pathToFileURL(process.argv[1])`
+ * form throws there. Resolving argv[1] through pathToFileURL also normalizes a
+ * relative invocation path to an absolute file URL before comparing.
+ * @param {string} importMetaUrl  the caller's `import.meta.url`
+ * @returns {boolean}
+ */
+export function isMain(importMetaUrl: string): boolean;
+/**
+ * Claim the process's CLI-entry slot for the calling module: every subsequent
+ * {@link isMain} call answers false. For bundle entry points that inline other
+ * isMain-guarded hooks (see isMain's bundle note); a claim cannot be released.
+ * @returns {void}
+ */
+export function claimCliEntry(): void;
+/**
+ * Find a `--name=value` flag in argv (by prefix scan, not position) and return
+ * its value, or undefined if absent. A named flag stays correct when unrelated
+ * arguments are prepended or interspersed — a bare positional index (argv[2])
+ * silently reads the wrong value the moment the command line grows.
+ * @param {string[]} argv
+ * @param {string} name flag name without the leading `--` or trailing `=`
+ * @returns {string|undefined}
+ */
+export function readFlag(argv: string[], name: string): string | undefined;
+/**
+ * @param {number} [maxBytes] cap before aborting (overridable for tests)
+ * @returns {Promise<any>}
+ */
+export function readStdinJson(maxBytes?: number): Promise<any>;
+/**
+ * Register already-loaded module namespaces for {@link lazyImport} to return in
+ * place of a runtime dynamic import. Call before importing any module that
+ * lazy-loads the given specifiers.
+ * @param {Record<string, Record<string, any>>} modules  specifier → namespace
+ * @returns {void}
+ */
+export function registerLazyModules(modules: Record<string, Record<string, any>>): void;
+/**
+ * The pre-registered namespace for `specifier`, or undefined when none was
+ * registered. The synchronous face of the registry, for call sites that cannot
+ * await {@link lazyImport} (e.g. a sync callback binding a scanner package):
+ * inside a bundle the registered namespace is the ONLY way to reach the
+ * package, since a runtime require/import has no node_modules to resolve from.
+ * @param {string} specifier
+ * @returns {Record<string, any> | undefined}
+ */
+export function registeredLazyModule(specifier: string): Record<string, any> | undefined;
+/**
+ * Dynamic-import `specifier`, yielding `{}` when the module cannot be loaded.
+ * Hooks bind their npm packages through this instead of a bare static import: a
+ * static npm import resolves before any try/catch, so a missing node_modules
+ * would crash the hook at load — the harness treats that as a non-blocking
+ * error and the tool call proceeds UNGUARDED (fail OPEN). Destructuring from
+ * the `{}` failure value leaves each binding undefined, so the first use throws
+ * into the hook's own catch and the hook takes its declared failure posture
+ * instead. A specifier registered via {@link registerLazyModules} resolves from
+ * the registry without touching the loader.
+ * @param {string} specifier
+ * @returns {Promise<Record<string, any>>}
+ */
+export function lazyImport(specifier: string): Promise<Record<string, any>>;
+/**
+ * A monotonic wall-clock budget shared across one hook run's downstream blocking
+ * calls. `remainingMs()` returns the milliseconds left until the budget is spent
+ * (clamped at 0), so an orchestrator hands each sub-call `min(its own timeout,
+ * remaining)` and a SERIES of daemon calls can never sum past the budget. This is
+ * the fail-open hazard a per-call-only deadline leaves open: when many output
+ * leaves each pay the Layer-4 redactor, the calls' individual timeouts bound each
+ * call but not their SUM — a pathological pile-up could exceed the PostToolUse
+ * hook kill, and a killed hook is non-blocking, so the RAW output would be shown.
+ * `now` is injectable so time-dependent logic is unit-testable with a fake clock.
+ * @param {number} budgetMs total wall-clock budget from creation
+ * @param {() => number} [now] clock source (defaults to Date.now)
+ * @returns {{ remainingMs: () => number }}
+ */
+export function makeDeadline(budgetMs: number, now?: () => number): {
+    remainingMs: () => number;
+};
+/**
+ * Scrub untrusted text before it is spliced into the model's context via a
+ * warning/reason field: strip ANSI and payload-capable invisibles to a fixed
+ * point (via the injected `layer1`, the package's composite Layer-1 view),
+ * replace lone surrogates so the model's UTF-16 context stays well-formed, then
+ * cap by whole code points (never mid-pair, which the surrogate pass above
+ * already swept). `layer1` is injected rather than imported so this
+ * dependency-light module never eagerly loads the sanitizer package — each
+ * caller passes its own caught-import binding.
+ * @param {unknown} raw
+ * @param {(text: string) => { cleaned: string }} layer1
+ * @param {number} [cap]
+ * @returns {string}
+ */
+export function scrubUntrustedText(raw: unknown, layer1: (text: string) => {
+    cleaned: string;
+}, cap?: number): string;
+/**
+ * Message from a caught value, which is `unknown` under strict mode. Appends
+ * the cause chain (one level) when the cause is itself an Error so callers
+ * get "outer: root" instead of just "outer" when an error wraps another.
+ * @param {unknown} err
+ * @returns {string}
+ */
+export function errMessage(err: unknown): string;
+/**
+ * errMessage() for an error whose message may embed attacker-chosen bytes: V8
+ * quotes a snippet of the offending input in a JSON.parse SyntaxError, so a hook
+ * that splices errMessage(err) into a user-/model-facing reason would relay raw
+ * ANSI escapes and invisible/format characters lifted from that snippet. Keep only
+ * printable ASCII (plus tab/newline) and drop every other code point — dropping the
+ * ESC/CSI-introducer and zero-width bytes neutralizes the sequence while leaving the
+ * residual literal text readable — then cap the length so a long snippet can't flood
+ * the reason. Use this instead of errMessage at any callsite that splices the
+ * message into a reason/warning shown to the user or model.
+ * @param {unknown} err
+ * @param {number} [cap]
+ * @returns {string}
+ */
+export function safeErrMessage(err: unknown, cap?: number): string;
+/**
+ * Write the `hookSpecificOutput` envelope a hook returns to stdout.
+ * @param {string} hookEventName
+ * @param {Record<string, unknown>} fields
+ * @returns {void}
+ */
+export function emitHookResponse(hookEventName: string, fields: Record<string, unknown>): void;
+/**
+ * Is the file at `path` one WE wrote — a regular file owned by this uid — rather
+ * than a squat? These markers live at predictable, world-visible $TMPDIR paths, so
+ * a co-tenant could pre-plant a file (or a symlink at the path) to steer a gate.
+ * lstatSync does NOT traverse a final symlink, so a planted symlink reads as a
+ * symlink (isFile() false) and a foreign file fails the uid check: either way the
+ * marker is untrusted and the caller ignores it.
+ * @param {string | null} path
+ * @returns {boolean}
+ */
+export function markerIsTrusted(path: string | null): boolean;
+/**
+ * Create a presence sentinel at `path` without following a symlink a co-tenant
+ * may have pre-planted there. These sentinels live at predictable, world-visible
+ * paths under $TMPDIR (a project-hash or fixed name), so a plain writeFileSync —
+ * which opens O_CREAT|O_TRUNC and follows a symlink at the path — would let
+ * anyone able to plant that symlink redirect the write and truncate an arbitrary
+ * file the hook's user owns. Unlink any existing entry first (removing a squatted
+ * symlink), then create exclusively (O_EXCL) so a symlink re-planted in the race
+ * window fails the open rather than being dereferenced. Content is irrelevant —
+ * callers test only for existence — so the file is left empty. Best-effort: a
+ * missing/read-only $TMPDIR or a lost race just leaves the sentinel absent, and
+ * every caller treats "absent" as "not yet done" (a repeated ask, never a crash),
+ * so all failures are swallowed.
+ * @param {string} path
+ * @returns {void}
+ */
+export function writeSentinelFile(path: string): void;
+/**
+ * Write `content` to `path` without following a symlink a co-tenant may have
+ * pre-planted there — the content-bearing counterpart to writeSentinelFile. These
+ * hooks write to predictable, world-visible $TMPDIR paths (a project-hash name, or
+ * a content-addressed digest an attacker who chose the input bytes can precompute),
+ * so a plain writeFileSync — which opens O_CREAT|O_TRUNC and follows a final
+ * symlink — would let anyone able to plant that symlink redirect the write and
+ * truncate/overwrite an arbitrary file the hook's user owns. Unlink any existing
+ * entry first (removing a squatted symlink), then create exclusively (O_EXCL via
+ * "wx") so a symlink re-planted in the unlink→open race window fails the open
+ * rather than being dereferenced. Returns true on success, false when the write
+ * could not be completed (unwritable dir, or a lost race) so the caller decides
+ * whether a failed best-effort write is fatal.
+ * @param {string} path
+ * @param {string} content
+ * @param {number} [mode]
+ * @returns {boolean}
+ */
+export function writeFileNoFollow(path: string, content: string, mode?: number): boolean;
+/** Claude Code hook event names (the hookEventName field). */
+export const HookEvent: Readonly<{
+    PRE_TOOL_USE: "PreToolUse";
+    POST_TOOL_USE: "PostToolUse";
+    USER_PROMPT_SUBMIT: "UserPromptSubmit";
+    SESSION_START: "SessionStart";
+}>;
+/** Claude Code permissionDecision verdicts. */
+export const PermissionDecision: Readonly<{
+    ALLOW: "allow";
+    DENY: "deny";
+    ASK: "ask";
+}>;
+/**
+ * Hard cap on hook stdin. A well-formed Claude Code hook payload is at most a
+ * few MB (tool input plus the harness-truncated tool output); 64 MiB leaves
+ * generous headroom while refusing a runaway or malformed sender before its
+ * bytes are buffered into memory — an unbounded read would OOM the hook process
+ * and take its own fail-closed output down with it.
+ */
+export const MAX_STDIN_BYTES: number;

package/types/claude-hooks/lib/invisible-alert.d.mts

@@ -0,0 +1,44 @@
+/**
+ * The alert findings if invisible-char injection was detected in instruction
+ * files and couldn't be auto-cleaned, else null. ALERT_FILE lives at a predictable,
+ * world-visible $TMPDIR path, so its contents are attacker-writable (a co-tenant can
+ * plant a file/symlink there): trust it only when markerIsTrusted confirms a regular
+ * file THIS uid owns (a squatted symlink/foreign file reads as no alert), then scrub
+ * the bytes through Layer-1 before any caller splices them into a reason — the report
+ * would otherwise carry ANSI/invisible spoofing into the model's context.
+ * @returns {string | null}
+ */
+export function invisibleCharAlert(): string | null;
+/**
+ * True once the gate has surfaced its blocking ask this session. Validates
+ * ownership (not mere existence): a co-tenant could pre-create ALERT_ACK_FILE at its
+ * predictable $TMPDIR path to permanently suppress the one-time blocking ask down to
+ * the passive reminder, so trust the marker only when it is a regular file this uid
+ * wrote (markerIsTrusted), mirroring how acknowledgeAlert writes it.
+ * @returns {boolean}
+ */
+export function alertAcknowledged(): boolean;
+/**
+ * Record that the gate has surfaced its blocking ask, so later tool calls get a
+ * passive reminder instead of an ask on every call. Cleared at SessionStart by
+ * the scanner so each fresh session re-asks once.
+ * @returns {void}
+ */
+export function acknowledgeAlert(): void;
+/**
+ * @param {string} findings
+ * @returns {string}
+ */
+export function gateAskReason(findings: string): string;
+/**
+ * Non-blocking reminder for tool calls after the first ask: the injection is
+ * still present, but the user was already asked once this session, so this rides
+ * as context rather than re-prompting on every call.
+ * @returns {string}
+ */
+export function gateReminderContext(): string;
+/** The project the hooks are guarding; the alert paths are keyed to it. */
+export const PROJECT_DIR: string;
+/** Findings the SessionStart scanner could not clean, for the PreToolUse gate. */
+export const ALERT_FILE: string;
+export const ALERT_ACK_FILE: string;

package/types/claude-hooks/lib/redactor-client.d.mts

@@ -0,0 +1,134 @@
+/**
+ * Parse a millisecond deadline from an env override, falling back to `fallback`
+ * unless the value is a finite positive number. A bare `Number(env) || fallback`
+ * silently accepts a NEGATIVE override (`-5 || 8000` is -5) — a non-positive
+ * deadline makes the fail-closed wait/request return immediately, defeating the
+ * deadline. Unset/blank/NaN/<=0 all take the sane positive fallback; a load-time
+ * throw is deliberately avoided so a misconfigured env can never crash these
+ * fail-closed hooks into a fail-OPEN non-load.
+ * @param {string|undefined} raw the env override value
+ * @param {number} fallback the sane positive default
+ * @returns {number}
+ */
+export function positiveMsOr(raw: string | undefined, fallback: number): number;
+/**
+ * The shape the redactor returns: plain mode `{text, found}`, map mode
+ * `{text, pairs, found}` or `{unmappable}`. All fields optional so a consumer
+ * narrows the variant it expects.
+ * @typedef {object} RedactResponse
+ * @property {string} [text]
+ * @property {string[]} [found]
+ * @property {{placeholder: string, original: string, start: number}[]} [pairs]
+ * @property {string} [unmappable]
+ */
+/**
+ * Classify the socket path before we connect and hand it live credentials.
+ * The request body carries collectEnvSecrets() — plaintext key VALUES — and the
+ * socket lives at a predictable, world-visible $TMPDIR path any co-tenant can
+ * reach. This is the one channel in the hook suite that ships secrets, so it
+ * needs the same squat defense markerIsTrusted / writeFileNoFollow apply to the
+ * marker/sentinel files. lstatSync does NOT traverse a final symlink, so a
+ * planted symlink reads as a symlink (isSocket() false) and a foreign daemon
+ * fails the uid check.
+ *   - "absent"    → nothing there yet: let createConnection ENOENT so the caller's
+ *                   respawn path spawns OUR daemon (never a refuse — that would
+ *                   break the cold-start spawn).
+ *   - "untrusted" → something IS bound there but it is not our socket under a dir
+ *                   only a trusted uid can write (a co-tenant squat): refuse, so
+ *                   no secret is written.
+ *   - "ok"        → our socket, our uid, under a dir isTrustedSocketDir accepts.
+ * `lstat`/`uid` are injectable seams so a test can drive a stat shape the test
+ * process cannot create (a dir owned by another uid); production binds the real ones.
+ * @param {string} socketPath
+ * @param {{lstat?: typeof lstatSync, uid?: number}} [deps]
+ * @returns {"absent" | "untrusted" | "ok"}
+ */
+export function classifySocket(socketPath: string, deps?: {
+    lstat?: typeof lstatSync;
+    uid?: number;
+}): "absent" | "untrusted" | "ok";
+/**
+ * Open one connection, send `request`, resolve with the parsed response object
+ * (or null). Rejects on connect failure, a malformed/oversize/short frame, or an
+ * {error} response — every one of which the caller turns into a fail-closed. A
+ * socket present but not owned by us fails closed WITHOUT respawning (the error
+ * carries no errno, so isRespawnable is false), so we never dial into a squat.
+ * @param {string} socketPath
+ * @param {{text: string, map: boolean, web_ingress: boolean}} request
+ * @param {number} [deadlineMs] total exchange deadline; defaults to the env-tunable value
+ * @returns {Promise<RedactResponse|null>}
+ */
+export function connectAndRequest(socketPath: string, request: {
+    text: string;
+    map: boolean;
+    web_ingress: boolean;
+}, deadlineMs?: number): Promise<RedactResponse | null>;
+/**
+ * Spawn the daemon detached so it outlives this hook process. The daemon's bind()
+ * is the cross-process mutex, so a racing second spawn just exits — the spawn is
+ * idempotent and needs no lock here.
+ * @param {string} socketPath
+ * @param {string[]} [command] daemon command as [argv0, ...leadingArgs]
+ * (injectable so tests can drive the missing-binary arm in-process;
+ * production always uses daemonCommand())
+ */
+export function spawnDaemon(socketPath: string, command?: string[]): void;
+/**
+ * Poll until the daemon is accepting connections or the deadline passes. Probes by
+ * connecting (not just existsSync) so it waits for listen(), not merely bind().
+ * @param {string} socketPath
+ * @param {{deadlineMs?: number, stepMs?: number}} [opts]
+ * @returns {Promise<boolean>}
+ */
+export function waitForSocket(socketPath: string, { deadlineMs, stepMs }?: {
+    deadlineMs?: number;
+    stepMs?: number;
+}): Promise<boolean>;
+/**
+ * Redact `text` via the daemon. Returns the response object (`{text, found}` for
+ * plain, `{text, pairs, found}` / `{unmappable}` for map) or null when nothing was
+ * redacted (plain mode). Throws to fail closed when the text cannot be vetted.
+ *
+ * `connect`/`spawn`/`waitForSocket` are injectable seams (default to the real
+ * implementations) so callers can stub the daemon in-process. `deadline` is the
+ * caller's shared wall-clock budget (makeDeadline): when supplied, every dial and
+ * the respawn wait are bounded by the budget REMAINING at that moment, and a spent
+ * budget fails CLOSED without dialing — never dial with a non-positive deadline,
+ * which would race and could return the raw, unvetted secret (fail open). Omitted,
+ * the redactor keeps its own per-call request deadline (the standalone default).
+ * @param {string} text
+ * @param {{map?: boolean, webIngress?: boolean, socketPath?: string,
+ *   deadline?: {remainingMs: () => number},
+ *   connect?: typeof connectAndRequest, spawn?: typeof spawnDaemon,
+ *   waitForSocket?: typeof waitForSocket}} [opts]
+ * @returns {Promise<RedactResponse|null>}
+ */
+export function redactViaDaemon(text: string, opts?: {
+    map?: boolean;
+    webIngress?: boolean;
+    socketPath?: string;
+    deadline?: {
+        remainingMs: () => number;
+    };
+    connect?: typeof connectAndRequest;
+    spawn?: typeof spawnDaemon;
+    waitForSocket?: typeof waitForSocket;
+}): Promise<RedactResponse | null>;
+export const FRAME_CAP: number;
+export const DEFAULT_SOCKET_PATH: string;
+/**
+ * The shape the redactor returns: plain mode `{text, found}`, map mode
+ * `{text, pairs, found}` or `{unmappable}`. All fields optional so a consumer
+ * narrows the variant it expects.
+ */
+export type RedactResponse = {
+    text?: string | undefined;
+    found?: string[] | undefined;
+    pairs?: {
+        placeholder: string;
+        original: string;
+        start: number;
+    }[] | undefined;
+    unmappable?: string | undefined;
+};
+import { lstatSync } from "node:fs";

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

@@ -0,0 +1,26 @@
+/**
+ * Persist one reveal's pre-splice text and return the model-facing hint naming
+ * its path, or null when the write fails (the splice already protected the
+ * output, so a failed convenience write must not break sanitization). The store
+ * dir is verified private/uid-owned and the file is created symlink-refusingly
+ * (O_EXCL): the path is content-addressed, so an attacker who chose the page bytes
+ * can precompute it and pre-plant a symlink there to redirect this write onto a
+ * victim file — writeFileNoFollow refuses that instead of following it.
+ * @param {string} content
+ * @returns {string | null}
+ */
+export function persistReveal(content: string): string | null;
+/**
+ * True when this PostToolUse event is a Read of a reveal sidecar file, so its
+ * output must be marked untrusted even though Read is otherwise a trusted local
+ * tool. Containment is checked against the lexically resolved path with a
+ * trailing separator so a sibling dir sharing the prefix (…-reveal-evil) cannot
+ * pass. The model picks what it Reads (no attacker-planted symlinks to escape),
+ * so lexical resolution — not realpath — is the right boundary here.
+ * @param {string} toolName
+ * @param {any} toolInput
+ * @returns {boolean}
+ */
+export function isRevealRead(toolName: string, toolInput: any): boolean;
+/** Envelope prepended to a reveal-file Read so its bytes are framed as untrusted. */
+export const REVEAL_READ_ENVELOPE: string;

package/types/claude-hooks/lib/secret-annotate.d.mts

@@ -0,0 +1,19 @@
+/**
+ * Regex matching `value` tolerating invisible chars spliced between its
+ * characters (mirrors the engine's env-value regex). Code-point split so
+ * an astral character is escaped whole, not as two surrogate halves.
+ * @param {string} value
+ * @returns {RegExp}
+ */
+export function envValueRegex(value: string): RegExp;
+/**
+ * True when tool output contains the literal value of a configured env-bound
+ * secret. The shape-based secret hint can't match a prefix-less key or a host
+ * credential, so the pre-gate must also fire on the value itself — otherwise
+ * the engine's env-bound redaction never runs. Invisible-tolerant so a
+ * value with spliced Cf chars (which the daemon still redacts) trips it too.
+ * @param {string} text
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {boolean}
+ */
+export function hasEnvBoundSecret(text: string, env?: NodeJS.ProcessEnv): boolean;

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

@@ -0,0 +1,21 @@
+/**
+ * Numeric verbosity from _AGENT_SANITIZER_TRACE: 0 off, 1 info, 2 debug.
+ * Unknown, empty, or "off" → 0.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {number}
+ */
+export function traceThreshold(env?: NodeJS.ProcessEnv): number;
+/**
+ * Emit one JSON trace line for `event` at `level` (default "info") carrying the
+ * metadata `fields`. No-op when the channel is below `level`; best-effort on write.
+ * @param {string} event
+ * @param {Record<string, unknown>} [fields]
+ * @param {"info"|"debug"} [level]
+ * @returns {void}
+ */
+export function trace(event: string, fields?: Record<string, unknown>, level?: "info" | "debug"): void;
+/** Trace-channel event names. */
+export const TraceEvent: Readonly<{
+    HOOK_RAN: "hook_ran";
+    SCAN_INVISIBLE_CHARS_RAN: "scan_invisible_chars_ran";
+}>;

package/types/claude-hooks/plugin-hooks.d.mts

@@ -0,0 +1,7 @@
+/**
+ * Dispatch to the hook named by `--hook=<name>` in argv. Exported and guarded by
+ * isMain below so importing this module (the published entry point) is a no-op:
+ * only a direct `node plugin-hooks.mjs --hook=…` run consumes stdin and exits.
+ * @returns {Promise<void>}
+ */
+export function main(): Promise<void>;

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

@@ -0,0 +1,47 @@
+/**
+ * Compose the four protections. Returns the `hookSpecificOutput` fields to
+ * emit, or null for a clean no-op. Throws only if a layer's engine throws; the
+ * caller fails closed (ask) on any throw. Every exit routes through emitTraced.
+ * @param {any} input parsed PreToolUse event
+ * @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)
+ * @returns {Promise<Record<string, unknown> | null>}
+ */
+export function buildPreToolUseResponse(input: any, rehydrate?: (tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>): 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
+ * sanitization pipeline through its own adapter. The wired Claude CLI below
+ * routes through this judge and renders the Verdict with the Claude adapter; on
+ * any throw (a control-plane package-load failure included) it falls back to
+ * failClosedFields — a native response that needs no package — so the
+ * 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]
+ * @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>): Promise<import("agent-control-plane-core").Verdict>;
+/**
+ * The fail-closed hookSpecificOutput fields for a hook-level failure, chosen by
+ * WHICH failure it was. Corrupt/unparsable INPUT (`parsedOk` false — a JSON parse
+ * error or the oversize-body cap) is a state an adversary can induce with no
+ * upside to failing, so it hard-DENIES: no human to talk past, no approval
+ * fatigue, no latency. A LAYER/engine throw after a clean parse (`parsedOk` true
+ * — redactor daemon down, package not loaded) is the sanitizer being UNAVAILABLE,
+ * so it ASKS to keep a human in the loop rather than hard-block on infrastructure.
+ * @param {boolean} parsedOk whether the input parsed before the failure
+ * @param {unknown} err
+ * @returns {Record<string, unknown>}
+ */
+export function failClosedFields(parsedOk: boolean, err: unknown): Record<string, 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.
+ * @returns {Promise<void>}
+ */
+export function cliMain(): Promise<void>;
+declare const rehydrateRedacted: typeof import("agent-sanitizer/rehydrate").rehydrateRedacted;
+export {};

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

@@ -0,0 +1,168 @@
+/**
+ * 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
+ * the HTML rewrite (Layer 2) and the exfil-URL scan (Layer 3), the injected
+ * secret redactor (Layer 4), and the display-only-SGR carve-out. `reveal` carries
+ * the seam's pre-Layer-2 text when the HTML splice removed anything, for the
+ * orchestrator to persist.
+ * @param {string} text
+ * @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
+ * @returns {Promise<{ cleaned: string, warnings: string[], modified: boolean, sgrNote: boolean, reveal?: string }>}
+ */
+export function sanitizeText(text: string, toolName: string, deadline?: {
+    remainingMs: () => number;
+}): Promise<{
+    cleaned: string;
+    warnings: string[];
+    modified: boolean;
+    sgrNote: boolean;
+    reveal?: string;
+}>;
+/**
+ * Sanitize every string leaf of a tool-output value, preserving its shape.
+ * Built-in tools return structured objects (Bash: `{stdout, stderr, interrupted,
+ * isImage}`), and the harness ignores an `updatedToolOutput` whose shape does not
+ * match the tool's schema — showing the raw output instead. So a single flat
+ * string handed back for an object-shaped tool would leak the unsanitized output;
+ * rewriting leaves in place keeps the shape intact. Object KEYS are sanitized
+ * too (a connector can hide a secret in a field name); non-string leaves
+ * (booleans, numbers, null) pass through untouched, and `warnings` accumulates
+ * across leaves.
+ * `sgrNote` is the OR across leaves: true when some leaf was an SGR-only strip.
+ * `reveals` accumulates each leaf's pre-Layer-2 text (when the HTML splice
+ * removed something) for the orchestrator to persist — same mutated-accumulator
+ * shape as `warnings`.
+ * @param {any} value
+ * @param {string} toolName
+ * @param {string[]} warnings
+ * @param {string[]} [reveals]
+ * @param {{remainingMs: () => number}} [deadline] shared wall-clock budget across
+ *   every leaf of this value (created once by the top-level caller)
+ * @returns {Promise<{ value: any, modified: boolean, sgrNote: boolean }>}
+ */
+export function sanitizeValue(value: any, toolName: string, warnings: string[], reveals?: string[], deadline?: {
+    remainingMs: () => number;
+}): Promise<{
+    value: any;
+    modified: boolean;
+    sgrNote: boolean;
+}>;
+/**
+ * Compose the model-facing additionalContext line for a sanitized/flagged tool
+ * output. The seam (composeContextSeam) owns the prefix + warning join; this
+ * binds the untrusted-ingress classification to the seam's `injectionAlert` slot
+ * — the semantic-injection alert rides ONLY on web/MCP output, the channel where
+ * injected natural language actually arrives (see isUntrustedIngress). On local
+ * tools (Read, Bash, Grep, gh) the alert on a plain ANSI/secret strip is pure
+ * noise that desensitizes the reader to the one place it matters, so it is
+ * omitted.
+ * @param {boolean} modified  output bytes were changed (vs. flagged only)
+ * @param {string[]} warnings
+ * @param {string} toolName
+ * @returns {string}
+ */
+export function composeContext(modified: boolean, warnings: string[], toolName: string): string;
+/**
+ * Fail-closed replacement: a shape-matching placeholder for the parsed tool
+ * output, or the bare `message` when stdin never parsed or carried no
+ * tool_response (no shape to match).
+ * @param {any} input  parsed hook input, or undefined if parsing threw
+ * @param {string} message
+ * @returns {any}
+ */
+export function failClosedReplacement(input: any, message: string): any;
+/**
+ * Whether the sanitizer's bindings actually loaded. lazyImport swallows a
+ * missing package and yields `{}`, so the absence shows up as an undefined
+ * binding here — NOT as a "Cannot find package" error, which the failing call
+ * site (a TypeError on an undefined function) never carries. Testing the
+ * binding is therefore the only detection that fires on the real condition.
+ * @returns {boolean}
+ */
+export function sanitizerDepsLoaded(): boolean;
+/**
+ * The model-facing note for a fail-closed emission, with the missing-dependency
+ * remedy appended when the sanitizer's bindings are the thing that is absent.
+ * @param {() => boolean} [depsLoaded]  injectable seam for testing
+ * @returns {string}
+ */
+export function failClosedContext(depsLoaded?: () => boolean): string;
+/**
+ * Emit a fail-closed PostToolUse response, robust to the suppression itself
+ * throwing. The shape-matching replacement walks `input.tool_response` and the
+ * emit serializes it; a pathologically deep (but valid-JSON) tool_response
+ * overflows that walk or `JSON.stringify`, which — left uncaught in the CLI's
+ * own catch — would exit non-zero with NO response, and the harness would then
+ * show the RAW, unvetted output (fail OPEN). The fallback emits the bare
+ * `message` string instead: shallow, always serializable, and a valid string
+ * tool_response, so the hook still fails CLOSED. `emit` is an injectable seam so
+ * the fallback is unit-testable without a subprocess.
+ * @param {any} input  parsed hook input, or undefined if parsing threw
+ * @param {string} message
+ * @param {(fields: Record<string, unknown>) => void} [emit]
+ * @returns {void}
+ */
+export function emitFailClosed(input: any, message: string, emit?: (fields: Record<string, unknown>) => void): void;
+/**
+ * Run the sanitization pipeline over a tool output and return the contract-
+ * shaped verdict fields — `mutated_output` (the shape-matching sanitized value)
+ * and/or `additional_context` (the model-facing note) — or null when there is
+ * nothing to change (no tool output, or a clean scan). Agent-neutral by
+ * construction: it speaks the control-plane vocabulary, never Claude's native
+ * `updatedToolOutput`/`additionalContext` wire keys (the adapter renders those).
+ * Every exit routes through `emit`, which announces engagement on the trace
+ * channel (hook_ran — metadata only: hook name, tool, outcome) and returns the
+ * 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
+ * @returns {Promise<{ mutated_output?: unknown, additional_context?: string } | null>}
+ */
+export function evaluateToolOutput(input: any): Promise<{
+    mutated_output?: unknown;
+    additional_context?: string;
+} | null>;
+/**
+ * Judge a normalized PostToolUse event: run the sanitization pipeline and
+ * express its outcome as a control-plane Verdict. sanitize-output only ever
+ * ALLOWS — the tool already ran, so this governs the model's VIEW of the
+ * output, not the side effect. It either rewrites that view (`mutated_output`),
+ * attaches a warning (`additional_context`), or does neither (a bare allow).
+ * {@link evaluateToolOutput} already returns those contract fields (or null),
+ * so the judge only stamps the `allow` decision onto them — no native-envelope
+ * 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
+ * @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>;
+/**
+ * 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
+ * omits the field is a PostToolUse call by construction. The claude adapter
+ * extracts `tool_response` (this hook's actual input) ONLY for a PostToolUse
+ * event; without this default a field-less but legitimate payload would parse as
+ * UNKNOWN, {@link judgeSanitizeOutput} would throw, and the CLI would fail closed
+ * (suppress) on real tool output. A payload carrying a DIFFERENT event name is
+ * left untouched, so the judge's UNKNOWN guard still fails closed on a genuinely
+ * unrecognized event.
+ * @param {unknown} input  the raw stdin payload
+ * @returns {unknown}
+ */
+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.
+ * @returns {Promise<void>}
+ */
+export function cliMain(): Promise<void>;
+export const applyLayer1: typeof import("agent-sanitizer").applyLayer1;
+export const matchesSecretHint: typeof import("agent-sanitizer").matchesSecretHint;
+export const SECRET_HINT: RegExp;
+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;

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

@@ -0,0 +1,23 @@
+/**
+ * Judge a normalized prompt-submit event. Agent-agnostic: consumes the
+ * control-plane ToolCallEvent and returns a Verdict, so the same prompt gate
+ * renders through any agent adapter, not just Claude's. Throws (into the
+ * calling hook's catch) when the sanitizer package never loaded — this hook is
+ * the only defense on user input, so a prompt it cannot classify must block,
+ * never pass through.
+ * @param {import("agent-control-plane-core").ToolCallEvent} event
+ * @param {((s: string) => string) | null} [strip]  the ANSI stripper (defaults
+ *   to the package's stripAnsiFully; injectable so the fail-closed path is testable)
+ * @returns {import("agent-control-plane-core").Verdict}
+ */
+export function judgeSanitizeUserPrompt(event: import("agent-control-plane-core").ToolCallEvent, strip?: ((s: string) => string) | null): import("agent-control-plane-core").Verdict;
+/**
+ * @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)
+ * @returns {Promise<void>}
+ */
+export function main(read: () => Promise<any> | any, write: (chunk: string) => void, strip?: ((s: string) => string) | null): 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

@@ -0,0 +1,64 @@
+/**
+ * The hook's CLI: scan the instruction files, auto-clean what it can, persist
+ * 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.
+ * @returns {Promise<void>}
+ */
+export function cliMain(): Promise<void>;
+/**
+ * @param {string} run
+ * @returns {{ method: string, decoded: string }}
+ */
+export function decodeRun(run: string): {
+    method: string;
+    decoded: string;
+};
+/**
+ * @param {string} dir
+ * @returns {string[]}
+ */
+export function findMdFiles(dir: string): string[];
+/**
+ * Every subdirectory instruction file (CLAUDE.md, CLAUDE.local.md, AGENTS.md)
+ * under `dir`. Claude Code loads these as project instructions on entry to their
+ * containing directory — a load path that bypasses the PostToolUse sanitizer — so
+ * a payload planted in e.g. `packages/foo/CLAUDE.md` reaches the model uncleaned
+ * unless it is scanned here. Skips node_modules; `**` skips dot directories by
+ * default (`.git`, and `.claude`, which the caller scans separately).
+ * @param {string} dir
+ * @returns {string[]}
+ */
+export function findInstructionFiles(dir: string): string[];
+/**
+ * @param {string} filePath
+ * @returns {Array<{ line: number, charCount: number, method: string, decoded: string }>}
+ */
+export function scanFile(filePath: string): Array<{
+    line: number;
+    charCount: number;
+    method: string;
+    decoded: string;
+}>;
+import { ALERT_FILE } from "./lib/invisible-alert.mjs";
+import { ALERT_ACK_FILE } from "./lib/invisible-alert.mjs";
+export const LONG_RUN_RE: RegExp;
+export const LONG_RUN_THRESHOLD: 10;
+export const TOTAL_INVISIBLE_THRESHOLD: 30;
+/**
+ * @param {Array<{
+ *   file: string,
+ *   findings: Array<{ line: number, charCount: number, method: string, decoded: string }>,
+ * }>} allFindings
+ * @returns {string}
+ */
+export function formatReport(allFindings: Array<{
+    file: string;
+    findings: Array<{
+        line: number;
+        charCount: number;
+        method: string;
+        decoded: string;
+    }>;
+}>): string;
+export { ALERT_FILE, ALERT_ACK_FILE };