pando-ai 0.6.5 → 0.7.0

package/README.md

@@ -6,13 +6,16 @@ normally while Pando applies local policy on each launch.
 
 Its jobs:
 
-1. **Constrain tool use** — install the project-scoped Pando MCP server, deny
+1. **Constrain tool use** — install project-scoped Pando MCP servers, 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.
+4. **Prefer semantic operations** — give agents structured code tools for
+   search, references, renames, edits, snapshots, and shell execution instead of
+   making raw shell access the default control surface.
 
 It is built on the same indexing + MCP engine as the Pandō VS Code extension.
 
@@ -35,21 +38,22 @@ from `npx`. After installation you keep running `codex` and `claude` normally
 
 ## How it works
 
-Two choke points, one ruleset:
+Four layers, 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, dynamically injects the Pando MCP server (root-scoped to your
-  project), and applies the MCP allow/deny policy via the agent's own launch
-  flags. Pando does not permanently add itself to the user's MCP config files by
-  default; supervised launches pass generated config on each run.
+  supported, dynamically injects root-scoped Pando MCP servers, and applies the
+  MCP allow/deny policy via the agent's own launch flags. Pando does not
+  permanently add itself to the user's MCP config files by default; supervised
+  launches pass generated config on each run.
 - **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`.
+  it to the upstream you control. Policy enforcement happens locally before a
+  request is forwarded and before a model response reaches the agent. 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
@@ -61,6 +65,77 @@ Two choke points, one ruleset:
   are denied; Pando MCP is always allowed. See `[native_tools]`, `[other_mcp]`,
   `[proxy]`, `[firewall]`.
 
+## Security model
+
+Pando's security model has three separate jobs:
+
+- **Containment**: the `pando_workspace` MCP process runs model-triggered
+  workspace mutation in an OS sandbox. The sandbox limits the process to the
+  project root, sandbox-local home/cache/temp directories, and no network by
+  default. This is the hard boundary for broad operations such as shell
+  commands and generated code.
+- **Audit and recovery**: mutating Pando tools and `shell-command` create Pando
+  snapshots around workspace changes. These are local, commit-like history
+  records for inspection and restore; they are not commits to the user's Git
+  repository.
+- **Semantic control**: Pando tools give the agent structured operations such as
+  `find-nodes`, `find-references`, `rename`, `replace`, `insert`,
+  `filter-map-reduce`, `snapshot-worktree`, and `restore-files`. These tools
+  keep requests bounded, make intent inspectable, require stable paths/hashes
+  where relevant, and reduce the need for raw shell/file access.
+
+The sandbox and snapshots are the fallback safety boundary. The Pando tools are
+the preferred control plane: they make ordinary coding work narrower, more
+auditable, and more semantically meaningful than arbitrary command execution.
+Shell remains available for tests, builds, package managers, generated files,
+unsupported languages, and tasks where a structured Pando operation is not the
+right tool.
+
+### Workspace sandbox and privileged helper
+
+Supervised launches split Pando into two MCP roles:
+
+- `pando_core` runs trusted read/search/planning/index operations.
+- `pando_workspace` runs model-triggered workspace mutation and shell commands.
+
+The workspace role re-execs into the OS sandbox before serving mutating tools.
+On macOS this uses Seatbelt; on Linux it uses bubblewrap. The sandbox is
+configured to allow the project root, sandbox-local home/cache/temp directories,
+and the minimal runtime/toolchain paths needed to start common commands. Network
+is denied by default. There is no silent unsandboxed fallback for workspace
+mutation.
+
+Install-time security setup also provisions dedicated local users
+(`pando-workspace` and `pando-core`) and a root-owned helper daemon. The helper
+is intentionally narrow: it can only launch Pando's known roles for validated
+project roots over stdio. It is not a general command runner and does not accept
+custom argv, shells, or arbitrary commands.
+
+The helper entrypoint is:
+
+```bash
+pando-ai security launch --role <core|workspace> --project-root <path> --stdio
+```
+
+The unprivileged CLI validates the request, connects to the local helper socket,
+and sends only the fixed launch request. The root-owned daemon validates again,
+selects the role's dedicated user when privilege is available, starts the fixed
+Pando MCP server invocation, and lets the normal workspace sandbox apply before
+mutating tools are served.
+
+Security setup is normally invoked by install/uninstall, but can be run
+directly:
+
+```bash
+pando-ai security setup-users
+```
+
+Diagnostics use the same JSONL log as the gateway and installer:
+`~/.pando-data/gateway-debug.jsonl` by default, or `PANDO_GATEWAY_LOG_FILE` when
+set. Logging is on by default and can be forced with `PANDO_DEBUG=1`; set
+`PANDO_DEBUG=0` to disable default helper logging. Useful event prefixes include
+`security_helper_client_*` and `security_helper_daemon_*`.
+
 ### Supported model APIs
 
 The gateway supports the current agent-facing APIs used by the supervised
@@ -77,20 +152,21 @@ Legacy completion APIs, including OpenAI chat/completions and Anthropic
 | 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 | ✅ dynamic `--mcp-config` + `--strict-mcp-config` | ✅ dynamic required `-c mcp_servers.pando.*` with Pando tools pre-approved |
-| `other_mcp: deny_all` | ✅ `--strict-mcp-config` (Pando only), Claude project built-ins disabled, gateway/hook block | ✅ request/response gateway block |
+| Install Pando MCP, root-scoped | ✅ dynamic `--mcp-config` + `--strict-mcp-config` | ✅ dynamic required `pando_core` / `pando_workspace` MCP config with Pando tools pre-approved |
+| `other_mcp: deny_all` | ✅ `--strict-mcp-config` with generated Pando-only config + 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, sets `default_tools_approval_mode="approve"` for Pando's own
-  MCP tools so non-interactive Codex launches can use them, 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.
+  servers required, sets `default_tools_approval_mode="approve"` for Pando's
+  own MCP tools so non-interactive Codex launches can use them, disables Codex
+  web search when native tools are denied, strips off-policy tool definitions
+  from `/v1/responses` requests, strips historical off-policy tool call/result
+  transcript items from resumed requests before they reach the model provider,
+  and blocks new 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
@@ -100,16 +176,18 @@ Legacy completion APIs, including OpenAI chat/completions and Anthropic
   native tools, MCP config, plugins, custom settings, IDE attachment, or bypass
   permissions (`--tools`, `--mcp-config`, `--settings`, `--plugin-dir`,
   `--permission-mode`, `--allowedTools`, dangerous permission/channel flags,
-  and related aliases). Pando also sets `ENABLE_CLAUDEAI_MCP_SERVERS=false`,
-  injects `--disable-slash-commands` when supported, and injects `--bare` /
-  `--no-chrome` on Claude builds that expose those flags. If Claude settings
-  set `disableAllHooks=true`, Pando refuses to launch Claude because hooks are
-  required for subscription-mode enforcement.
+  and related aliases). Pando also sets `ENABLE_CLAUDEAI_MCP_SERVERS=false`
+  and injects `--no-chrome` on Claude builds that expose it. Pando intentionally
+  does not pass `--bare`, because it can force API-key billing paths and skip
+  hooks on some Claude builds. Slash commands/skills are left enabled for now;
+  tool execution is constrained through `--tools ""`, strict MCP config, hooks,
+  and the gateway. If Claude settings set `disableAllHooks=true`, Pando refuses
+  to launch Claude because hooks are required for subscription-mode enforcement.
 - **Claude Code built-in/project MCP state** is stricter than normal Claude
-  config. When policy blocks non-Pando MCP servers, Pando disables matching
-  project-level Claude MCP entries such as `computer-use` in `~/.claude.json`
-  and removes stale Pando-owned top-level MCP entries. Generated Pando MCP
-  config is still passed dynamically on each supervised launch.
+  config. When policy blocks non-Pando MCP servers, Pando launches Claude with
+  strict generated MCP config containing only allowed servers. Generated Pando
+  MCP config is passed dynamically on each supervised launch, and Pando leaves
+  the user's on-disk Claude MCP config untouched by default.
 - **Claude Desktop general chat**: not part of the strong-enforcement claim;
   transparent interception is not reliable there without app-level controls.
 
@@ -207,6 +285,8 @@ pando-ai serve [path]    # stdio MCP server for MCP clients
 pando-ai serve-http      # explicit HTTP MCP server for debugging/integrations
 pando-ai gateway         # run the firewall gateway in the foreground (debug)
 pando-ai proxy status|enable|disable [codex|claude]
+pando-ai security setup-users
+pando-ai security launch --role <core|workspace> --project-root <path> --stdio
 pando-ai login|logout|whoami
 pando-ai config set telemetry false
 ```
