pi-ca-leash 0.10.0 → 0.12.0

package/README.md

@@ -1,12 +1,17 @@
 # pi-ca-leash
 
+> [!WARNING]
+> **Claude Code auth caveat:** the default `claude-sdk` runtime path actively sends prompts and follow-up messages through `@anthropic-ai/claude-agent-sdk`, including resumed peer sessions. The optional `claude-cli` runtime path avoids that SDK package and shells out to `claude -p`, but it is still non-interactive Claude Code message sending. Anthropic's current Claude Code legal/authentication docs say OAuth subscription credentials are intended for ordinary Claude Code and native Anthropic app use, while developers building products or services with the Agent SDK should use API key authentication through Claude Console or a supported cloud provider. Do not use this extension to route Free, Pro, or Max subscription credentials on behalf of other users.
+>
+> Read-only/local features such as dashboard state, peer history browsing, local persistence, Git operations, and the experimental `codex-cli` runtime path are separate from Claude Agent SDK message sending.
+
 Harness-aware Claude Code and Codex CLI extension for pi.
 
 Claude Code and Codex CLI are more than model endpoints. They are coding harnesses with their own tool loops, session semantics, and increasingly harness-optimized models. `pi-ca-leash` treats them that way.
 
 Pi stays in the brain seat — like a human coordinating multiple coding agents. It can start long-lived workers, hand them scoped tasks, wait for results, inspect what they did, and decide what happens next.
 
-Claude is the default and most complete path today. Codex works too, but is still experimental and not parity-complete.
+Claude is the default and most complete path today. `claude-cli` is available as an optional local CLI-backed Claude path. Codex works too, but is still experimental and not parity-complete.
 
 ## What it adds
 
@@ -14,6 +19,7 @@ After installation, pi gets:
 - named long-lived peers with `/peer start`, `/peer ask`, `/peer send`, `/peer history`, and `/peer stop`
 - a peer dashboard plus local attention state
 - LLM-callable peer tools such as `peer_start`, `peer_ask`, `peer_send`, `peer_history`, and `runtime_models`
+- a supported programmatic managed-peer API for downstream orchestrators via `@pi-claude-code-agent/intercom-bridge`
 - optional local subagent-style runs and local persistent teammates behind advanced commands/tools
 - optional live intercom transport when the broker is reachable
 
@@ -58,17 +64,7 @@ Once peer mode is active, you can often ask for this in natural language instead
 
 ## Install
 
-For most users, if pi already works on your machine and `pi install` works, you do not need to think about Node directly. `pi install npm:pi-ca-leash` is usually enough.
-
-Requirements for normal use:
-- a working pi installation
-- at least one configured runtime:
-  - Claude Code configured for Claude-backed execution, or
-  - `codex` on `PATH` for experimental Codex-backed runtime checks
-
-Requirements for local development or source installs:
-- Node.js 18 or newer
-- npm
+Read the Claude Code auth caveat at the top of this README before using a Claude-backed runtime path.
 
 Install from npm:
 
@@ -79,14 +75,20 @@ pi install npm:pi-ca-leash
 Pin an explicit version when needed:
 
 ```bash
-pi install npm:pi-ca-leash@0.10.0
+pi install npm:pi-ca-leash@0.12.0
 ```
 
-Install from a pinned git release:
+Local checkout install:
 
-```bash
-pi install git:github.com/durandom/pi-ca-leash@v0.10.0
-```
+Requirements for normal use:
+- a working pi installation
+- at least one configured runtime:
+  - Claude Code configured for Claude-backed execution, or
+  - `codex` on `PATH` for experimental Codex-backed runtime checks
+
+Requirements for local development or source installs:
+- Node.js 18 or newer
+- npm
 
 Try this checkout locally:
 
@@ -99,14 +101,60 @@ pi install /absolute/path/to/pi-ca-leash
 
 `npm install` runs the workspace build through `prepare`, so local development and git-based installs have package `dist/` files available.
 
-Use Codex as the default runtime driver for newly started peers:
+Use another default runtime driver for newly started peers:
 
 ```bash
+PI_CLAUDE_RUNTIME_DRIVER=claude-cli pi
 PI_CLAUDE_RUNTIME_DRIVER=codex-cli pi
 ```
 
 Persisted peers keep their recorded driver.
 
