@node9/proxy 2.9.3 → 2.11.0

package/docs/agents/README.md

@@ -0,0 +1,29 @@
+# node9 per agent
+
+One page per agent: what node9 wires into it, what that covers, and what it does not. The
+"what is not covered" section is the one to read before you tell your team an agent is governed.
+
+| Agent                       | Control model | Prompt scan | Guide                                  |
+| --------------------------- | ------------- | ----------- | -------------------------------------- |
+| Claude Code                 | hooks + MCP   | yes         | [claude-code.md](claude-code.md)       |
+| Codex CLI                   | hooks + MCP   | yes         | [codex.md](codex.md)                   |
+| GitHub Copilot CLI          | hooks + MCP   | yes         | [copilot-cli.md](copilot-cli.md)       |
+| Gemini CLI                  | hooks + MCP   | no          | [gemini-cli.md](gemini-cli.md)         |
+| Antigravity                 | hooks + MCP   | no          | [antigravity.md](antigravity.md)       |
+| Hermes Agent                | hooks         | no          | [hermes.md](hermes.md)                 |
+| OpenCode                    | plugin        | yes         | [opencode.md](opencode.md)             |
+| Pi                          | extension     | yes         | [pi.md](pi.md)                         |
+| Cursor                      | MCP only      | no          | [cursor.md](cursor.md)                 |
+| Windsurf                    | MCP only      | no          | [windsurf.md](windsurf.md)             |
+| VS Code (Copilot extension) | MCP only      | no          | [vscode.md](vscode.md)                 |
+| Claude Desktop              | MCP only      | no          | [claude-desktop.md](claude-desktop.md) |
+
+"Hooks" means node9 sees every tool call before it runs. "MCP only" means node9 sees the tools
+that go through MCP servers and nothing the editor does on its own.
+
+Every page ends with the same two commands, and they are the real check:
+
+```bash
+node9 doctor
+node9 explain Bash 'cat ~/.ssh/id_rsa'
+```

package/docs/agents/antigravity.md

@@ -0,0 +1,33 @@
+# node9 with Antigravity
+
+| Surface           | How node9 is wired                                     | What it does                                |
+| ----------------- | ------------------------------------------------------ | ------------------------------------------- |
+| Every tool call   | `PreToolUse` hook in `~/.gemini/config/hooks.json`     | allow / review / block before the tool runs |
+| Every tool result | `PostToolUse` hook                                     | audit record                                |
+| MCP servers       | `~/.gemini/config/mcp_config.json` entries are wrapped | per-tool allow / review / block             |
+
+Payload shape verified against Antigravity 1.0.6.
+
+## Set it up
+
+```bash
+node9 agents add antigravity
+```
+
+`node9 init` does this for every agent it detects on the machine. Either command is safe to
+re-run; it repairs a hook that an agent update removed and leaves everything else alone.
+
+## What is not covered
+
+- **No prompt scan.** There is no prompt event to hook.
+- Cost is not tracked for Antigravity.
+
+## Verify it on this machine
+
+```bash
+node9 doctor                                   # is the hook (or MCP wrap) actually in place?
+node9 explain Bash 'cat ~/.ssh/id_rsa'         # shows the verdict the live hook enforces: BLOCK
+```
+
+`node9 explain` prints the exact rule that fires and where the decision came from. If `doctor`
+says the agent is not wired, the guard is not running, whatever the config looks like.

package/docs/agents/claude-code.md