@@ -242,6 +322,35 @@ Use stdio MCP for agents:
 pando-ai serve /path/to/project
 ```
 
+Supervised Codex and Claude launches register two Pando MCP server entries for
+the same project:
+
+- `pando_core` exposes read, search, indexing, graph, planning, and snapshot
+  inspection tools.
+- `pando_workspace` exposes workspace-mutating tools such as rename, replace,
+  insert, delete, signature changes, filter-map-reduce, shell execution,
+  restore operations, and exclude-dir changes.
+
+The split is process-level. Each server process starts with a
+`PANDO_PROCESS_ROLE` value, and tools outside that role are not registered. A
+manual `pando-ai serve /path/to/project` command without `PANDO_PROCESS_ROLE`
+starts a combined server for direct integrations; supervised Codex and Claude
+launches use the split servers.
+
+The `pando_workspace` process re-execs into a local workspace sandbox by
+default. In that sandbox:
+
+- `HOME`, temp, and package-manager cache paths point under `.pando-sandbox/`.
+- Network is denied by default.
+- The process can read and write the project root.
+- Pando workspace data created by the sandboxed process stays sandbox-local.
+
+Auth is handled separately from the sandbox home. The launcher passes the user's
+real auth home through `PANDO_AUTH_HOME_OVERRIDE`, so the sandboxed workspace
+process can read the existing `~/.pando-ai/session.json` without making the
+real home its writable `HOME` and without opening network login inside the
+sandbox.
+
 `serve-http` remains available as an explicit command for debugging or
 integrations that need HTTP:
 
@@ -293,10 +402,13 @@ The CLI does not send source code, file paths, file names, or symbol names.
 
 ## Support level
 
-- TypeScript / JavaScript / Clojure: supported in the standalone CLI distribution
-- Python / Java / C# / Dart / C / C++: not included in the standalone CLI distribution
+- TypeScript / JavaScript / Clojure / C# / C / C++: included in the standalone
+  CLI distribution.
+- Python / Java / Dart: adapters exist in the source tree, but their helper
+  assets are not included in the published npm package yet.
 
 ## Notes
 
 - Some host-only extension tools are intentionally omitted from the CLI in V1.
-- If non-TS helpers are missing, the CLI should degrade with clear tool-level errors instead of failing startup.
+- If a language helper is missing, the CLI should degrade with clear tool-level
+  errors instead of failing startup.