+## Configuration
+
+Driver choice can be set per call, by environment, or by config file. Precedence is:
+
+1. explicit method/tool/command driver, such as `peer_start(..., driver: "claude-cli")` or `/peer start task | claude-cli`
+2. `PI_CLAUDE_RUNTIME_DRIVER`
+3. config file `defaultDriver`
+4. built-in default `claude-sdk`
+
+Config files are JSON and are merged in this order:
+
+1. global XDG config: `$XDG_CONFIG_HOME/pi-ca-leash/config.json`, or `~/.config/pi-ca-leash/config.json`
+2. repository-local config: `.pi-ca-leash/config.json`
+3. explicit override path from `PI_CA_LEASH_CONFIG`
+
+Example:
+
+```json
+{
+  "defaultDriver": "claude-cli",
+  "drivers": {
+    "claude-cli": {
+      "executable": "/opt/homebrew/bin/claude",
+      "permissionMode": "bypassPermissions"
+    },
+    "codex-cli": {
+      "executable": "/opt/homebrew/bin/codex"
+    }
+  }
+}
+```
+
+`claude-cli` runs local Claude Code in print mode (`claude -p --output-format stream-json`) and resumes follow-up peer messages with `--resume <session-id>`. `claude-sdk` remains available and is still the default unless you choose another driver.
+
+## SDK Usage
+
+This repo also ships reusable SDK packages for programmatic use:
+
+- `@pi-claude-code-agent/runtime` for driver-backed sessions, status, events, transcripts, and normalized result usage
+- `@pi-claude-code-agent/intercom-bridge` for named long-lived peers and managed-peer orchestration
+- `@pi-claude-code-agent/subagents-backend` for persisted bounded local runs
+- `@pi-claude-code-agent/teams-backend` for persistent local teammate records
+
+Token usage is exposed as per-result-event data, not as an automatic session total. SDK consumers should sum selected `RuntimeEvent.type === "result"` events themselves when they need cumulative accounting. See `docs/token-usage-reporting.md` for the adapter/backend matrix and example SDK summing pattern.
+
 ## Try this first
 
 Inside pi:
@@ -120,9 +168,10 @@ Inside pi:
 /peer dashboard advanced
 ```
 
-If you want Codex-backed peers, inspect the bundled Codex catalog first:
+If you want driver-specific peers, inspect the bundled catalog first:
 
 ```text