@@ -0,0 +1,40 @@
+# node9 with Claude Code
+
+Claude Code is the most fully covered agent.
+
+| Surface           | How node9 is wired                                                | What it does                                              |
+| ----------------- | ----------------------------------------------------------------- | --------------------------------------------------------- |
+| Every tool call   | `PreToolUse` hook in `~/.claude/settings.json`                    | allow / review / block before the tool runs               |
+| Every tool result | `PostToolUse` hook                                                | writes the audit record                                   |
+| Pasted prompts    | `UserPromptSubmit` hook                                           | secret pasted into the prompt is caught before it is sent |
+| MCP servers       | entries in `~/.claude.json` are wrapped through the node9 gateway | per-tool allow / review / block                           |
+| Cost              | reads `~/.claude/projects` session logs                           | per-project spend in `node9 report`                       |
+
+The `PreToolUse` hook runs in every Claude Code permission mode, including
+`--dangerously-skip-permissions`. That was verified with a standalone probe, and it is
+undocumented behaviour, so treat it as a fact about today's Claude Code rather than a guarantee.
+
+## Set it up
+
+```bash
+node9 agents add claude
+```
+
+`node9 init` does this for every agent it detects on the machine. Either command is safe to
+re-run; it repairs a hook that an agent update removed and leaves everything else alone.
+
+## What is not covered
+
+- Tool **output** is observed, not gated. Claude Code's `PostToolUse` cannot suppress a
+  result, so a secret or an injected instruction inside a tool result is recorded and the
+  session is tainted for review on the next call; it is not stripped before Claude sees it.
+
+## Verify it on this machine
+
+```bash
+node9 doctor                                   # is the hook (or MCP wrap) actually in place?
+node9 explain Bash 'cat ~/.ssh/id_rsa'         # shows the verdict the live hook enforces: BLOCK
+```
+
+`node9 explain` prints the exact rule that fires and where the decision came from. If `doctor`
+says the agent is not wired, the guard is not running, whatever the config looks like.

package/docs/agents/claude-desktop.md

@@ -0,0 +1,32 @@
+# node9 with Claude Desktop
+
+Claude Desktop only calls tools through MCP, so wrapping its servers covers every tool it
+can use.
+
+| Surface     | How node9 is wired                                                            | What it does                    |
+| ----------- | ----------------------------------------------------------------------------- | ------------------------------- |
+| MCP servers | entries in `claude_desktop_config.json` are wrapped through the node9 gateway | per-tool allow / review / block |
+
+## Set it up
+
+```bash
+node9 agents add claudeDesktop
+```
+
+`node9 init` does this for every agent it detects on the machine. Either command is safe to
+re-run; it repairs a hook that an agent update removed and leaves everything else alone.
+
+## What is not covered
+
+- No prompt scan and no cost tracking.
+- `node9 doctor` and `node9 status` do not list Claude Desktop yet.
+
+## Verify it on this machine
+
+```bash
+node9 doctor                                   # is the hook (or MCP wrap) actually in place?
+node9 explain Bash 'cat ~/.ssh/id_rsa'         # shows the verdict the live hook enforces: BLOCK
+```
+
+`node9 explain` prints the exact rule that fires and where the decision came from. If `doctor`
+says the agent is not wired, the guard is not running, whatever the config looks like.

package/docs/agents/codex.md

@@ -0,0 +1,37 @@
+# node9 with Codex CLI
+
+Codex gets the same pre-tool gate as Claude Code.
+
+| Surface           | How node9 is wired                                  | What it does                                       |
+| ----------------- | --------------------------------------------------- | -------------------------------------------------- |
+| Every tool call   | `PreToolUse` hook in `~/.codex/hooks.json`          | allow / review / block before the tool runs        |
+| Pasted prompts    | `UserPromptSubmit` hook                             | prompt secret scan                                 |
+| Every tool result | `PostToolUse` hook                                  | audit record; verified against real Codex sessions |
+| MCP servers       | `mcp_servers` in `~/.codex/config.toml` are wrapped | per-tool allow / review / block                    |
+
+Headless `codex exec` runs the same hooks. Verified with a nonce probe against the real
+trusted-hooks config: both the pre and post hook fired.
+
+## Set it up
+
+```bash
+node9 agents add codex
+```
+
+`node9 init` does this for every agent it detects on the machine. Either command is safe to
+re-run; it repairs a hook that an agent update removed and leaves everything else alone.
+
+## What is not covered
+
+- Cost is not tracked for Codex. `node9 report` cost figures are Claude Code only today.
+- Tool output is observed, not gated (same as Claude Code).
+
+## Verify it on this machine
+
+```bash
+node9 doctor                                   # is the hook (or MCP wrap) actually in place?
+node9 explain Bash 'cat ~/.ssh/id_rsa'         # shows the verdict the live hook enforces: BLOCK
+```
+
+`node9 explain` prints the exact rule that fires and where the decision came from. If `doctor`
+says the agent is not wired, the guard is not running, whatever the config looks like.

