pando-ai 0.2.1 → 0.2.3

package/README.md

@@ -1,42 +1,168 @@
-# pandō CLI
+# pandō — AI coding firewall
 
-`pando-ai` is the standalone CLI for `pandō`, a code indexing and semantic code editing engine exposed over MCP.
+`pando-ai` is an **AI coding firewall** for Codex and Claude Code. It installs
+supervised launchers so developers keep running `codex ...` and `claude ...`
+normally while Pando applies local policy on each launch.
 
-`pandō` scans a repository, builds a structured index of code and symbols, and serves tools that let agents search code, follow references, inspect callers, and make targeted edits using syntax-aware operations instead of raw text matching.
+Its jobs:
 
-For example, an MCP client can use `pandō` to find a function definition, list every caller across a large codebase, and then add a parameter with `change-signature`, updating the function and its call sites together.
+1. **Constrain tool use** — install the project-scoped Pando MCP server, deny
+   native tools where supported, and deny non-Pando MCP tools by default.
+2. **Inspect tool traffic** — use Claude Code hooks on every Claude launch and
+   a local provider gateway where available to block off-policy tool calls and
+   tool results.
+3. **Keep code local by default** — run indexing, search, snapshots, and edits
+   locally; optional working-set memory is off unless explicitly enabled.
 
-`pando-ai` starts the same core indexing and tool runtime used by the VS Code extension, but runs headlessly for terminal agents and local MCP clients. We have tested it on codebases as large as Metabase and Visual Studio Code.
+It is built on the same indexing + MCP engine as the Pandō VS Code extension.
 
 ## Install
 
 Requires Node.js `22.5.0` or newer.
 
-Run without installing globally:
-
 ```bash
-npx -y pando-ai --help
+npx -y pando-ai
 ```
 
-Or install globally:
+On a terminal this opens the **firewall console**: it detects whether `codex`
+and `claude` are protected, offers to install supervised launchers for any that
+aren't, and shows current status and policy. After installation you keep running
+`codex` and `claude` normally — Pando supervises each launch.
+
+## How it works
+
+Two choke points, one ruleset:
+
+- **Launch shim** (`~/.pando/bin` ahead of the real tools on PATH) — supervises
+  every `codex`/`claude` invocation. It disables the agent's native tools where
+  supported, installs the Pando MCP server (root-scoped to your project), and
+  applies the MCP allow/deny policy via the agent's own launch flags.
+- **Wire gateway** (a local reverse proxy speaking the OpenAI Responses API and
+  Anthropic Messages API) — sits inline on every supported request and forwards
+  it to the upstream you control, so traffic stays local. It blocks off-policy
+  tool definitions, tool calls, and tool results before they can cross the
+  provider boundary, and blocks off-policy tool calls on model responses before
+  the agent can execute them. When enabled, it runs the protocol-adapted
+  working-set memory engine ported from `pando-proxy`.
+- **Memory manager** (`PANDO_GATEWAY_MEMORY=1`, off by default) — maintains a
+  per-session working set and archive recall path. The memory core is separate
+  from policy enforcement: policy decides which tools are allowed; memory
+  decides which prior context remains visible. OpenAI Responses and Anthropic
+  Messages use protocol adapters around the same core. The maintenance
+  classifier currently uses an OpenAI-compatible structured model backend.
+- **Policy** (`~/.pando/policy.toml`, or a Pando DB table) — one allowlist plus a
+  default action. By default, native tools are denied and non-Pando MCP servers
+  are denied; Pando MCP is always allowed. See `[native_tools]`, `[other_mcp]`,
+  `[proxy]`, `[firewall]`.
+
+### Supported model APIs
+
+The gateway supports the current agent-facing APIs used by the supervised
+launchers:
+
+- OpenAI/OpenAI-compatible Responses API: `/v1/responses`
+- Anthropic Messages API: `/v1/messages`
+
+Legacy completion APIs, including OpenAI chat/completions and Anthropic
+`/v1/complete`, are intentionally unsupported.
+
+### Enforcement matrix (what is actually enforced)
+
+| Capability | Claude Code | Codex |
+| --- | --- | --- |
+| Disable native tools | ✅ `--tools ""` (MCP stays available) + gateway/hook block | ⚠️ read-only sandbox + web search disabled + request/response gateway block |
+| Install Pando MCP, root-scoped | ✅ `--mcp-config` | ✅ required `-c mcp_servers.pando.*` |
+| `other_mcp: deny_all` | ✅ `--strict-mcp-config` (Pando only) + gateway/hook block | ✅ request/response gateway block |
+| `other_mcp: allow_list` | ✅ strict config with Pando + named servers + gateway/hook block | ✅ request/response gateway block |
+| `other_mcp: deny_list` | ✅ `--disallowedTools` removes denied names + gateway/hook block | ✅ request/response gateway block |
+| Route traffic through local gateway | ✅ API-key/token/helper auth via `ANTHROPIC_BASE_URL`; hooks are always on | ✅ provider override |
+
+- **Codex** has no documented strict-MCP switch and no exact `--tools ""`
+  equivalent, so launch-time stripping is best-effort. Pando marks its MCP
+  server required, disables Codex web search when native tools are denied,
+  strips off-policy tool definitions from `/v1/responses` requests, blocks
+  provider-bound off-policy tool call/result transcript items before they reach
+  the model provider, and blocks off-policy tool calls in model responses before
+  Codex can execute them.
+- **Claude Code** always gets Pando hook settings for tool-call/tool-result
+  enforcement. API-key, auth-token, or Claude Code `apiKeyHelper` auth also
+  enables gateway mode through `ANTHROPIC_BASE_URL`. Subscription-only launches
+  use hooks-only fallback because Claude Code does not route subscription OAuth
+  through a custom gateway.
+- **Claude Desktop general chat**: not part of the strong-enforcement claim;
+  transparent interception is not reliable there without app-level controls.
+
+### Claude Code gateway and hook modes
+
+Claude Code tool enforcement is hook-based for every launch. Official Claude
+Code gateway configuration uses `ANTHROPIC_BASE_URL` with
+`ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`, or `apiKeyHelper`; those
+credentials take precedence over subscription OAuth. When any of those
+credentials are configured and `[proxy].claude = "enforce"`, Pando also routes
+Claude through the local gateway for full-wire interception and optional memory.
+
+Pando injects Claude hook settings on each launch:
+
+- `PreToolUse` blocks off-policy tool calls before execution.
+- `PostToolUse` replaces off-policy tool output with a Pando block message
+  before Claude can use it.
+- `PostToolUseFailure` adds retry context; the tool has already failed, so this
+  hook is not treated as a hard enforcement boundary.
+- `PostToolBatch` blocks the loop before the next model request if a serialized
+  off-policy tool result appears in the batch.
+
+Hooks are the Claude tool firewall: they prevent Claude from using
+non-Pando/off-policy tools and prevent their results from becoming usable model
+context. Gateway mode is an additional full-wire layer for request/response
+inspection, memory, and provider-bound enforcement; hooks still run when the
+gateway is active.
+
+### Provider proxy toggle
+
+Users can enable or disable the local provider proxy per supervised tool:
 
 ```bash
-npm install -g pando-ai
-pando-ai --help
+pando-ai proxy status
+pando-ai proxy enable claude
+pando-ai proxy disable claude
+pando-ai proxy enable codex
+pando-ai proxy disable codex
+```
+
+This writes the `[proxy]` section in `~/.pando/policy.toml`:
+
+```toml
+[proxy]
+codex = "enforce"  # enforce | off
+claude = "enforce" # enforce | off
 ```
 
