pi-bro 0.15.1 → 0.16.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to pi-bro are documented here.
 
+## [0.16.0] - 2026-09-24
+
+### Added
+
+- Claude Code execution for explain, show and advisor, selected independently per capability through `/bro config`. Explain/show disable tools and customizations; advisor runs fresh with workspace tools. Claude-backed BTW is explicitly unsupported in this release.
+- Backend-tagged model/effort selections with atomic per-capability overrides. Existing settings remain Agy selections and are migrated to version 2 only when saved; Agy remains the default.
+
 ## [0.15.1] - 2026-09-22
 
 ### Changed

package/README.md

@@ -7,7 +7,8 @@ plain-language explanation — or open a sandboxed side conversation with
 `pi-bro` is an extension for [Earendil Pi](https://github.com/earendil-works/pi).
 It opens explanations in a separate modal and uses the
 [Google Antigravity CLI](https://antigravity.google/docs/cli-install) (`agy`)
-with your selected model.
+with your selected model. Claude Code is also supported for explain, show and
+advisor; Agy remains the default and is required for BTW.
 
 ## Quick start
 
@@ -32,7 +33,7 @@ Restart Pi or run `/reload`, then try:
 Run `/bro doctor` after installation or whenever Bro is not working.
 
 Explain, show, BTW and advisor share an internal execution layer; Agy remains
-its only backend and existing settings are unchanged. Cancellation, host deadlines
+the default backend. Claude Code can be selected per capability in `/bro config`. Cancellation, host deadlines
 and invalid execution streams terminate the subprocess group on POSIX, escalating
 after a five-second grace period. Windows cleanup targets the direct child only;
 descendant termination is not guaranteed. Unexpected signal exits are reported as
@@ -70,7 +71,7 @@ text directly captures a new source the same way.
 | `/bro show [n-turns] [query]` | Draw recent session turns (default last 1) as shapes instead of prose, from user and assistant conversation text only — tool calls, tool results, reasoning, and images are omitted. An optional query steers what the shapes focus on, with or without a leading turn count. |
 | `/bro doctor` | Check Bro's settings, Agy installation, account, model, effort, and mode. |
 | `/bro usage [--provider agy]` | Show current Agy resource limits. |
-| `/bro model [id]` | View or choose the shared default Agy model. |
+| `/bro model [id]` | View or choose the selected backend’s shared default model. |
 | `/bro effort [low\|medium\|high]` | View or choose the shared default reasoning effort. |
 | `/bro mode [brief\|balanced\|faithful]` | View or choose the explanation mode. |
 | `/bro config` | Open an interactive settings screen for the shared default model/effort, explain mode, show turns, and per-capability (explain/show/btw/advisor) model and effort overrides. |
@@ -164,7 +165,7 @@ gives an `agy update` action when it is too old.
   summary. Bro captures a harness-neutral snapshot — the executor's system
   instructions, its active tools, and the conversation so far including tool
   calls and results — and sends it, along with an optional `question` the
-  executor may pass, to a **fresh, standalone Agy process** for every
+  executor may pass, to a **fresh, standalone process of the selected backend** for every
   consultation. Nothing is resumed or reused across calls, including retries.
 - **Instructed to investigate, not implement**: the advisor process has real
   tool access in the workspace with permissions auto-approved
@@ -694,32 +695,46 @@ Bro creates this user-editable settings file when the extension loads:
 ~/.pi/agent/bro-settings.json
 ```
 
-```json
-{
-  "model": "gemini-3.7-flash",
-  "effort": "low",
-  "mode": "balanced",
-  "showTurns": 1
-}
-```
-
-`model` and `effort` are the **shared default**: explain, show, and btw all use
-them unless a capability has its own override. An optional `overrides` object
-adds per-capability overrides, each a full `{ "model": ..., "effort": ... }`
-pair:
+Existing flat model/effort files remain valid and select Agy. Explicit saves use
+version 2 with backend-tagged selections:
 
 ```json
 {
-  "model": "gemini-3.7-flash",
-  "effort": "low",
+  "version": 2,
+  "default": { "backend": "agy", "model": "gemini-3.7-flash", "effort": "low" },
   "mode": "balanced",
   "showTurns": 1,
   "overrides": {
-    "show": { "model": "gemini-3.7-pro", "effort": "high" }
+    "explain": { "backend": "claude", "model": "sonnet", "effort": "medium" },
+    "advisor": { "backend": "claude", "model": "opus", "effort": "high" }
   }
 }
 ```
 
+Each override is a complete backend/model/effort selection, never a field-by-field
+merge. Omitted overrides inherit the shared default. Matching an override to the
+default does not unpin it; select Default explicitly to restore inheritance.
+
+### Claude Code
+
+Install and authenticate `claude` independently (tested with Claude Code 2.1.281).
+Bro uses its CLI account and billing route, not Pi provider credentials. Choose
+Claude in `/bro config`; model aliases such as `sonnet` and `opus`, or explicit
+model IDs, are passed to the CLI. Claude efforts are `default` (omit the flag),
+`low`, `medium`, `high`, `xhigh`, and `max`; the chosen model/account must support
+the requested combination. Runtime rejection is surfaced without fallback.
+
+Explain/show use a scratch directory, safe mode, disabled tools, empty strict MCP
+configuration, disabled skills and no session persistence. This is a tool/configuration
+restriction, not an OS sandbox; built-in and managed Claude behavior can remain.
+Advisor uses safe mode and a fresh workspace process with permissions bypassed;
+it can modify files, and instructions to only advise remain behavioral. Running
+that mode as root may be rejected by Claude. BTW remains Agy-only: if a Claude
+shared default makes BTW unsupported, select an explicit Agy override.
+
+Doctor distinguishes CLI installation and configured authentication from a live
+request; it does not run a Claude model turn. `/bro usage` remains Agy-specific.
+
 Use `/bro model`, `/bro effort`, and `/bro mode` to update the shared default
 and mode from Pi, `/bro config` to review or change the shared default and any
 per-capability (explain/show/btw/advisor) overrides interactively, or edit the file
@@ -749,9 +764,9 @@ PI_BRO_MODEL=gemini-3.7-flash-low pi
 ### Configuration precedence
 
 When resolving model and reasoning effort:
-1. **Per-capability override**: If configured under `overrides.<capability>` (`explain`, `show`, `btw`, or `advisor`) in `bro-settings.json`, that capability pins its own `{ "model": ..., "effort": ... }` pair and ignores the shared default.
-2. **Shared default**: If no override is set for that capability, it inherits the root `model` and `effort` in `bro-settings.json`.
-3. **Catalog normalization**: Bro normalizes the resolved `{ model, effort }` against Agy's installed model catalog (mapping suffixed variant IDs and handling fixed-effort models).
+1. **Per-capability override**: If configured under `overrides.<capability>` (`explain`, `show`, `btw`, or `advisor`) in `bro-settings.json`, that capability pins its own complete backend/model/effort selection and ignores the shared default.
+2. **Shared default**: If no override is set for that capability, it inherits `default` in version-2 settings (root model/effort in legacy settings).
+3. **Catalog normalization**: For Agy selections, Bro normalizes the resolved `{ model, effort }` against Agy's installed model catalog (mapping suffixed variant IDs and handling fixed-effort models).
 4. **Initial file creation only**: `PI_BRO_MODEL` selects the initial default model only when Bro creates a missing `bro-settings.json` file. It has no effect once the file exists.
 
 When resolving turn count for `/bro show`:
@@ -799,7 +814,7 @@ run `/bro doctor` for the exact problem.
 - **External requests**: Bro sends the latest completed assistant response,
   pasted text, extracted document text, extracted webpage text, or recent
   session conversation text (tool calls, tool results, reasoning, and images
-  omitted) to Agy and its configured model provider.
+  omitted) to the selected backend and its configured model provider.
 - **Side conversation requests**: `/bro btw` sends your side questions and, on
   the first turn, the seeded main-session conversation text to Agy. In `--full`
   mode the side agent additionally reads the workspace.
@@ -830,14 +845,14 @@ run `/bro doctor` for the exact problem.
   URLs whose query string contains secrets.
 - **Web extraction**: Bro parses downloaded HTML locally without executing page
   scripts or loading page subresources. It sends the extracted readable text,
-  including links preserved in that text, to Agy; it does not separately send
+  including links preserved in that text, to the selected backend; it does not separately send
   the requested URL or raw page HTML. The URL, captured text, and explanation
   remain in process memory only and clear with the existing `/bro open` cache.
 - **Show diagrams**: When a show reply ends in one self-contained HTML block,
   Bro writes it to `/tmp/pi-bro-<uid>/bro-show-<hash>.html` with a restrictive
   Content-Security-Policy, and opens it in your browser only when you press
   **O**. **C** copies the full reply, including the HTML.
-- **Provider data**: Agy and your model provider may retain logs and request data
+- **Provider data**: The selected CLI backend and your model provider may retain logs and request data
   according to their own settings and privacy policies.
 - **Clipboard**: Pressing **C** copies the text to your system clipboard, where
   your operating system or clipboard manager may retain it.
@@ -845,7 +860,7 @@ run `/bro doctor` for the exact problem.
   instructions, active tool list (excluding `bro_advisor`), ordered
   conversation history including tool calls and tool results (unlike Show, which
   omits them), human steering brief, and the executor's optional question to
-  Agy and your configured model provider. Reasoning and image bodies are
+  the selected backend and its configured model provider. Reasoning and image bodies are
   omitted with explicit markers (`[reasoning omitted]`, `[image omitted]`).
 - **Advisor tool execution & safety boundary**: The advisor process runs
   directly in your workspace (`cwd`) with auto-approved permissions
@@ -867,7 +882,7 @@ extracted, copy its content into a supported text file or save it as a PDF and
 use `/bro file`. If a PDF contains only scanned images, run OCR with another
 tool before giving it to Bro.
 
-- Uses Agy as its only provider.
+- Supports Agy for all capabilities and Claude Code for explain/show/advisor. Claude BTW is not yet supported; unsupported selections fail without fallback.
 - Document input supports `.md`, `.markdown`, `.txt`, `.pdf`, and `.docx` only;
   it does not perform OCR.
 - Webpage input supports one public HTML page, up to 5 MiB downloaded and
@@ -906,7 +921,7 @@ npm test
 pi --tui-mode fullscreen -e ./bro.ts
 ```
 
-The smoke test uses a fake `agy`, so it does not call an external model. It
+The smoke test uses a fake `agy`, and Claude adapter tests use a fake `claude`, so automated tests do not call an external model. It
 verifies command routing, document and URL safety boundaries, HTML
 extraction, show capture (conversation text only, tool calls and results
 absent), and HTML-diagram handling, healthy and broken setup handling,

package/backend.ts

@@ -5,14 +5,18 @@ import { join } from "node:path";
 import { createInterface } from "node:readline";
 
 // Shared internal execution boundary for all four Bro features (explain, show, btw, advisor).
-// This is the Agy-only implementation of docs/plans/2026-09-22-shared-backend-design.md: it owns
-// Agy CLI selection, process invocation, progress/outcome normalization, continuation, and
+// This implements docs/plans/2026-09-22-shared-backend-design.md for Agy (all features) and the
+// Claude Code CLI (explain/show/advisor; no btw yet): it owns CLI selection, process invocation, progress/outcome normalization, continuation, and
 // single-attempt cleanup. Feature code (bro.ts) keeps retries, UI, source/session capture and
 // settings.
 
 export type BackendFeature = "explain" | "show" | "btw" | "advisor";
 export type BackendAccess = "restricted" | "workspace-full";
 export type AgySelection = { model: string; effort?: "low" | "medium" | "high" };
+export const CLAUDE_EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;
+export type BackendSelection =
+	| ({ backend?: "agy" } & AgySelection)
+	| { backend: "claude"; model: string; effort?: (typeof CLAUDE_EFFORTS)[number] };
 export type BackendContinuation = { id: string };
 export type BackendProgress = { kind: "text"; text: string } | { kind: "activity"; label: string; timestamp: number };
 export type BackendOnProgress = (progress: BackendProgress) => void;
@@ -61,14 +65,17 @@ export function agySelection(pair: { model: string; effort: "default" | "low" |
 	};
 }
 
-function processStartMessage(processError: NodeJS.ErrnoException): string {
-	return processError.code === "ENOENT"
-		? "Agy could not start. Make sure Agy is installed and on PATH, then run `/bro doctor`."
-		: `Agy could not start: ${processError.message}\n\nRun \`/bro doctor\` for setup help.`;
+function processStartMessage(processError: NodeJS.ErrnoException, cli = "Agy"): string {
+	if (processError.code === "ENOENT") {
+		return cli === "Agy"
+			? "Agy could not start. Make sure Agy is installed and on PATH, then run `/bro doctor`."
+			: "Claude Code could not start. Make sure `claude` is installed and on PATH, then run `/bro doctor`.";
+	}
+	return `${cli} could not start: ${processError.message}\n\nRun \`/bro doctor\` for setup help.`;
 }
 
-function unexpectedSignalMessage(exitSignal: NodeJS.Signals | null): string {
-	return withDoctor(`Agy exited unexpectedly${exitSignal ? ` (signal ${exitSignal})` : ""}, not from a request Bro made.`);
+function unexpectedSignalMessage(exitSignal: NodeJS.Signals | null, cli = "Agy"): string {
+	return withDoctor(`${cli} exited unexpectedly${exitSignal ? ` (signal ${exitSignal})` : ""}, not from a request Bro made.`);
 }
 
 // Sends to the whole POSIX process group when possible so a misbehaving grandchild dies too, not
@@ -481,6 +488,207 @@ async function executeAdvisorStdin(
 	return { status: "success", text };
 }
 
+
+// Claude Code supports every feature except btw (it has no continuation wiring yet).
+export function backendSupports(backend: "agy" | "claude", feature: BackendFeature): boolean {
+	return backend === "agy" || feature !== "btw";
+}
+
+type ClaudeEvent = {
+	type?: unknown;
+	subtype?: unknown;
+	is_error?: unknown;
+	result?: unknown;
+	parent_tool_use_id?: unknown;
+	stop_reason?: unknown;
+	terminal_reason?: unknown;
+	event?: { type?: unknown; delta?: { type?: unknown; text?: unknown } };
+	message?: { content?: unknown };
+};
+
+// Every Claude run is fresh (never resumed, nothing persisted) under --safe-mode, which disables
+// CLAUDE.md, skills, plugins, hooks and MCP servers but keeps the user's auth (--bare would break
+// OAuth). The prompt goes over stdin. explain/show additionally run tool-less in a scratch cwd;
+// advisor runs in the caller's workspace with tools auto-approved. Only the terminal `result`
+// event is authoritative; streamed text_delta events are progress only, and thinking is dropped.
+async function executeClaude(
+	request: BackendRequest,
+	selection: { model: string; effort?: string },
+	signal: AbortSignal,
+	onProgress: BackendOnProgress | undefined,
+	killEscalationMs: number,
+	deadlineMsOverride: number | undefined,
+): Promise<BackendOutcome> {
+	const isAdvisor = request.feature === "advisor";
+	const deadlineMs = deadlineMsOverride ?? (isAdvisor ? 610_000 : 125_000);
+	const action = isAdvisor ? "complete the advisor consultation" : "simplify the response";
+
+	if (signal.aborted) return { status: "cancelled", message: "Canceled." };
+	const runDirectory = isAdvisor ? undefined : await mkdtemp(join(tmpdir(), "pi-bro-"));
+	if (signal.aborted) {
+		if (runDirectory) await rm(runDirectory, { recursive: true, force: true });
+		return { status: "cancelled", message: "Canceled." };
+	}
+
+	try {
+		const child = spawn(
+			"claude",
+			[
+				"-p",
+				"--safe-mode",
+				"--no-session-persistence",
+				"--disable-slash-commands",
+				"--output-format",
+				"stream-json",
+				"--verbose",
+				"--include-partial-messages",
+				...(isAdvisor
+					? ["--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}', "--dangerously-skip-permissions"]
+					: ["--tools", "", "--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}', "--permission-mode", "dontAsk"]),
+				"--model",
+				selection.model,
+				...(selection.effort ? ["--effort", selection.effort] : []),
+			],
+			{
+				cwd: isAdvisor ? request.cwd : runDirectory,
+				stdio: ["pipe", "pipe", "pipe"],
+				windowsHide: true,
+				detached: process.platform !== "win32",
+			},
+		);
+
+		const attempt = beginAttempt(child, signal, deadlineMs, killEscalationMs);
+		let processError: Error | undefined;
+		let stderr = "";
+		let partial = "";
+		let final: string | undefined;
+		let terminalError: string | undefined;
+		let protocolError: string | undefined;
+		let stdoutBuffer = "";
+
+		child.stderr?.setEncoding("utf8");
+		child.stderr?.on("data", (chunk: string) => {
+			stderr += chunk;
+		});
+		child.once("error", (error) => {
+			processError = error;
+		});
+		child.stdin?.on("error", () => {
+			// claude exiting before it reads stdin is reported through the close/error path below.
+		});
+		child.stdin?.end(request.prompt);
+
+		const handleLine = (line: string) => {
+			if (!line.trim() || attempt.causeOf()) return;
+			let event: ClaudeEvent;
+			try {
+				event = JSON.parse(line) as ClaudeEvent;
+			} catch {
+				throw new Error("Claude emitted invalid stream-json output.");
+			}
+			const topLevel = event.parent_tool_use_id === undefined || event.parent_tool_use_id === null;
+			if (!isAdvisor && topLevel && event.type === "stream_event" && event.event?.type === "content_block_delta") {
+				const delta = event.event.delta;
+				if (delta?.type === "text_delta" && typeof delta.text === "string" && delta.text) {
+					partial += delta.text;
+					onProgress?.({ kind: "text", text: partial });
+				}
+			}
+			if (isAdvisor && topLevel && event.type === "assistant" && Array.isArray(event.message?.content)) {
+				for (const block of event.message.content as Array<{ type?: unknown; name?: unknown; text?: unknown }>) {
+					const label =
+						block?.type === "tool_use" && typeof block.name === "string"
+							? block.name.trim()
+							: block?.type === "text" && typeof block.text === "string"
+								? block.text.split("\n").find((text) => text.trim())?.trim()
+								: undefined;
+					if (label) onProgress?.({ kind: "activity", label, timestamp: Date.now() });
+				}
+			}
+			if (event.type !== "result" || !topLevel) return;
+			if (event.subtype === "success" && event.is_error === false && (event.stop_reason !== "end_turn" || (event.terminal_reason !== undefined && event.terminal_reason !== "completed"))) {
+				terminalError ??= `Claude did not complete the answer (stop reason: ${String(event.stop_reason)}, terminal reason: ${String(event.terminal_reason)}).`;
+				return;
+			}
+			// A result ends a model turn, not necessarily the stream; the first failure is latched and
+			// otherwise the latest successful result wins once the process exits cleanly.
+			if (event.subtype === "success" && event.is_error === false && typeof event.result === "string") {
+				final = event.result;
+			} else {
+				const detail =
+					typeof event.subtype === "string" && event.subtype !== "success"
+						? event.subtype
+						: typeof event.result === "string" && event.result.trim()
+							? event.result.trim()
+							: "turn failed";
+				terminalError ??= `Claude failed: ${detail}`;
+			}
+		};
+
+		child.stdout?.setEncoding("utf8");
+		child.stdout?.on("data", (chunk: string) => {
+			stdoutBuffer += chunk;
+			const parts = stdoutBuffer.split(/\r?\n/);
+			stdoutBuffer = parts.pop() ?? "";
+			if (stdoutBuffer.length > ADVISOR_MAX_STDOUT_LINE_CHARS || parts.some((line) => line.length > ADVISOR_MAX_STDOUT_LINE_CHARS)) {
+				protocolError ??= `Claude emitted a stdout line over ${ADVISOR_MAX_STDOUT_LINE_CHARS} characters; the stream is unparseable.`;
+				stdoutBuffer = "";
+				attempt.stop("protocol");
+				return;
+			}
+			for (const line of parts) {
+				try {
+					handleLine(line);
+				} catch (error) {
+					protocolError ??= errorMessage(error);
+					attempt.stop("protocol");
+					return;
+				}
+			}
+		});
+
+		const { code, exitSignal } = await attempt.closed;
+		attempt.dispose();
+		if (stdoutBuffer.trim()) {
+			try {
+				handleLine(stdoutBuffer);
+			} catch (error) {
+				protocolError ??= errorMessage(error);
+			}
+		}
+
+		const partialText = partial || undefined;
+		const cause = attempt.causeOf();
+		if (cause === "cancelled") return { status: "cancelled", message: "Canceled.", partialText };
+		if (cause === "timeout") {
+			const during = isAdvisor ? "during the advisor consultation" : "while simplifying the response";
+			return { status: "timeout", message: `Claude timed out ${during}. Run \`/bro doctor\` for setup help.`, partialText };
+		}
+		if (protocolError) return { status: "failure", message: withDoctor(protocolError), partialText };
+		if (processError) return { status: "failure", message: processStartMessage(processError as NodeJS.ErrnoException, "Claude") };
+		if (exitSignal || code === null) return { status: "failure", message: unexpectedSignalMessage(exitSignal, "Claude"), partialText };
+		if (terminalError) return { status: "failure", message: withDoctor(terminalError), partialText };
+		if (code !== 0) {
+			const detail = stderr.trim();
+			return {
+				status: "failure",
+				message: detail
+					? `Claude could not ${action}: ${detail}\n\nRun \`/bro doctor\` for setup help.`
+					: `Claude could not ${action}. Make sure Claude Code is installed and signed in, then run \`/bro doctor\`.`,
+				partialText,
+			};
+		}
+		if (final === undefined) {
+			return { status: "failure", message: withDoctor(`Claude exited without a result event${stderr.trim() ? `: ${stderr.trim()}` : "."}`), partialText };
+		}
+		const text = final.trim();
+		if (!text) return { status: "failure", message: withDoctor("Claude returned no final answer."), partialText };
+		return { status: "success", text };
+	} finally {
+		if (runDirectory) await rm(runDirectory, { recursive: true, force: true });
+	}
+}
+
 // Single-attempt executor shared by all four features. Never retries (retries are feature-owned,
 // e.g. advisor's 3-attempt backoff in bro.ts); never spawns a pre-aborted request; on cancellation,
 // host deadline, or a protocol failure, stops the whole POSIX process group (SIGTERM, then SIGKILL
@@ -488,7 +696,7 @@ async function executeAdvisorStdin(
 // callers never override the deadline or kill-escalation delay.
 export async function execute(
 	request: BackendRequest,
-	selection: AgySelection,
+	selection: BackendSelection,
 	signal: AbortSignal,
 	onProgress?: BackendOnProgress,
 	options?: BackendExecuteOptions,
@@ -500,6 +708,15 @@ export async function execute(
 		(request.feature !== "btw" && request.continuation)
 	) return { status: "failure", message: "Unsupported execution request: check feature access, workspace cwd and continuation." };
 	const killEscalationMs = options?.killEscalationMs ?? DEFAULT_KILL_ESCALATION_MS;
+	if (selection.backend === "claude") {
+		if (!backendSupports("claude", request.feature)) {
+			return { status: "failure", message: "Claude does not support /bro btw yet; switch btw back to Agy in `/bro config`." };
+		}
+		if (!selection.model.trim() || (selection.effort !== undefined && !CLAUDE_EFFORTS.includes(selection.effort))) {
+			return { status: "failure", message: "Unsupported Claude selection: check the model and effort (low, medium, high, xhigh or max)." };
+		}
+		return executeClaude(request, selection, signal, onProgress, killEscalationMs, options?.deadlineMs);
+	}
 	if (request.feature === "advisor") {
 		return executeAdvisorStdin(request, selection, signal, onProgress, killEscalationMs, options?.deadlineMs);
 	}