package/docs/agents/copilot-cli.md

@@ -0,0 +1,34 @@
+# node9 with GitHub Copilot CLI
+
+Copilot CLI is wired on three events, which makes it one of the strongest integrations.
+
+| Surface           | How node9 is wired                               | What it does                                |
+| ----------------- | ------------------------------------------------ | ------------------------------------------- |
+| Every tool call   | `PreToolUse` in `~/.copilot/hooks/node9.json`    | allow / review / block before the tool runs |
+| Every tool result | `PostToolUse`                                    | audit record                                |
+| Pasted prompts    | `UserPromptSubmit`                               | prompt secret scan                          |
+| MCP servers       | `~/.copilot/mcp-config.json` entries are wrapped | per-tool allow / review / block             |
+
+## Set it up
+
+```bash
+node9 agents add copilot
+```
+
+`node9 init` does this for every agent it detects on the machine. Either command is safe to
+re-run; it repairs a hook that an agent update removed and leaves everything else alone.
+
+## What is not covered
+
+- Cost is not tracked for Copilot.
+- Tool output is observed, not gated.
+
+## Verify it on this machine
+
+```bash
+node9 doctor                                   # is the hook (or MCP wrap) actually in place?
+node9 explain Bash 'cat ~/.ssh/id_rsa'         # shows the verdict the live hook enforces: BLOCK
+```
+
+`node9 explain` prints the exact rule that fires and where the decision came from. If `doctor`
+says the agent is not wired, the guard is not running, whatever the config looks like.

package/docs/agents/cursor.md

@@ -0,0 +1,36 @@
+# node9 with Cursor
+
+Cursor has no pre-execution hook, so node9 protects it through MCP only.
+
+| Surface     | How node9 is wired                                                 | What it does                                                                           |
+| ----------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| MCP servers | `~/.cursor/mcp.json` entries are wrapped through the node9 gateway | every `tools/call` is authorized, pinned and env-scrubbed before it reaches the server |
+
+For tools that go through MCP this is the same allow / review / block gate every other agent
+gets.
+
+## Set it up
+
+```bash
+node9 agents add cursor
+```
+
+`node9 init` does this for every agent it detects on the machine. Either command is safe to
+re-run; it repairs a hook that an agent update removed and leaves everything else alone.
+
+## What is not covered
+
+- **Cursor's own terminal and file edits are not gated.** Nothing in Cursor exposes them to a
+  hook today. If Cursor runs `cat ~/.ssh/id_rsa` in its built-in terminal, node9 does not see it.
+- No prompt scan, no audit of native tool calls, no cost tracking.
+- Say this plainly to your team: with Cursor, node9 governs the MCP surface, not the editor.
+
+## Verify it on this machine
+
+```bash
+node9 doctor                                   # is the hook (or MCP wrap) actually in place?
+node9 explain Bash 'cat ~/.ssh/id_rsa'         # shows the verdict the live hook enforces: BLOCK
+```
+
+`node9 explain` prints the exact rule that fires and where the decision came from. If `doctor`
+says the agent is not wired, the guard is not running, whatever the config looks like.

package/docs/agents/gemini-cli.md

@@ -0,0 +1,34 @@
+# node9 with Gemini CLI
+
+| Surface           | How node9 is wired                                    | What it does                                |
+| ----------------- | ----------------------------------------------------- | ------------------------------------------- |
+| Every tool call   | `BeforeTool` hook in `~/.gemini/settings.json`        | allow / review / block before the tool runs |
+| Every tool result | `AfterTool` hook                                      | audit record                                |
+| MCP servers       | `mcpServers` in `~/.gemini/settings.json` are wrapped | per-tool allow / review / block             |
+
+## Set it up
+
+```bash
+node9 agents add gemini
+```
+
+`node9 init` does this for every agent it detects on the machine. Either command is safe to
+re-run; it repairs a hook that an agent update removed and leaves everything else alone.
+
+## What is not covered
+
+- **No prompt scan.** Gemini CLI has no prompt-submit hook, so a secret pasted into the prompt
+  is not caught until it shows up in a tool call.
+- The session id Gemini sends drifts across resumes, so a review taint set before a resume can
+  be orphaned. Within one session it works.
+- Cost is not tracked for Gemini.
+
+## Verify it on this machine
+
+```bash
+node9 doctor                                   # is the hook (or MCP wrap) actually in place?
+node9 explain Bash 'cat ~/.ssh/id_rsa'         # shows the verdict the live hook enforces: BLOCK
+```
+
+`node9 explain` prints the exact rule that fires and where the decision came from. If `doctor`
+says the agent is not wired, the guard is not running, whatever the config looks like.

