pi-bro 0.15.1 → 0.17.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to pi-bro are documented here.
 
+## [0.17.0] - 2026-09-24
+
+### Added
+
+- Grok Build execution for explain, show, native multi-turn BTW (both modes), and advisor, with per-capability model/effort configuration, custom model IDs, and installation diagnostics. Agy remains the default.
+- Capability-first Grok access: conversation-only intent uses prompt instructions when enforcement is unavailable, with truthful UI/docs rather than feature bans or speculative tool blacklists. Native tools remain available.
+- Private temporary prompt files, backend-bound continuation, authoritative terminal completion checks and bounded cancellation. Backend/access changes start a fresh BTW thread instead of reusing incompatible native session IDs.
+- Explain, show, and BTW modal headers show the model and reasoning effort each request used (`default` when the model's own effort applies); `/bro open` keeps the original label.
+
+### Changed
+
+- The BTW header no longer shows a sandbox/conversation-only access label; the `full · edits repo` badge still marks `--full` threads.
+
+### Removed
+
+- `/bro usage` is removed for now. Doctor still checks Agy account access.
+
+## [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

@@ -1,13 +1,14 @@
 # pi-bro
 
 Turn a dense AI reply, pasted text, local document, or public webpage into a
-plain-language explanation — or open a sandboxed side conversation with
+plain-language explanation — or open a separate side conversation with
 `/bro btw` — without adding anything to your main agent's context.
 
 `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
@@ -69,8 +70,7 @@ text directly captures a new source the same way.
 | `/bro open` | Reopen the latest explanation without calling the simplifier again. |
 | `/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. |
@@ -109,6 +109,10 @@ a persistent mode with `/bro mode`:
 - **O**: Open the HTML diagram when a show reply contains one
 - **Esc**: Close the modal, or cancel while Bro is working
 
+The modal header shows the model and reasoning effort the explanation or
+drawing used (`default` when the model's own effort applies); `/bro open`
+keeps the original label.
+
 Bro temporarily captures mouse input while its modal is open. Native mouse
 selection may be unavailable or visually extend outside the modal depending on
 your terminal mode; press **C** to copy the complete explanation reliably.
@@ -116,17 +120,19 @@ your terminal mode; press **C** to copy the complete explanation reliably.
 ## Bro btw (side conversation)
 
 `/bro btw` opens a separate multi-turn conversation in a modal, so you can ask
-a quick side question while the main agent keeps working. It runs through Agy,
-the same backend as the rest of Bro, and never adds anything to Pi's
+a quick side question while the main agent keeps working. It runs through the
+selected Agy or Grok backend and never adds anything to Pi's
 conversation unless you explicitly insert it into the editor.
 
-- **Sandboxed by default**: the side conversation is read-only (no project
-  access). Add `--full` to let it read and edit the workspace.
+- **Conversation-only intent by default**: Agy uses its sandbox controls; Grok
+  receives prompt instructions to stay within supplied context, with normal tools
+  still available. Grok is not sandboxed. Add `--full` to explicitly invite
+  workspace investigation and edits.
 - `/bro btw <question>` asks immediately; `/bro btw` opens an empty thread.
 - `--fresh` starts a thread without seeding the main session's recent
   conversation text. Reopening without an access flag preserves the existing
-  thread's access mode, including `--full`. Use `--sandbox` to return to sandbox
-  mode; changing access mode starts a new thread. `--fresh` alone does not reset
+  thread's access mode, including `--full`. Use `--sandbox` to return to conversation-only
+  intent; changing access mode starts a new thread. `--fresh` alone does not reset
   the access mode.
 - The first turn is seeded with up to the last 8 turns of user/assistant
   conversation text (40,000 characters max, with a truncation notice); the
@@ -139,7 +145,7 @@ conversation unless you explicitly insert it into the editor.
   - `/insert-all`: inserts the full thread into the main editor without submitting (use `/insert-all!` to replace an existing editor draft)
   - `/retry`: re-asks the last question (empty Enter does the same)
   - `/clear`: resets the thread
-  Any other text or slash-prefixed input (such as `/send` or `/copy!`) is not a composer command and is submitted directly as a question to the side conversation. Esc closes the modal. A visible `full · edits repo` badge shows whenever `--full` mode is active.
+  Any other text or slash-prefixed input (such as `/send` or `/copy!`) is not a composer command and is submitted directly as a question to the side conversation. Esc closes the modal. The header shows the model and reasoning effort the latest turn used (`default` when the model's own effort applies), and a visible `full · edits repo` badge shows whenever `--full` mode is active.
 - The thread lives in memory only — it clears when you switch Pi sessions,
   reload extensions, or quit Pi.
 
@@ -164,7 +170,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
@@ -224,7 +230,7 @@ changes the form: it draws what you and the assistant said in the last few
 session turns as a shape instead of paragraphs. Capture keeps only user and
 assistant conversation text, including every intermediate assistant message in
 a turn — tool calls, tool results, reasoning, and images never leave the
-session. It runs the same isolated, sandboxed model call and shows the result
+session. It runs the same backend-specific model call and shows the result
 in the same modal, never touching your conversation. `/bro show` uses its own
 draw prompt; the explanation modes and `bro-prompt.md` do not affect it.
 
@@ -694,32 +700,71 @@ 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. Claude BTW continuation is not wired yet (tracked in #58): if a Claude
+shared default makes BTW unsupported, select an explicit Agy or Grok override.
+
+Doctor distinguishes CLI installation and configured authentication from a live
+request; it does not run a Claude model turn.
+
+### Grok Build
+
+Grok supports **explain, show, BTW (both modes), and advisor**, using the
+separately authenticated `grok` CLI (tested with 1.0.41). Seeded choices are
+`grok-4.7` and `grok-4.7-build-fast`; custom IDs are accepted. Efforts are
+`default` (omit the flag), `low`, `medium`, `high`, and `xhigh`; model-specific
+rejection is surfaced without silently changing your selection.
+
+Grok runs with `--sandbox off --permission-mode bypassPermissions`. For
+explain/show and ordinary BTW, Bro asks it to answer from supplied context
+without investigating or modifying the workspace. **That is a prompt instruction,
+not an enforced access restriction.** Tools, hooks, skills, plugins and MCP may
+remain available. Explain/show start in a temporary directory; BTW uses your
+workspace consistently because native resumed sessions retain their original cwd.
+`--full` invites workspace access rather than imposing conversation-only intent.
+Advisor runs fresh with workspace access. Bro does not blacklist tools merely
+because they are more powerful than the immediate task requires.
+
+BTW resumes using Grok's native session ID. Changing backend or access mode
+starts a fresh Bro thread; IDs are never passed between backends. Bro removes
+its private temporary prompt file, but Grok may retain sessions/logs under its
+own settings. Bro does not copy credentials or change Grok configuration.
+Cancellation targets the managed process group, not independently detached shell
+work or external services. Doctor checks version, not authenticated connectivity.
+
 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 +794,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,30 +844,28 @@ 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.
-- **Usage checks**: `/bro usage` checks your authenticated Agy limits without
-  sending an assistant response or running a model turn.
 - **Setup checks**: `/bro doctor` checks Agy account and model availability
   without sending an assistant response or running a model turn.
 - **Context isolation**: Bro does not add explanations to Pi's conversation
   history, session files, or main-agent context.
-- **Side conversation (`/bro btw`)**: sandboxed by default — the side agent has
-  no project access and runs in a temporary folder. With `--full` it runs in
-  your workspace with auto-approved tools, so it can read and edit files while
-  the main agent is also working; use `--full` only when you want that. The
-  side thread is memory-only and clears when you switch sessions, reload
-  extensions, or quit Pi.
+- **Side conversation (`/bro btw`)**: Agy uses sandbox controls by default;
+  Grok uses conversation-only prompt instructions with normal workspace authority.
+  `--full` explicitly invites workspace access. Bro's thread state clears when
+  you switch sessions, reload extensions, or quit Pi; backend-native sessions
+  can persist independently. Prompt instructions are not access enforcement.
 - **Memory cache**: The latest explanation is stored only in process memory for
   `/bro open`. It clears when you switch Pi sessions, reload extensions, or quit
   Pi.
 - **File safety**: `/bro file` reads only regular files whose resolved path is
-  inside Pi's current workspace, including after resolving symlinks. Bro does
-  not modify them. It runs Agy in sandbox mode inside a temporary empty folder.
-  This reduces project access, but it is not a security boundary. Bro only
-  writes its own user settings file described above.
+  inside Pi's current workspace, including after resolving symlinks. Bro's extractor does
+  not modify them. The selected backend then receives extracted text: Agy uses
+  sandbox controls, Claude tool/config restrictions, and Grok prompt instructions
+  in a temporary directory. Grok retains normal tool authority; a request not
+  to modify files is behavioral, not a technical guarantee.
 - **Web requests**: `/bro url` connects directly to the target website. The site
   sees your IP address and Bro's user agent. Bro sends no browser cookies,
   authorization, or referrer information, and it refuses local, private, and
@@ -830,14 +873,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,11 +888,11 @@ 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
-  (`--dangerously-skip-permissions`). It has real tool access (file reading,
+  (Agy/Claude permission bypass; Grok `--sandbox off --permission-mode bypassPermissions`). It has real tool access (file reading,
   search, command execution). The directive to only advise and leave edits to
   the executor is a **behavioral prompt instruction**, not an enforced sandbox
   or security boundary. Treat its findings as advice to verify before applying.
@@ -867,7 +910,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
@@ -876,7 +919,7 @@ tool before giving it to Bro.
 - Direct webpage fetching does not currently use `HTTP_PROXY`, `HTTPS_PROXY`,
   or other proxy environment variables.
 - `/bro btw` threads are memory-only and do not survive reloads or restarts.
-  The side conversation needs Agy's `--conversation` resume support; sandbox
+  The side conversation uses Agy `--conversation` or Grok `--resume`; conversation-only
   mode caps a turn at 2 minutes and full mode at 10 minutes.
 - `bro_advisor` requires Agy CLI `>=1.1.15` (for `--input-format stream-json`).
   Consultations run directly in the workspace with auto-approved permissions
@@ -906,7 +949,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,