pi-ca-leash 0.11.1 → 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
 
@@ -59,7 +64,7 @@ Once peer mode is active, you can often ask for this in natural language instead
 
 ## Install
 
-This npm package is available again, but it comes with a large caveat: the Claude-backed runtime path actively sends messages through Anthropic's Agent SDK. Read the Agent SDK auth notice below before using it.
+Read the Claude Code auth caveat at the top of this README before using a Claude-backed runtime path.
 
 Install from npm:
 
@@ -70,7 +75,7 @@ pi install npm:pi-ca-leash
 Pin an explicit version when needed:
 
 ```bash
-pi install npm:pi-ca-leash@0.11.1
+pi install npm:pi-ca-leash@0.12.0
 ```
 
 Local checkout install:
@@ -96,20 +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.
 
-### Agent SDK Auth Notice
-
-The `claude-sdk` runtime path actively sends prompts and follow-up messages through `@anthropic-ai/claude-agent-sdk`, including resumed peer sessions. 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.
-
-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:
@@ -123,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
 ```
 
@@ -150,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>
@@ -157,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>
@@ -205,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.
 
@@ -230,8 +280,9 @@ Result: managed peers created by another extension can show up in the live `/pee
 
 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
@@ -256,6 +307,7 @@ Useful docs that should remain current:
 - `ARCHITECTURE.md`
 - `KNOWN_LIMITS.md`
 - `CHANGELOG.md`
+- `RELEASE_NOTES.md`
 - `DEVELOPMENT.md`
 - `AGENTS.md`
 

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 ?? "",

package/extensions/index.ts