package/docs/agents/hermes.md

@@ -0,0 +1,35 @@
+# node9 with Hermes Agent
+
+| Surface           | How node9 is wired                                     | What it does                                |
+| ----------------- | ------------------------------------------------------ | ------------------------------------------- |
+| Every tool call   | `pre_tool_call` command hook in the Hermes YAML config | allow / review / block before the tool runs |
+| Every tool result | `post_tool_call` command hook                          | audit record                                |
+
+Run `node9 status` to see the exact config path on your machine.
+
+## Set it up
+
+```bash
+node9 agents add hermes
+```
+
+`node9 init` does this for every agent it detects on the machine. Either command is safe to
+re-run; it repairs a hook that an agent update removed and leaves everything else alone.
+
+## What is not covered
+
+- **No prompt scan.** Hermes has no prompt event.
+- **No MCP wrapping.** Hermes' MCP servers are not routed through the node9 gateway.
+- Hermes sends an empty session id on the pre-tool hook, so the output-taint review gate
+  does not work for Hermes. Upstream issue: NousResearch/hermes-agent#48311.
+- Cost is not tracked for Hermes.
+
+## Verify it on this machine
+
+```bash
+node9 doctor                                   # is the hook (or MCP wrap) actually in place?
+node9 explain Bash 'cat ~/.ssh/id_rsa'         # shows the verdict the live hook enforces: BLOCK
+```
+
+`node9 explain` prints the exact rule that fires and where the decision came from. If `doctor`
+says the agent is not wired, the guard is not running, whatever the config looks like.

package/docs/agents/opencode.md

@@ -0,0 +1,36 @@
+# node9 with OpenCode
+
+OpenCode is protected by a node9 plugin rather than hooks or MCP.
+
+| Surface           | How node9 is wired                                                                                 | What it does                                |
+| ----------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| Every tool call   | `tool.execute.before` in the node9 plugin under the OpenCode config directory (`plugins/node9.js`) | allow / review / block before the tool runs |
+| Prompts           | `chat.message`                                                                                     | prompt secret scan                          |
+| Every tool result | `tool.execute.after`                                                                               | audit record, and output redaction in place |
+
+Because the plugin can mutate tool output, secrets in a result are redacted before the model
+sees them. That is stronger than the observe-only agents.
+
+## Set it up
+
+```bash
+node9 agents add opencode
+```
+
+`node9 init` does this for every agent it detects on the machine. Either command is safe to
+re-run; it repairs a hook that an agent update removed and leaves everything else alone.
+
+## What is not covered
+
+- MCP servers are not wrapped for OpenCode; the plugin gates tool calls directly.
+- Cost is not tracked for OpenCode.
+
+## Verify it on this machine
+
+```bash
+node9 doctor                                   # is the hook (or MCP wrap) actually in place?
+node9 explain Bash 'cat ~/.ssh/id_rsa'         # shows the verdict the live hook enforces: BLOCK
+```
+
+`node9 explain` prints the exact rule that fires and where the decision came from. If `doctor`
+says the agent is not wired, the guard is not running, whatever the config looks like.

package/docs/agents/pi.md