+/peer models claude-cli
 /peer models codex-cli
 ```
 
@@ -147,6 +196,10 @@ Primary slash-command surface:
 /peer init
 /peer dashboard
 /peer dashboard advanced
+/peer dashboard hide
+/peer dashboard show
+/peer hide
+/peer show
 /peer start <prompt>
 /peer start <prompt> | <driver> | <model>
 /peer start <name> | <prompt>
@@ -154,7 +207,7 @@ Primary slash-command surface:
 /peer ask <name> | <message>
 /peer send <name> | <message>
 /peer list
-/peer models [claude-sdk|codex-cli] [all|advanced|verbose]
+/peer models [claude-sdk|claude-cli|codex-cli] [all|advanced|verbose]
 /peer history <name> [cursor] [limit]
 /peer interrupt <name>
 /peer stop <name>
@@ -202,7 +255,7 @@ PI_CA_LEASH_ENABLE_LEGACY_COMMANDS=1 PI_CLAUDE_ENABLE_ADVANCED_COMMANDS=1 pi
 
 ## Behavior
 
-The extension is lazy. Loading it registers commands and tools, but it does not start the Peers widget, background monitor, or intercom transport checks immediately. `/peer` with no args opens the dashboard and activates peer mode. `/peer init` also activates the peer workflow, adds the one-time orchestration guide to the main agent context, and shows the user a compact command cheat sheet as a user-only UI notification. The first actionable `/peer` command, such as `/peer models`, `/peer dashboard`, `/peer list`, or `/peer start`, also activates it and adds that agent guide once. `/peer help` and `/peer about` stay passive and show user-only UI notifications. `/peer about` reports the installed package version, package root, state root, default driver, and session mode.
+The extension is lazy. Loading it registers commands and tools, but it does not start the Peers widget, background monitor, or intercom transport checks immediately. `/peer` with no args opens the dashboard and activates peer mode. `/peer init` also activates the peer workflow, adds the one-time orchestration guide to the main agent context, and shows the user a compact command cheat sheet as a user-only UI notification. The first actionable `/peer` command, such as `/peer models`, `/peer dashboard`, `/peer list`, or `/peer start`, also activates it and adds that agent guide once. `/peer help` and `/peer about` stay passive and show user-only UI notifications. `/peer about` reports the installed package version, package root, state root, default driver, and session mode. `/peer dashboard hide` (or `/peer hide`) clears the compact Peers widget for the current session without stopping peers or disabling completion relays; `/peer dashboard show` (or `/peer show`) restores it.
 
 Peers are asynchronous workers. The main agent should start a peer, continue useful work, and wait for the automatic peer completion, blocked, or failure relay. It should not poll `peer_list`, `peer_history`, or repeated `peer_ask` just to see whether the peer is done. When a peer returns, the main agent still owns verification, synthesis, and the final answer.
 
@@ -212,10 +265,24 @@ The extension keeps peer output quiet by default:
 - peer completion is relayed back as one wrapped follow-up turn with the latest visible peer message
 - detailed backend diagnostics live in `/peer dashboard advanced`
 
+## Managed peers for downstream orchestrators
+
+If another extension wants workers that behave like normal `pi-ca-leash` peers, use the supported managed-peer surface from `@pi-claude-code-agent/intercom-bridge`:
+
+- `PiCaLeashManagedPeerApi`
+- `piCaLeashStateDir(...)`
+- `piCaLeashRuntimeStorageDir(...)`
+- `piCaLeashBridgeStorageDir(...)`
+
+That API gives downstream orchestrators the normal peer lifecycle (`launch`, `attach`, `list`, `status`, `send`, `ask`, `interrupt`, `stop`, `reconcile`) while writing to the same `.pi-ca-leash/{runtime,bridge}` state used by the extension.
+
+Result: managed peers created by another extension can show up in the live `/peer dashboard` and `peer_list` without requiring a pi restart. The normal dashboard shows a compact `managed:owner` badge, and the advanced dashboard expands full managed-peer metadata.
+
 Runtime driver notes:
 - `claude-sdk` is the default and most complete path
+- `claude-cli` shells out to local `claude -p --output-format stream-json`; it avoids importing the Agent SDK package, but still uses Claude Code non-interactively
 - `codex-cli` is supported, but still experimental and not parity-complete
-- `PI_CLAUDE_RUNTIME_DRIVER=codex-cli` changes the default for newly started peers
+- `PI_CLAUDE_RUNTIME_DRIVER=claude-cli` or `PI_CLAUDE_RUNTIME_DRIVER=codex-cli` changes the default for newly started peers
 - `/peer models` and LLM-callable `runtime_models` show a short recommended model list by default, including advisory use cases
 - `/peer models ... all` and `runtime_models(verbose: true)` expose the full bundled Lanista-derived model catalog
 - LLM-callable `peer_start`, `peer_ask`, and `peer_send` can pass explicit model ids
@@ -240,6 +307,7 @@ Useful docs that should remain current:
 - `ARCHITECTURE.md`
 - `KNOWN_LIMITS.md`
 - `CHANGELOG.md`
+- `RELEASE_NOTES.md`
 - `DEVELOPMENT.md`
 - `AGENTS.md`
 
@@ -255,7 +323,7 @@ npm run smoke:last
 npm run smoke:manual
 ```
 
