agent-sanitizer 2.4.0 → 2.4.1

package/README.md

@@ -30,11 +30,9 @@ placeholders where hidden HTML was spliced out.
 
 ## Entry points
 
-Split into subpaths so the heavy HTML dependency stays opt-in. The **seam**
-column marks entry points that inject the agent-specific concern (a callback
-you supply) rather than baking it in; `—` means the function is a pure
-transform with no such hook, and `fs (direct)` means it does its own file I/O
-(Node's filesystem, not an agent harness) instead of taking a callback.
+Split into subpaths so the heavy HTML dependency stays opt-in. **Seam** names
+the callback you inject for the agent-specific concern; `—` is a pure transform,
+`fs (direct)` does its own file I/O instead of taking one.
 
 | #   | Import          | Purpose                                                                                                                                                    | Seam                        |
 | --- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
@@ -69,16 +67,12 @@ without notice.
 
 ### `FILTER_WARNING` codes (Layer 5)
 
-The Layer-5 `filterInjection` seam is deliberately thin: the injected filter may
-only ask for **verbatim span deletions** (`removeSpans`) and may only warn with a
-**closed enum code** (`warning`), never free text. Because the filter runs on
-attacker-influenced content and its `warning` would otherwise be concatenated
-straight into the model-facing context **without** re-passing Layer 1, a
-compromised or prompt-injected filter emitting arbitrary text would defeat the
-"a compromised filter can only remove bytes, never inject" contract. So the
-**library owns the message** for each code, and a filter returning any value
-outside this enum makes `sanitizeText` **throw** (fail loud). Branch on the code,
-like `found`:
+The Layer-5 `filterInjection` seam is deliberately thin: the filter may only
+request **verbatim span deletions** (`removeSpans`) and warn with a **closed
+enum code**, never free text. Its warning reaches the model-facing context
+without re-passing Layer 1, so a prompt-injected filter emitting arbitrary text
+would defeat the "can only remove bytes, never inject" contract. The library
+owns each message, and any value outside the enum makes `sanitizeText` **throw**:
 
 | `FILTER_WARNING` code | Meaning                                                                                 |
 | --------------------- | --------------------------------------------------------------------------------------- |
@@ -88,120 +82,57 @@ like `found`:
 
 ## Using it with Claude Code
 
-The entry points above are a library — you supply the wiring. For Claude Code
-the wiring is already written, as four hooks that put Layers 1–4 on the tool
-stream: tool input, tool output, user prompts, and a session-start scan of the
-instruction files.
-
-### The plugin (recommended)
+Four hooks put Layers 1–4 on the tool stream: tool input, tool output, user
+prompts, and a session-start scan of the instruction files.
 
 ```
 /plugin marketplace add AlexanderMattTurner/agent-sanitizer
 /plugin install agent-sanitizer@agent-sanitizer
 ```
 
-The plugin ships a self-contained bundle and a committed Python zipapp of the
-secret-redaction engine, so it needs no `node_modules` and no install step
-beyond a `python3` on PATH.
-
-### Without the plugin
+The plugin needs no `node_modules` and no build step — just `python3` on PATH
+for Layer 4.
 
-Install the package and point your `settings.json` at the published hook entry.
-One entry point dispatches all four modes on `--hook=`:
+To wire them yourself instead, one entry dispatches all four modes on `--hook=`:
 
 ```jsonc
+// settings.json — one entry per event; PreToolUse/PostToolUse also take "matcher": "*"
 {
-  "hooks": {
-    "UserPromptSubmit": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node ./node_modules/agent-sanitizer/claude-hooks/plugin-hooks.mjs --hook=sanitize-user-prompt",
-          },
-        ],
-      },
-    ],
-    "PreToolUse": [
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node ./node_modules/agent-sanitizer/claude-hooks/plugin-hooks.mjs --hook=pretooluse-sanitize",
-          },
-        ],
-      },
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node ./node_modules/agent-sanitizer/claude-hooks/plugin-hooks.mjs --hook=sanitize-output",
-          },
-        ],
-      },
-    ],
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node ./node_modules/agent-sanitizer/claude-hooks/plugin-hooks.mjs --hook=scan-invisible-chars",
-          },
-        ],
-      },
-    ],
-  },
+  "type": "command",
+  "command": "node ./node_modules/agent-sanitizer/claude-hooks/plugin-hooks.mjs --hook=sanitize-output",
 }
 ```
 
-Resolve the path however your project prefers — `require.resolve("agent-sanitizer/claude-hooks")` gives it without hardcoding a layout. Importing the module instead of spawning it is a no-op, so a build step that pulls it in will not consume stdin.
+| Event              | `--hook=`              |
+| ------------------ | ---------------------- |
+| `UserPromptSubmit` | `sanitize-user-prompt` |
+| `PreToolUse`       | `pretooluse-sanitize`  |
+| `PostToolUse`      | `sanitize-output`      |
+| `SessionStart`     | `scan-invisible-chars` |
 
-**Layer 4 needs the Python engine.** Secret redaction runs out-of-process
-against `agent-secret-redactor-daemon`, from the `secrets` extra on PyPI:
-
-```bash
-pip install 'agent-sanitizer[secrets]'   # version-match the npm package
-```
+`require.resolve("agent-sanitizer/claude-hooks")` gives the path without
+hardcoding a layout. Importing the module rather than spawning it is a no-op.
 
-Without it, `sanitize-output` **fails closed** on secret-shaped output — the
-tool result is suppressed and replaced with a placeholder rather than shown
-unvetted. That is the intended posture, not a degradation to ignore: Layers 1–3
-still run, but a missing daemon means every secret-shaped output is withheld.
+**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.
 
-**Layer 5 (second-model injection filtering) is not included.** The `/output`
-seam accepts a `filterInjection` callback, but these hooks never supply one, so
-nothing here calls out to a model or leaves the machine.
+**Layer 5 (second-model injection filtering) is not included.** These hooks
+never supply the `/output` seam's `filterInjection` callback, so nothing here
+calls a model or leaves the machine.
 
-### Internal environment variables
-
-These tune the hooks' internals. They are **not a stable interface** — they
-carry a leading underscore and may change between minor versions. The stable
-surface is the `--hook=` CLI and the settings wiring above.
-
-| Variable                               | Effect                                                             |
-| -------------------------------------- | ------------------------------------------------------------------ |
-| `_AGENT_SANITIZER_REDACTOR_DAEMON`     | Path to the redactor daemon binary                                 |
-| `_AGENT_SANITIZER_REDACTOR_SOCKET`     | Unix socket the daemon binds; per-session and private by default   |
-| `_AGENT_SANITIZER_REDACTOR_WAIT_MS`    | How long to wait for a freshly spawned daemon to accept            |
-| `_AGENT_SANITIZER_REDACTOR_REQUEST_MS` | Deadline for one request; bounds a daemon that accepts then stalls |
-| `_AGENT_SANITIZER_SANITIZE_BUDGET_MS`  | Total wall-clock budget for one hook run's daemon calls            |
-| `_AGENT_SANITIZER_TRACE`               | `info` or `debug` to emit one JSON line per layer engagement       |
-| `_AGENT_SANITIZER_TRACE_FILE`          | Trace sink; stderr when unset                                      |
-| `_AGENT_SANITIZER_REVEAL_DIR`          | Where Layer 2 stores pre-splice text for the model to read back    |
+Hook internals are tuned by `_AGENT_SANITIZER_*` variables (redactor daemon
+path/socket/timeouts, sanitize budget, trace channel, Layer-2 reveal dir). The
+leading underscore marks them unstable — the supported surface is the `--hook=`
+CLI above.
 
 ## How this compares
 
-The "sanitize untrusted LLM input" space mostly splits into two camps: ML
-classifiers that score a prompt's _intent_ (Lakera Guard, Meta's Prompt
-Guard, Rebuff, NeMo Guardrails' input rails), and PII-focused redactors
-(Microsoft Presidio). Neither targets the byte-level hiding channel this
-library covers, and that gap is exactly where invisible-Unicode and
-hidden-HTML payloads live—content a semantic classifier never "sees" as
-suspicious because it renders as blank space or doesn't render at all.
+The space splits into ML classifiers that score a prompt's _intent_ (Lakera
+Guard, Meta's Prompt Guard, Rebuff, NeMo Guardrails) and PII redactors
+(Presidio). Neither targets the byte-level hiding channel — content a semantic
+classifier never "sees" as suspicious because it renders as blank space or
+doesn't render at all.
 
 |                               | `agent-sanitizer`                                                                                                        | Semantic guard/classifier (Lakera, Prompt Guard, Rebuff, NeMo rails)                                       | PII redactor (Presidio)                                      |
 | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
@@ -213,13 +144,10 @@ suspicious because it renders as blank space or doesn't render at all.
 | **Reversibility**             | `/rehydrate` re-anchors a model's edit from the sanitized view back onto real bytes, denying anything ambiguous          | N/A—classifiers only pass/block, they don't rewrite-and-reverse                                            | N/A                                                          |
 | **Non-JS support**            | Same verdicts via a bundled CLI/worker—Python client included, no reimplementation                                       | Usually a hosted API (language-agnostic) or Python-only SDK                                                | Python-first (spaCy-based)                                   |
 
-In practice these are complementary, not competing: run a semantic guard for
-intent, Presidio for PII you must not leak, and this library for the hidden
-channel both of those are blind to. If you already run a classifier and are
-still getting bitten by zero-width payloads or `display:none` instructions
-riding along in RAG context, that's the gap this library closes.
+These are complementary: a semantic guard for intent, Presidio for PII, and this
+for the hidden channel both are blind to.
 
-### Examples
+## Examples
 
 ```js
 import { stripInvisibleWithReport } from "agent-sanitizer/invisible";
@@ -269,25 +197,21 @@ await rehydrateRedacted("Edit", toolInput, {
 }); // { updatedInput, context } | { deny } | null — a deny never exposes a secret
 ```
 
-The credential-noun vocabulary — the words that make an identifier name a secret —
-is published as data so a consumer with its own matcher derives it from one list
-instead of forking one. Each noun carries the `uses` it is valid for: `env-name`
-for a matcher that inspects a variable NAME only, `field-value` for one that
-redacts whatever follows `noun = ` (a broad noun there mangles ordinary text, so
-`key` and `pat` are name-only).
+The credential-noun vocabulary — the words that make an identifier name a
+secret — is published as data so a consumer with its own matcher derives it
+rather than forking it. Each noun's `uses` marks where it is valid: `env-name`
+inspects a variable NAME only, `field-value` also redacts what follows
+`noun = ` (too broad for `key` and `pat`, which stay name-only).
 
 ```js
 import { createRequire } from "node:module";
-const vocabulary = createRequire(import.meta.url)(
-  "agent-sanitizer/credential-names",
-);
-vocabulary.nouns; // [{ parts: ["api", "key"], uses: ["env-name", "field-value"] }, …]
+createRequire(import.meta.url)("agent-sanitizer/credential-names").nouns;
+// [{ parts: ["api", "key"], uses: ["env-name", "field-value"] }, …]
 ```
 
 ```python
 from agent_sanitizer.secrets import credential_name_segments
-
-credential_name_segments()  # ("API_KEY", "APIKEY", "ACCESS_KEY", …) — rendered for a NAME matcher
+credential_name_segments()  # ("API_KEY", "APIKEY", "ACCESS_KEY", …)
 ```
 
 ## Limits
@@ -306,17 +230,14 @@ layer does and does not defend against.
 
 ## Non-JS pipelines (Python, etc.)
 
-The JS is the **single source of truth**—non-JS callers drive the same verdicts
-through the bundled CLI, so there’s
-no second implementation to drift. An `op` field selects the entry point
-(default `sanitize`); the self-contained ones—`sanitizeText`, `classifyPrompt`,
-`scanInstructionFiles`, `cleanFile`—are all bridged. Entry points with an
-injected JS callback have no wire form and stay JS-only. The bridged
-`sanitizeText` runs Layers 1–3 only (invisible/ANSI strip, HTML hidden-content
-splice, exfil detection): it never redacts secrets (Layer 4) or runs injection
-filtering (Layer 5), and the wire protocol's `sgrNote` (Python's
-`TextResult.sgr_note`) is always `false`, since the bridge never wires
-`sgrCarveOut`.
+The JS is the **single source of truth** — non-JS callers drive the same
+verdicts through the bundled CLI, so no second implementation can drift. An `op`
+field selects the entry point (default `sanitize`); the self-contained ones —
+`sanitizeText`, `classifyPrompt`, `scanInstructionFiles`, `cleanFile` — are
+bridged, while entry points taking a JS callback have no wire form. Bridged
+`sanitizeText` runs Layers 1–3 only: no secret redaction (Layer 4), no injection
+filtering (Layer 5), and `sgrNote` is always `false` since the bridge never
+wires `sgrCarveOut`.
 
 ```sh
 echo '{"text":"a​b"}' | npx sanitize-cli           # default op: sanitize
@@ -324,16 +245,13 @@ echo '{"op":"classifyPrompt","text":"…"}' | npx sanitize-cli
 sanitize-cli --worker                              # newline-delimited, one response/line
 ```
 