@@ -0,0 +1,34 @@
+# node9 with Pi
+
+Pi is protected by a node9 extension rather than hooks or MCP.
+
+| Surface                           | How node9 is wired                               | What it does                                |
+| --------------------------------- | ------------------------------------------------ | ------------------------------------------- |
+| Every tool call                   | `tool_call` in `~/.pi/agent/extensions/node9.js` | allow / review / block before the tool runs |
+| Prompts                           | `input`                                          | prompt secret scan                          |
+| The `!` / `!!` shell side channel | `user_bash`                                      | gated like any other command                |
+| Every tool result                 | `tool_result`                                    | audit record, and output redaction in place |
+
+## Set it up
+
+```bash
+node9 agents add pi
+```
+
+`node9 init` does this for every agent it detects on the machine. Either command is safe to
+re-run; it repairs a hook that an agent update removed and leaves everything else alone.
+
+## What is not covered
+
+- MCP servers are not wrapped for Pi.
+- Cost is not tracked for Pi.
+
+## Verify it on this machine
+
+```bash
+node9 doctor                                   # is the hook (or MCP wrap) actually in place?
+node9 explain Bash 'cat ~/.ssh/id_rsa'         # shows the verdict the live hook enforces: BLOCK
+```
+
+`node9 explain` prints the exact rule that fires and where the decision came from. If `doctor`
+says the agent is not wired, the guard is not running, whatever the config looks like.

package/docs/agents/vscode.md

@@ -0,0 +1,33 @@
+# node9 with VS Code (Copilot extension)
+
+The VS Code Copilot extension exposes no hook, so node9 wraps its MCP servers only. This is
+a different integration from the Copilot **CLI**, which has full hooks; see
+[copilot-cli.md](copilot-cli.md).
+
+| Surface     | How node9 is wired                                                 | What it does                    |
+| ----------- | ------------------------------------------------------------------ | ------------------------------- |
+| MCP servers | VS Code's MCP config entries are wrapped through the node9 gateway | per-tool allow / review / block |
+
+## Set it up
+
+```bash
+node9 agents add vscode
+```
+
+`node9 init` does this for every agent it detects on the machine. Either command is safe to
+re-run; it repairs a hook that an agent update removed and leaves everything else alone.
+
+## What is not covered
+
+- The editor's own terminal and edits are not gated.
+- `node9 doctor` and `node9 status` do not list VS Code yet.
+
+## Verify it on this machine
+
+```bash
+node9 doctor                                   # is the hook (or MCP wrap) actually in place?
+node9 explain Bash 'cat ~/.ssh/id_rsa'         # shows the verdict the live hook enforces: BLOCK
+```
+
+`node9 explain` prints the exact rule that fires and where the decision came from. If `doctor`
+says the agent is not wired, the guard is not running, whatever the config looks like.

package/docs/agents/windsurf.md

@@ -0,0 +1,31 @@
+# node9 with Windsurf
+
+Windsurf exposes no pre-execution hook, so node9 wraps its MCP servers and nothing else.
+
+| Surface     | How node9 is wired                                                  | What it does                    |
+| ----------- | ------------------------------------------------------------------- | ------------------------------- |
+| MCP servers | Windsurf's MCP config entries are wrapped through the node9 gateway | per-tool allow / review / block |
+
+## Set it up
+
+```bash
+node9 agents add windsurf
+```
+
+`node9 init` does this for every agent it detects on the machine. Either command is safe to
+re-run; it repairs a hook that an agent update removed and leaves everything else alone.
+
+## What is not covered
+
+- Windsurf's own terminal and edits are not gated, and there is no audit of them.
+- `node9 doctor` and `node9 status` do not list Windsurf yet; check the MCP config by hand.
+
+## Verify it on this machine
+
+```bash
+node9 doctor                                   # is the hook (or MCP wrap) actually in place?
+node9 explain Bash 'cat ~/.ssh/id_rsa'         # shows the verdict the live hook enforces: BLOCK
+```
+
+`node9 explain` prints the exact rule that fires and where the decision came from. If `doctor`
+says the agent is not wired, the guard is not running, whatever the config looks like.

package/docs/badges.md