-For the full developer workflow, smoke-command reference, artifact/debugging guide, and manual release checklist, see [`DEVELOPMENT.md`](./DEVELOPMENT.md).
+For the full developer workflow, smoke-command reference, artifact/debugging guide, and manual release checklist, see [`DEVELOPMENT.md`](https://github.com/durandom/pi-ca-leash/blob/main/DEVELOPMENT.md).
 
 ## Persistence
 

package/RELEASE_NOTES.md

@@ -0,0 +1,71 @@
+# Release Notes
+
+## Unreleased
+
+This release adds a second Claude-backed runtime path while keeping the existing Agent SDK path intact.
+
+### Claude CLI runtime
+
+- Added `claude-cli`, an optional runtime driver that runs local Claude Code through `claude -p --output-format stream-json`.
+- Follow-up peer messages resume the same Claude Code session with `--resume <session-id>`.
+- `claude-cli` shares the existing Anthropic model catalog and alias handling used by `claude-sdk`.
+- `claude-sdk` remains available and stays the built-in default.
+
+Use it per peer:
+
+```text
+/peer start reviewer | Review this repo briefly. | claude-cli
+```
+
+Or as the default for new peers:
+
+```bash
+PI_CLAUDE_RUNTIME_DRIVER=claude-cli pi
+```
+
+### Configuration
+
+Driver defaults and executable overrides can now come from config files as well as environment variables and method/tool parameters.
+
+Precedence:
+
+1. explicit method, tool, or command driver
+2. `PI_CLAUDE_RUNTIME_DRIVER`
+3. config file `defaultDriver`
+4. built-in default `claude-sdk`
+
+Config files are merged in this order:
+
+1. `$XDG_CONFIG_HOME/pi-ca-leash/config.json` or `~/.config/pi-ca-leash/config.json`
+2. `.pi-ca-leash/config.json` in the repository
+3. `PI_CA_LEASH_CONFIG`
+
+Example:
+
+```json
+{
+  "defaultDriver": "claude-cli",
+  "drivers": {
+    "claude-cli": {
+      "executable": "/opt/homebrew/bin/claude",
+      "permissionMode": "bypassPermissions"
+    },
+    "codex-cli": {
+      "executable": "/opt/homebrew/bin/codex"
+    }
+  }
+}
+```
+
+### Codex CLI permissions
+
+- `codex-cli` now maps `permissionMode: "bypassPermissions"` to Codex's unsandboxed automation flag for fresh and resumed peer runs.
+- Other accepted Codex permission modes keep the existing `--full-auto` behavior.
+
+### Auth Caveat
+
+The top-level README warning now distinguishes the two Claude-backed paths:
+
+- `claude-sdk` sends messages through `@anthropic-ai/claude-agent-sdk`.
+- `claude-cli` avoids importing that SDK package and shells out to `claude -p`.
+- Both are still non-interactive Claude Code message-sending paths, so users must understand their authentication mode and applicable Anthropic terms before using them.

package/extensions/command-drivers.ts

@@ -61,7 +61,7 @@ export function parsePeerStartCommandInput(args: string): ParsedPeerStartCommand
     }
     const driver = parseRuntimeDriverName(parts[2]);
     if (!driver) {
-      throw new Error("driver must be claude-sdk or codex-cli when using a driver-aware peer start form");
+      throw new Error("driver must be claude-sdk, claude-cli, or codex-cli when using a driver-aware peer start form");
     }
     return {
       name: parts[0],
@@ -72,7 +72,7 @@ export function parsePeerStartCommandInput(args: string): ParsedPeerStartCommand
   }
   const driver = parseRuntimeDriverName(parts[2]);
   if (!driver) {
-    throw new Error("driver must be claude-sdk or codex-cli when using <name> | <prompt> | <driver> | <model>");
+    throw new Error("driver must be claude-sdk, claude-cli, or codex-cli when using <name> | <prompt> | <driver> | <model>");
   }
   return {
     name: parts[0],
@@ -94,7 +94,7 @@ export function parseSubagentRunCommandInput(args: string): ParsedSubagentRunCom
   }
   const driver = parseRuntimeDriverName(parts[0]);
   if (!driver) {
-    throw new Error("driver must be claude-sdk or codex-cli when using <driver> | <task>");
+    throw new Error("driver must be claude-sdk, claude-cli, or codex-cli when using <driver> | <task>");
   }
   return {
     driver,
@@ -116,7 +116,7 @@ export function parseTeamSpawnCommandInput(args: string): ParsedTeamSpawnCommand
   }
   const driver = parseRuntimeDriverName(maybeDriver);
   if (!driver) {
-    throw new Error("driver must be claude-sdk or codex-cli when using <name> | <prompt> | <driver>");
+    throw new Error("driver must be claude-sdk, claude-cli, or codex-cli when using <name> | <prompt> | <driver>");
   }
   return {
     name: name ?? "",