-## Usage
+When Claude proxying is off, Pando uses hooks-only fallback for
+tool-call/tool-result enforcement. When Codex proxying is off, Pando still
+launches Codex with Pando MCP and best-effort local restrictions, but
+provider-bound gateway enforcement is disabled.
+
+## Surfaces
 
 ```bash
-pando-ai [project-path]
-pando-ai --version
-pando-ai --help
+pando-ai                 # firewall console (TTY): status + proactive install
+pando-ai install         # force a (re)install pass
+pando-ai serve [path]    # stdio MCP server for MCP clients
+pando-ai serve-http      # HTTP MCP server
+pando-ai gateway         # run the firewall gateway in the foreground (debug)
+pando-ai proxy status|enable|disable [codex|claude]
+pando-ai login|logout|whoami
+pando-ai config set telemetry false
 ```
 
-## Commands
+`pando-ai launch codex|claude -- <args>` is the supervised launcher the shims
+call; you don't run it directly.
+
+## MCP serve mode
 
-- `pando-ai [project-path]` starts the engine for the given path, or the current working directory.
-- `pando-ai config set telemetry false` disables usage telemetry.
+When invoked without a TTY (e.g. spawned by an MCP client) `pando-ai` starts the
+engine over stdio for the given path, or the current working directory, exactly
+as before. `pando-ai config set telemetry false` disables usage telemetry.
 
 ## Transport behavior
 
@@ -47,29 +173,6 @@ pando-ai --help
 
 At startup, the CLI detects common MCP clients and prints a matching configuration snippet when possible.
 
-You can also install `pando-ai` manually as an MCP server:
-
-```bash
-# Claude Code
-claude mcp add pando-ai -- npx -y pando-ai
-
-# Codex CLI
-codex mcp add pando-ai -- npx -y pando-ai
-```
-
-Cursor uses `mcp.json` instead of an `add` command. Add this to `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for a global install:
-
-```json
-{
-  "mcpServers": {
-    "pando-ai": {
-      "command": "npx",
-      "args": ["-y", "pando-ai"]
-    }
-  }
-}
-```
-
 Current detection targets:
 
 - Claude Code