-The [`python/`](./python) client wraps every bridged op (`sanitize`,
-`sanitize_text`, `classify_prompt`, `scan_instruction_files`, `clean_file`). The
-wheel ships a self-contained, single-file build of the CLI (`src/` and its npm
-dependencies bundled into one `.mjs` at release time), so a `pip install` plus
-Node.js (>=22) on `PATH` works with no separate JavaScript checkout to clone.
-`AGENT_SANITIZER_CLI` is only an override escape hatch (e.g. to point at a
-custom/dev build)—a normal install never needs to set it. The first
-`html=True` call starts a shared worker, so the ~200 ms HTML module-load is
-paid **once per process**; Layer-1 calls stay one-shot. `persist=True/False`
-forces the mode and `shutdown_worker()` (also an `atexit` hook) stops it.
+The [`python/`](./python) client wraps every bridged op. The wheel ships a
+single-file build of the CLI, so `pip install` plus Node.js (>=22) on `PATH`
+needs no JavaScript checkout; `AGENT_SANITIZER_CLI` is an override escape hatch
+a normal install never sets. The first `html=True` call starts a shared worker,
+paying the ~200 ms HTML module-load **once per process**; Layer-1 calls stay
+one-shot. `persist=True/False` forces the mode; `shutdown_worker()` (also an
+`atexit` hook) stops it.
 
 ```python
 from agent_sanitizer import sanitize, Sanitizer

package/package.json

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