@@ -78,6 +78,8 @@ const EXTENSION_VERSION = String((extensionRequire("../package.json") as { versi
 const STATE_DIR_NAME = ".pi-ca-leash";
 const BACKGROUND_POLL_INTERVAL_MS = 5_000;
 const BACKGROUND_REFRESH_MIN_INTERVAL_MS = 3_000;
+const RUNTIME_DRIVER_ENUM = ["claude-sdk", "claude-cli", "codex-cli", "pi-coding-agent"] as const;
+const RUNTIME_DRIVER_USAGE = "claude-sdk, claude-cli, or codex-cli";
 const DEFAULT_SNOOZE_MINUTES = 15;
 
 interface DashboardSnapshot {
@@ -142,15 +144,17 @@ interface ExtensionLogEntryInput {
 let dashboardContextRef: ExtensionContext | ExtensionCommandContext | undefined;
 let operatorContextRef: ExtensionContext | ExtensionCommandContext | undefined;
 let lastWidgetSignature: string | undefined;
+let peerDashboardHidden = false;
 
 export default async function piCaLeashExtension(pi: ExtensionAPI) {
   const cwd = process.cwd();
   const rootDir = resolve(cwd, STATE_DIR_NAME);
   const attentionLedgerPath = resolve(rootDir, "extension", "attention-ledger.json");
-  const runtimeDriverConfig = resolveExtensionRuntimeDriverConfig();
+  const runtimeDriverConfig = resolveExtensionRuntimeDriverConfig(process.env, cwd);
   const runtime = new ClaudeCodeRuntime({
     storageDir: resolve(rootDir, "runtime"),
     defaultDriver: runtimeDriverConfig.defaultDriver,
+    config: runtimeDriverConfig.config,
   });
   const bridge = new ClaudeRuntimeIntercomBridge({
     runtime,
@@ -188,7 +192,7 @@ export default async function piCaLeashExtension(pi: ExtensionAPI) {
   async function startPeerWithoutWaiting(input: {
     name: string;
     prompt: string;
-    driver?: "claude-sdk" | "codex-cli";
+    driver?: (typeof RUNTIME_DRIVER_ENUM)[number];
     cwd?: string;
     model?: string;
     permissionMode?: "default" | "acceptEdits" | "plan" | "dontAsk" | "bypassPermissions";
@@ -547,7 +551,7 @@ export default async function piCaLeashExtension(pi: ExtensionAPI) {
     parameters: {
       type: "object",
       properties: {
-        driver: { type: "string", enum: ["claude-sdk", "codex-cli"], description: "Optional runtime driver to filter the model catalog." },
+        driver: { type: "string", enum: [...RUNTIME_DRIVER_ENUM], description: "Optional runtime driver to filter the model catalog." },
         verbose: { type: "boolean", description: "When true, include every model from the bundled catalog instead of the short recommended list." },
       },
       additionalProperties: false,
@@ -556,7 +560,7 @@ export default async function piCaLeashExtension(pi: ExtensionAPI) {
       const input = params as { driver?: unknown; verbose?: unknown };
       const driver = input.driver == null ? undefined : parseRuntimeDriverName(input.driver);
       if (input.driver != null && !driver) {
-        throw new Error("driver must be claude-sdk or codex-cli");
+        throw new Error(`driver must be ${RUNTIME_DRIVER_USAGE}`);
       }
       const verbose = input.verbose === true;
       const catalogs = modelCatalogsForDriver(driver);
@@ -631,7 +635,7 @@ export default async function piCaLeashExtension(pi: ExtensionAPI) {
       properties: {
         prompt: { type: "string", description: "Task or role prompt for the peer." },
         name: { type: "string", description: "Optional explicit peer name." },
-        driver: { type: "string", enum: ["claude-sdk", "codex-cli"], description: "Optional runtime driver for this peer. Defaults to the extension startup driver." },
+        driver: { type: "string", enum: [...RUNTIME_DRIVER_ENUM], description: "Optional runtime driver for this peer. Defaults to the extension startup driver." },
         model: { type: "string", description: "Optional model to use for this peer session." },
         cwd: { type: "string", description: "Optional working directory for the peer. Relative paths resolve from the current pi working directory." },
       },
@@ -650,7 +654,7 @@ export default async function piCaLeashExtension(pi: ExtensionAPI) {
         throw new Error("prompt required");
       }
       if (input.driver != null && !driver) {
-        throw new Error("driver must be claude-sdk or codex-cli");
+        throw new Error(`driver must be ${RUNTIME_DRIVER_USAGE}`);
       }
       const effectiveDriver = driver ?? runtimeDriverConfig.defaultDriver;
       const modelSelection = resolveRuntimeModelSelection(effectiveDriver, model);
@@ -1137,7 +1141,7 @@ export default async function piCaLeashExtension(pi: ExtensionAPI) {
         task: { type: "string", description: "Task for the delegated run." },
         name: { type: "string", description: "Optional agent name for this run." },
         prompt: { type: "string", description: "Optional agent prompt. Defaults to a concise delegated-worker prompt." },
-        driver: { type: "string", enum: ["claude-sdk", "codex-cli"], description: "Optional runtime driver for this run." },
+        driver: { type: "string", enum: [...RUNTIME_DRIVER_ENUM], description: "Optional runtime driver for this run." },
         model: { type: "string", description: "Optional model override for this run." },
         cwd: { type: "string", description: "Optional working directory for this run. Relative paths resolve from the current pi working directory." },
         async: { type: "boolean", description: "Launch as background run and return immediately." },
@@ -1300,7 +1304,7 @@ export default async function piCaLeashExtension(pi: ExtensionAPI) {
       properties: {
         name: { type: "string", description: "Teammate name." },
         prompt: { type: "string", description: "Teammate bootstrap prompt." },
-        driver: { type: "string", enum: ["claude-sdk", "codex-cli"], description: "Optional runtime driver for this teammate." },
+        driver: { type: "string", enum: [...RUNTIME_DRIVER_ENUM], description: "Optional runtime driver for this teammate." },
         model: { type: "string", description: "Optional model override." },
         cwd: { type: "string", description: "Optional working directory. Relative paths resolve from the current pi working directory." },
       },
@@ -1539,7 +1543,21 @@ export default async function piCaLeashExtension(pi: ExtensionAPI) {
 
   async function handleDashboardCommand(args: string, ctx: ExtensionCommandContext, command: string): Promise<void> {
     await activatePeerMode(ctx, { command, reason: "Peer mode activated" });
-    const advanced = args.trim().toLowerCase() === "advanced";
+    const normalizedArgs = args.trim().toLowerCase();
+    if (["hide", "off", "close", "clear", "minimize", "minimise"].includes(normalizedArgs)) {
+      peerDashboardHidden = true;
+      ctx.ui.setWidget("peer-dashboard", undefined);
+      ctx.ui.notify("Peers widget hidden. Use /peer dashboard show to restore it.", "info");
+      return;
+    }
+    if (["show", "on", "open", "restore"].includes(normalizedArgs)) {
+      peerDashboardHidden = false;
+      lastWidgetSignature = undefined;
+      const data = await refreshDashboard(ctx, runtime, bridge, subagents, teams, dashboardState, attentionLedger, "Peers widget restored");
+      ctx.ui.notify(`Peers widget restored (${data.peers.length} peer${data.peers.length === 1 ? "" : "s"}).`, "info");
+      return;
+    }
+    const advanced = normalizedArgs === "advanced";
     await syncAttentionLedger();
     const data = await refreshDashboard(ctx, runtime, bridge, subagents, teams, dashboardState, attentionLedger);
     const health = getPeerFirstHealth(data.snapshot.peerRows, data.snapshot.transportDegraded);
@@ -1901,7 +1919,7 @@ export default async function piCaLeashExtension(pi: ExtensionAPI) {
         `/${command} ask <name> | <message>`,
         `/${command} send <name> | <message>`,
         `/${command} list`,
-        `/${command} models [claude-sdk|codex-cli] [all|advanced|verbose]`,
+        `/${command} models [claude-sdk|claude-cli|codex-cli] [all|advanced|verbose]`,
         `/${command} history <name> [cursor] [limit]`,
         `/${command} interrupt <name>`,
         `/${command} stop <name>`,
@@ -1910,7 +1928,7 @@ export default async function piCaLeashExtension(pi: ExtensionAPI) {
         "Driver/model forms",
         `/${command} start <prompt> | <driver> | <model>`,
         `/${command} start <name> | <prompt> | <driver> | <model>`,
-        "drivers: claude-sdk, codex-cli",
+        `drivers: ${RUNTIME_DRIVER_USAGE}`,
         "model aliases: sonnet, opus, haiku, mini, spark; exact ids are shown by /peer models",
         "",
         "Version/environment",
@@ -1938,7 +1956,7 @@ export default async function piCaLeashExtension(pi: ExtensionAPI) {
     });
   }
 
-  registerExtensionCommand(pi, "peer", "Peer dashboard and controls. Args: [about|init|dashboard|start|ask|send|list|models|history|interrupt|stop] ...", async (args, ctx) => {
+  registerExtensionCommand(pi, "peer", "Peer dashboard and controls. Args: [about|init|dashboard [hide|show|advanced]|start|ask|send|list|models|history|interrupt|stop] ...", async (args, ctx) => {
     const trimmed = args.trim();
     if (!trimmed) {
       await activatePeerMode(ctx, { command: "peer", showGuide: true, reason: "Peer mode activated" });
@@ -1965,6 +1983,16 @@ export default async function piCaLeashExtension(pi: ExtensionAPI) {
         await activatePeerMode(ctx, { command: "peer dashboard", showGuide: true, reason: "Peer mode activated" });
         await handleDashboardCommand(rest, ctx, "peer dashboard");
         return;
+      case "hide":
+      case "minimize":
+      case "minimise":
+        await activatePeerMode(ctx, { command: "peer dashboard hide", showGuide: true, reason: "Peer mode activated" });
+        await handleDashboardCommand("hide", ctx, "peer dashboard hide");
+        return;
+      case "show":
+        await activatePeerMode(ctx, { command: "peer dashboard show", showGuide: true, reason: "Peer mode activated" });
+        await handleDashboardCommand("show", ctx, "peer dashboard show");
+        return;
       case "start":
         await activatePeerMode(ctx, { command: "peer start", showGuide: true, reason: "Peer mode activated" });
         await handlePeerStartCommand(rest, ctx, "peer start");
@@ -2425,6 +2453,10 @@ async function refreshDashboard(
 
   if (!process.argv.includes("--no-session")) {
     ctx.ui.setStatus(EXTENSION_NAME, undefined);
+    if (peerDashboardHidden) {
+      ctx.ui.setWidget("peer-dashboard", undefined);
+      return data;
+    }
     const newSignature = computeWidgetSignature({
       peerRows: data.snapshot.peerRows.filter(isPeerVisibleInWidget),
       transportDegraded: data.snapshot.transportDegraded,
@@ -2683,7 +2715,7 @@ function completePeerCommand(prefix: string, names: Set<string>): AutocompleteIt
   }
   if (subcommand === "models") {
     const trimmed = restParts.join(" ").trim();
-    const items = ["claude-sdk", "codex-cli"]
+    const items = [...RUNTIME_DRIVER_ENUM]
       .filter((driver) => trimmed.length === 0 || driver.startsWith(trimmed))
       .map((driver) => ({ value: driver, label: driver }));
     return items.length > 0 ? items : null;
@@ -2972,8 +3004,8 @@ function formatAttentionReport(attention: AttentionView[]): string {
   );
 }
 
-function parsePeerModelsArgs(args: string): { driver?: "claude-sdk" | "codex-cli"; verbose: boolean } {
-  let driver: "claude-sdk" | "codex-cli" | undefined;
+function parsePeerModelsArgs(args: string): { driver?: (typeof RUNTIME_DRIVER_ENUM)[number]; verbose: boolean } {
+  let driver: (typeof RUNTIME_DRIVER_ENUM)[number] | undefined;
   let verbose = false;
   for (const token of args.trim().split(/\s+/).filter(Boolean)) {
     const parsedDriver = parseRuntimeDriverName(token);
@@ -2985,7 +3017,7 @@ function parsePeerModelsArgs(args: string): { driver?: "claude-sdk" | "codex-cli
       verbose = true;
       continue;
     }
-    throw new Error("usage: /peer models [claude-sdk|codex-cli] [all|advanced|verbose]");
+    throw new Error("usage: /peer models [claude-sdk|claude-cli|codex-cli] [all|advanced|verbose]");
   }
   return { driver, verbose };
 }
@@ -3173,9 +3205,13 @@ function compactModel(model: string): string {
 function compactDriver(driver: string): string {
   switch (driver) {
     case "claude-sdk":
+      return "sdk";
+    case "claude-cli":
       return "claude";
     case "codex-cli":
       return "codex";
+    case "pi-coding-agent":
+      return "pi-ca";
     default:
       return driver.length > 7 ? `${driver.slice(0, 6)}…` : driver;
   }

package/extensions/model-catalog.ts

@@ -13,7 +13,7 @@ export interface RuntimeModelCatalogEntry {
 
 export interface RuntimeDriverModelCatalog {
   driver: RuntimeDriverName;
-  provider: "anthropic" | "openai-codex";
+  provider: "anthropic" | "openai-codex" | "pi-ai";
   defaultModel: string;
   aliases: Record<string, string>;
   recommendations: RuntimeModelRecommendation[];
@@ -39,7 +39,7 @@ export interface RuntimeModelSelection {
 
 const LANISTA_SOURCE = "lanista agents anthropic/codex";
 
-export const RUNTIME_MODEL_CATALOGS: Record<RuntimeDriverName, RuntimeDriverModelCatalog> = {
+export const RUNTIME_MODEL_CATALOGS: Record<string, RuntimeDriverModelCatalog> = {
   "claude-sdk": {
     driver: "claude-sdk",
     provider: "anthropic",
@@ -108,7 +108,7 @@ export const RUNTIME_MODEL_CATALOGS: Record<RuntimeDriverName, RuntimeDriverMode
       { id: "gpt-5.2", name: "GPT-5.2", contextWindow: 272000, maxTokens: 128000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 1.75, outputCostPerMillion: 14 },
       { id: "gpt-5.2-codex", name: "GPT-5.2 Codex", contextWindow: 272000, maxTokens: 128000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 1.75, outputCostPerMillion: 14 },
       { id: "gpt-5.3-codex", name: "GPT-5.3 Codex", contextWindow: 272000, maxTokens: 128000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 1.75, outputCostPerMillion: 14 },
-      { id: "gpt-5.3-codex-spark", name: "GPT-5.3 Codex Spark", contextWindow: 128000, maxTokens: 128000, reasoning: true, inputModalities: ["text"], inputCostPerMillion: 0, outputCostPerMillion: 0 },
+      { id: "gpt-5.3-codex-spark", name: "GPT-5.3 Codex Spark", contextWindow: 128000, maxTokens: 128000, reasoning: true, inputModalities: ["text"], inputCostPerMillion: 3.5, outputCostPerMillion: 28 },
       { id: "gpt-5.4", name: "GPT-5.4", contextWindow: 272000, maxTokens: 128000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 2.5, outputCostPerMillion: 15 },
       { id: "gpt-5.4-mini", name: "GPT-5.4 Mini", contextWindow: 272000, maxTokens: 128000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 0.75, outputCostPerMillion: 4.5 },
       { id: "gpt-5.5", name: "GPT-5.5", contextWindow: 272000, maxTokens: 128000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 5, outputCostPerMillion: 30 },
@@ -118,18 +118,26 @@ export const RUNTIME_MODEL_CATALOGS: Record<RuntimeDriverName, RuntimeDriverMode
 
 export function modelCatalogsForDriver(driver?: RuntimeDriverName): RuntimeDriverModelCatalog[] {
   if (driver) {
-    return [RUNTIME_MODEL_CATALOGS[driver]];
+    return [catalogForDriver(driver)];
   }
-  return [RUNTIME_MODEL_CATALOGS["claude-sdk"], RUNTIME_MODEL_CATALOGS["codex-cli"]];
+  // claude-cli intentionally omitted: the driver is unstable in practice
+  // (sticky-session / non-interactive output issues), so it is not part of
+  // the recommended runtime surface. Callers that explicitly request it
+  // via catalogForDriver("claude-cli") will throw.
+  return [
+    catalogForDriver("claude-sdk"),
+    catalogForDriver("codex-cli"),
+    catalogForDriver("pi-coding-agent"),
+  ];
 }
 
 export function findRuntimeModel(driver: RuntimeDriverName, model: string): RuntimeModelCatalogEntry | undefined {
   const normalized = model.trim();
-  return RUNTIME_MODEL_CATALOGS[driver].models.find((entry) => entry.id === normalized);
+  return catalogForDriver(driver).models.find((entry) => entry.id === normalized);
 }
 
 export function resolveRuntimeModelSelection(driver: RuntimeDriverName, model?: string): RuntimeModelSelection {
-  const catalog = RUNTIME_MODEL_CATALOGS[driver];
+  const catalog = catalogForDriver(driver);
   const requestedModel = model?.trim() || undefined;
   if (!requestedModel) {
     return {
@@ -168,6 +176,31 @@ export function resolveRuntimeModelSelection(driver: RuntimeDriverName, model?:
   };
 }
 
+function catalogForDriver(driver: RuntimeDriverName): RuntimeDriverModelCatalog {
+  if (driver === "claude-cli") {
+    throw new Error(
+      "claude-cli driver is no longer supported by the runtime model catalog " +
+        "(driver retired due to sticky-session / non-interactive output issues). " +
+        "Use claude-sdk for Claude models.",
+    );
+  }
+  if (driver === "pi-coding-agent") {
+    // pi-coding-agent routes through pi-ai, which only proxies gpt-* models
+    // in our environment. Inherit the codex-cli catalog so recommendations
+    // and model entries advertise the actually-supported set.
+    const base = RUNTIME_MODEL_CATALOGS["codex-cli"]!;
+    return {
+      ...base,
+      driver,
+      provider: "pi-ai",
+      cli: "pi",
+      flag: "pi --model <provider>/<id>",
+      source: `${base.source}; shared with codex-cli catalog (pi-coding-agent routes through pi-ai to gpt-* models)`,
+    };
+  }
+  return RUNTIME_MODEL_CATALOGS[driver]!;
+}
+
 export function describeModelSelection(driver: RuntimeDriverName, model?: string): string | undefined {
   return resolveRuntimeModelSelection(driver, model).note;
 }

package/extensions/prompts/peer-start-tool.md

@@ -1,7 +1,7 @@
 Start a long-lived runtime-backed peer for delegated work. Returns peer name, state, session id, driver, model, cwd, and latest visible peer reply when available.
 - Use `peer_start` when you want a reusable long-lived peer instead of solving the task in the current turn.
 - Pass `name` only when you need a stable explicit peer name; otherwise let the tool auto-name from prompt.
-- Pass `driver` when you need to force `claude-sdk` or `codex-cli` for this peer instead of using the extension default.
+- Pass `driver` when you need to force `claude-sdk`, `claude-cli`, or `codex-cli` for this peer instead of using the extension default.
 - Call `runtime_models` first when you need the supported model ids for a driver.
 - Pass `model` and `cwd` when you need a specific model and working directory.
 - Keep bootstrap prompts scoped. If the tool reports a prompt size warning, start a smaller peer and point it at files instead of pasting large context.

package/extensions/prompts/runtime-models-tool.md

@@ -1,6 +1,6 @@
-Inspect available model ids for claude-sdk and codex-cli before passing a model override to peer_start, peer_ask, subagent_run, or team_spawn.
+Inspect available model ids for claude-sdk, claude-cli, and codex-cli before passing a model override to peer_start, peer_ask, subagent_run, or team_spawn.
 - Use `runtime_models` before choosing a non-default model.
-- Use `driver` to narrow results to `claude-sdk` or `codex-cli`.
+- Use `driver` to narrow results to `claude-sdk`, `claude-cli`, or `codex-cli`.
 - Default output is a short recommended list with advisory use cases; pass `verbose: true` only when you need every bundled model id.
 - The report includes supported shorthand aliases. For example, Claude aliases such as `sonnet`, `opus`, and `haiku` are resolved to concrete model ids before launch.
 - Catalog entries are advisory; provider and CLI entitlements can drift, so unknown model ids are passed through to the runtime.

package/extensions/prompts/subagent-run-tool.md

@@ -1,6 +1,6 @@
 Run a delegated subagent task through the local backend. Supports driver, model, cwd, and optional async execution.
 - Use `subagent_run` when you need a bounded delegated run instead of a reusable peer.
-- Pass `driver` to force `claude-sdk` or `codex-cli` for this run instead of using the extension default.
+- Pass `driver` to force `claude-sdk`, `claude-cli`, or `codex-cli` for this run instead of using the extension default.
 - Call `runtime_models` first when you need the supported model ids for a driver.
 - Pass `async: true` when you want to launch a background run and inspect it later with `subagent_status` or `subagent_list`.
 - Keep delegated tasks bounded. If the tool reports a prompt size warning, split the run into smaller slices.

package/extensions/prompts/team-spawn-tool.md

@@ -1,5 +1,5 @@
 Spawn a persistent teammate when you want a named worker you can task or message repeatedly.
 - Use `team_spawn` for a persistent named worker, not for one-off bounded work.
-- Pass `driver` to force `claude-sdk` or `codex-cli` for this teammate instead of using the extension default.
+- Pass `driver` to force `claude-sdk`, `claude-cli`, or `codex-cli` for this teammate instead of using the extension default.
 - Call `runtime_models` first when you need the supported model ids for a driver.
 - Keep the teammate bootstrap prompt compact; give detailed work through later `team_task` or `team_message` calls.