pando-ai 0.2.0 → 0.2.2

package/README.md

@@ -1,38 +1,162 @@
-# pandō CLI
+# pandō — AI coding firewall
 
-`pando-ai` is the standalone MCP CLI for the shared pandō engine runtime.
+`pando-ai` is an **AI coding firewall**. It supervises your coding agents
+(`codex` and `claude`) transparently, with two jobs:
 
-It starts the same core indexing and tool runtime used by the VS Code extension, but runs headlessly for terminal agents and local MCP clients.
+1. **Block unsafe operations** — reduce the agent to a single audited tool (the
+   Pando MCP server) and intercept, rewrite, or block everything else.
+2. **Keep code local** — sit inline on the wire so model/tool traffic passes
+   through a local gateway you control.
+
+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