@@ -0,0 +1,98 @@
+# node9 badges
+
+Drop-in Markdown for showing that a project's agent-security surface is checked by node9.
+
+Two badges ship. One is for projects that use node9; the other is reserved for this repository.
+
+## `scanned by node9`
+
+Use this on any public project where the node9 Action runs in CI. It says that the repo's
+committed agent configuration — CI workflows, agent settings, MCP servers, instruction files — is
+inspected on every pull request, and it links readers back to node9 so they can judge what the
+badge is worth.
+
+![scanned by node9](https://img.shields.io/badge/scanned%20by-node9-a855f7?style=flat&labelColor=%231A1A2E&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNCAxNCI+PHBhdGggZmlsbD0iI0Y1RTlGRiIgZmlsbC1ydWxlPSJldmVub2RkIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiIGQ9Ik03IDAuNCAxLjYgMi41djQuMmMwIDMuMSAyLjMgNS42IDUuNCA2LjkgMy4xLTEuMyA1LjQtMy44IDUuNC02LjlWMi41TDcgMC40Wm0wIDEuNSAzLjkgMS41djMuM2MwIDIuMy0xLjYgNC4yLTMuOSA1LjMtMi4zLTEuMS0zLjktMy0zLjktNS4zVjMuNEw3IDEuOVptMCAyLjJhMS45IDEuOSAwIDAgMC0xIDMuNXYxLjZoMlY3LjZhMS45IDEuOSAwIDAgMC0xLTMuNVoiLz48L3N2Zz4K)
+
+### Requirements
+
+Only display this badge if the node9 Action genuinely runs on every pull request. The honest CI
+wiring is the signal; the badge is only a surface for it. A badge on a repo that does not run the
+check is misleading, and it devalues the badge for everyone who does.
+
+The minimum is a job that runs `node9-ai/node9-proxy@v2` on `pull_request`:
+
+```yaml
+# .github/workflows/agent-security.yml
+name: node9 agent-security
+on: pull_request
+permissions:
+  contents: read
+  pull-requests: write
+  checks: write
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: node9-ai/node9-proxy@v2
+        with:
+          fail-on: high # 'never' to comment without gating
+```
+
+`fail-on: never` still counts as running the check: the badge claims the surface is _inspected_,
+not that merges are blocked.
+
+### Markdown
+
+```markdown
+[![scanned by node9](https://img.shields.io/badge/scanned%20by-node9-a855f7?style=flat&labelColor=%231A1A2E&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNCAxNCI+PHBhdGggZmlsbD0iI0Y1RTlGRiIgZmlsbC1ydWxlPSJldmVub2RkIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiIGQ9Ik03IDAuNCAxLjYgMi41djQuMmMwIDMuMSAyLjMgNS42IDUuNCA2LjkgMy4xLTEuMyA1LjQtMy44IDUuNC02LjlWMi41TDcgMC40Wm0wIDEuNSAzLjkgMS41djMuM2MwIDIuMy0xLjYgNC4yLTMuOSA1LjMtMi4zLTEuMS0zLjktMy0zLjktNS4zVjMuNEw3IDEuOVptMCAyLjJhMS45IDEuOSAwIDAgMC0xIDMuNXYxLjZoMlY3LjZhMS45IDEuOSAwIDAgMC0xLTMuNVoiLz48L3N2Zz4K)](https://github.com/node9-ai/node9-proxy)
+```
+
+### HTML
+
+```html
+<a href="https://github.com/node9-ai/node9-proxy">
+  <img
+    alt="scanned by node9"
+    src="https://img.shields.io/badge/scanned%20by-node9-a855f7?style=flat&labelColor=%231A1A2E&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNCAxNCI+PHBhdGggZmlsbD0iI0Y1RTlGRiIgZmlsbC1ydWxlPSJldmVub2RkIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiIGQ9Ik03IDAuNCAxLjYgMi41djQuMmMwIDMuMSAyLjMgNS42IDUuNCA2LjkgMy4xLTEuMyA1LjQtMy44IDUuNC02LjlWMi41TDcgMC40Wm0wIDEuNSAzLjkgMS41djMuM2MwIDIuMy0xLjYgNC4yLTMuOSA1LjMtMi4zLTEuMS0zLjktMy0zLjktNS4zVjMuNEw3IDEuOVptMCAyLjJhMS45IDEuOSAwIDAgMC0xIDMuNXYxLjZoMlY3LjZhMS45IDEuOSAwIDAgMC0xLTMuNVoiLz48L3N2Zz4K"
+  />
+</a>
+```
+
+### Placement
+
+Put it with the other status badges at the top of the README. It follows the standard shields.io
+layout, so it sits cleanly next to CI, coverage, and license badges.
+
+### Link target
+
+Link the badge to `https://github.com/node9-ai/node9-proxy` so a reader can click through and find out what it asserts. Linking to
+your own passing CI run instead is also fine.
+
+## `node9 self-scanned`
+
+**Reserved for this repository.** It says that node9 runs its own Action against its own source on
+every pull request, and gates merges on the result — dogfooding in public. It links to the workflow
+that does it, so the claim is checkable in one click.
+
+![node9 self-scanned](https://img.shields.io/badge/node9-self--scanned-a855f7?style=flat&labelColor=%231A1A2E&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNCAxNCI+PHBhdGggZmlsbD0iI0Y1RTlGRiIgZmlsbC1ydWxlPSJldmVub2RkIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiIGQ9Ik03IDAuNCAxLjYgMi41djQuMmMwIDMuMSAyLjMgNS42IDUuNCA2LjkgMy4xLTEuMyA1LjQtMy44IDUuNC02LjlWMi41TDcgMC40Wm0wIDEuNSAzLjkgMS41djMuM2MwIDIuMy0xLjYgNC4yLTMuOSA1LjMtMi4zLTEuMS0zLjktMy0zLjktNS4zVjMuNEw3IDEuOVptMCAyLjJhMS45IDEuOSAwIDAgMC0xIDMuNXYxLjZoMlY3LjZhMS45IDEuOSAwIDAgMC0xLTMuNVoiLz48L3N2Zz4K)
+
+```markdown
+[![node9 self-scanned](https://img.shields.io/badge/node9-self--scanned-a855f7?style=flat&labelColor=%231A1A2E&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNCAxNCI+PHBhdGggZmlsbD0iI0Y1RTlGRiIgZmlsbC1ydWxlPSJldmVub2RkIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiIGQ9Ik03IDAuNCAxLjYgMi41djQuMmMwIDMuMSAyLjMgNS42IDUuNCA2LjkgMy4xLTEuMyA1LjQtMy44IDUuNC02LjlWMi41TDcgMC40Wm0wIDEuNSAzLjkgMS41djMuM2MwIDIuMy0xLjYgNC4yLTMuOSA1LjMtMi4zLTEuMS0zLjktMy0zLjktNS4zVjMuNEw3IDEuOVptMCAyLjJhMS45IDEuOSAwIDAgMC0xIDMuNXYxLjZoMlY3LjZhMS45IDEuOSAwIDAgMC0xLTMuNVoiLz48L3N2Zz4K)](https://github.com/node9-ai/node9-proxy/blob/main/.github/workflows/agent-security.yml)
+```
+
+On any other project, use `scanned by node9` above. This wording is only honest here.
+
+## Brand
+
+- Label background: `#1A1A2E`
+- Message background: `#a855f7` (the node9 accent)
+- Logo: `#F5E9FF`, a shield glyph inlined as an SVG data URI
+
+shields.io renders an inlined SVG verbatim rather than tinting it, so the fill is baked into the
+glyph. Do not change the colours or substitute a different logo. The consistency is the point: a
+badge is only recognisable if it looks the same everywhere.
+
+## Problems
+
+If the badge renders oddly in your README, open an issue on
+[node9-ai/node9-proxy](https://github.com/node9-ai/node9-proxy/issues) with the rendered image and your README source.

package/docs/comparison.md

@@ -0,0 +1,66 @@
+# Where node9 sits among agent-security tools
+
+Most comparisons in this space grade tools on runtime mediation: where the allow / deny decision
+is computed, where it is enforced, and what evidence the tool emits. That is a fair axis and
+node9 is not the strongest tool on it. This page grades on a second axis that the same
+comparisons leave out: **what a tool can see before an agent ever runs**.
+
+Every claim below about node9 is code-verified against this repository. Claims about other
+tools come from their own public documentation as of September 2026; if one is wrong, open an
+issue and it will be corrected.
+
+## Two questions, two fields
+
+| Question                                                                 | Who answers it                                                                                                                           |
+| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| At runtime, can a mediator stop this action and prove it did?            | pipelock, CAPSEM, Signet, AgentMint, Cupcake, agentsh, Docker MCP gateway, Microsoft AGT, Invariant, **node9**                           |
+| Before any run, is this repository's committed agent surface hijackable? | **node9 `scan-repo`**, and in narrow slices Snyk `mcp-scan` (MCP tool definitions) and Trail of Bits `mcp-context-protector` (MCP drift) |
+
+The first field is crowded and well served. The second is nearly empty.
+
+## The committed agent surface
+
+An agent wired into a repository leaves configuration behind: hook files, workflow YAML, MCP
+server pins, instruction files. That configuration decides what an outsider can make the agent
+do, and it is reviewable without running anything.
+
+| Check | What it reads                                                                                        | What it flags                                                                                                                           | Nearest alternative                     |
+| ----- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| CI-1  | `.claude/settings.json` and hooks                                                                    | committed config that pre-authorizes broad tools or runs remote hooks                                                                   | none                                    |
+| CI-2  | `.github/workflows/*.yml`                                                                            | an agent that an outsider can trigger with the repository's secrets in reach (`pull_request_target`, untrusted checkout, no actor gate) | none                                    |
+| CI-3  | `.mcp.json`, `.cursor/mcp.json`                                                                      | unpinned or `@latest` MCP servers, inline credentials                                                                                   | Snyk `mcp-scan` (definitions, not pins) |
+| CI-4  | workflow YAML                                                                                        | secrets an injected agent could exfiltrate, given the shell it has                                                                      | none                                    |
+| CI-6  | `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `copilot-instructions.md`, `.windsurfrules`, `.clinerules` | poisoned or dangerous instructions, including concealed text                                                                            | none                                    |
+
+Not built: CI-5, drift of these files over time. `mcp-context-protector` does drift for MCP tool
+descriptions; nobody does it for the rest of the surface, including node9.
+
+Runs as `npx node9-ai scan-repo <owner/repo>` on any public repository with no install and no
+token, or as a GitHub Action that fails the PR. This repository runs it on itself on every pull
+request.
+
+## Runtime: what node9 is and is not
+
+node9 gates tool calls in the agent's own hook system (Claude Code, Codex, Copilot CLI, Gemini
+CLI, Antigravity, Hermes, OpenCode, Pi) or at the MCP boundary (Cursor, Windsurf, VS Code,
+Claude Desktop). Shell commands are parsed as an AST, so `$(cat ~/.aws/credentials | base64)`
+is a credential read, not a string that happens to contain the word `cat`.
+
+Where the runtime tools are ahead of node9, in their own words and ours:
+
+| Capability                                       | Strongest tool on it                      | node9 today                                                                                                                                 |
+| ------------------------------------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| Offline-verifiable, signed evidence per decision | pipelock (Ed25519, hash-chained receipts) | audit log with privacy hashing; release artifacts are signed, decisions are not                                                             |
+| Content scanning of HTTP and WebSocket egress    | pipelock                                  | egress is a destination gate, off by default; no wire-level content scan                                                                    |
+| Kernel or container boundary                     | agentsh, pipelock containment, CAPSEM     | `node9 sandbox` is a first-phase container run                                                                                              |
+| Prompt-injection detection on tool output        | pipelock, Invariant                       | observed and quarantined on hook agents, redacted in place on OpenCode and Pi; not blocked before the model sees it on Claude Code or Codex |
+
+Where node9 is ahead: per-agent wiring across twelve agents with one `node9 doctor` that tells
+you which hook is actually in place, and the repository scan above.
+
+## How to read this page
+
+If your risk is an agent that is already running, pick from the first field and compare
+evidence models. If your risk is a repository that wires an agent into CI, there is one tool
+that reads that surface, and this is it. Most teams have both risks, and node9 is the only one
+of the set that tries to cover both, which is also why it is not the deepest on either.