pi-bro 0.25.0 → 0.26.0

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 All notable changes to pi-bro are documented here.
 
+## [0.26.0] - 2026-10-20
+
+### Highlights
+
+- Run any Bro feature on **Pi itself**: a new `pi` backend drives an in-process Pi SDK session with your own Pi models and credentials. No extra CLI to install.
+- `/bro config` is now two steps: pick the backend, then its model. Esc steps back without saving.
+- Pi is the safest review option alongside Claude and Muse: Guided Review gets file-only tools and no shell.
+
+### Breaking
+
+- **pi-bro now requires Pi `>=1.3.0`** (previously `>=0.84.2`). The Pi backend is built on SDK APIs introduced after 0.84.2 — `SettingsManager.getSettings()`, `ModelRuntime.getAllModels()` and seeded `SessionManager.inMemory(cwd, { id }, entries)` (1.0.0), and the `disabledBuiltinExtensions` resource-loader option (1.1.0) — so an older host cannot load the extension at all. Update Pi before upgrading pi-bro; the five CLI backends need no other change. `pi-floor` in CI now pins 1.3.0, the oldest supported version.
+
+### Added
+
+- New `pi` backend for `explain`, `show`, `elevate`, `btw` (restricted and full), `advisor`, and Guided Review. It runs `createAgentSession` inside this process, uses your Pi model registry and configured credentials, and needs no CLI.
+- `/bro config` two-step picker: step 1 chooses the backend (Default for capability overrides, Agy, Claude, Grok, Codex, Muse, Pi), step 2 chooses that backend's model. Esc in step 2 returns to step 1 without saving; a selection only saves on a complete model pick. The Agy family list and the Pi catalog load independently, so `/bro config` works when Agy is offline.
+- Pi model choices come from your configured scoped models (`enabledModels`), falling back to every model with configured credentials. Virtual (`pi-virtual`) models are filtered out and cannot be selected.
+- A `/bro doctor` Pi section that checks the selected physical model, its auth and scope membership, the effective effort, and the curated tool set for each capability, all without a CLI spawn or a live model turn.
+
+### Changed
+
+- Guided Review accepts `pi` as a file-only backend (read/grep/find/ls, no shell) alongside Claude and Muse, and no longer treats it as a shell-capable sandbox. Its session also ignores the captured checkout's `.pi/settings.json`, `.pi/SYSTEM.md` and `.pi/APPEND_SYSTEM.md`, so a PR cannot steer settings or inject system instructions for the review. Host-untrusted workspaces get the same protection.
+- Pi `btw` keeps its side session in memory only (nothing written under `~/.pi/agent/sessions`), resumes it within the same mode and preferences, and drops it on a `/mode` switch or preferences change, matching Agy. An expired or evicted side conversation now fails loudly instead of silently restarting without its history.
+- Settings version 2 accepts `"backend": "pi"` with a `"<provider>/<id>"` model (split on the first `/` only). A malformed custom model ID is reported in the field instead of throwing out of `/bro config`.
+- Pi model choices come from your configured scoped models (`enabledModels`), falling back to every model with configured credentials. The catalog now includes models authenticated by runtime keys, so the picker offers everything a run can actually use. Virtual (`pi-virtual`) models are filtered out and cannot be selected.
+- Pi `btw` and `advisor` runs are raced against the deadline and cancellation latch, so an uncooperative provider can no longer hold the caller or start a model request after its deadline.
+- `/bro doctor` now computes and reports the effective Pi reasoning effort (`requested → effective` only when they differ) instead of claiming a clamp it never checked, and describes both BTW access modes. Scoped-model `:thinking` suffixes are honoured when the Bro effort is `default`.
+- Docs, README, and `/bro help` document the Pi backend and the two-step picker.
+
+## [0.25.1] - 2026-10-19
+
+### Highlights
+
+- `bro_advisor` answers faster: it relies on the session snapshot (including tool calls and outputs) first, and only reads files or runs commands when needed.
+- `bro_advisor` no longer automatically restarts failed consultations up to three times with 5s and 10s waits; it runs once and reports any failure immediately.
+
+### Changed
+
+- `buildAdvisorPrompt` and the `bro_advisor` tool description now instruct the advisor to use the captured session snapshot first and inspect the workspace only when something needed is missing or a key claim is in doubt, instead of requiring a fresh workspace investigation before advising.
+- `runAdvisor` (formerly `runAdvisorWithRetries`) runs a single consultation attempt and surfaces any backend failure, timeout, or cancellation immediately without 5-second and 10-second full-restart retries.
+
 ## [0.25.0] - 2026-10-19
 
 ### Highlights

package/README.md

@@ -61,8 +61,8 @@ File and webpage examples need your own real path or URL; see [how to explain th
 | `/bro show` | **[Show](docs/features/show.md#bro-show).** The last few turns drawn as a shape (call tree, file tree, diff, pseudocode, a sequence diagram, or an HTML layout) instead of prose. |
 | `/bro elevate` or **Ctrl+Shift+E** | **[Elevate](docs/elevate.md).** Discover missing expert considerations, select useful improvements, and rewrite your task without submitting it. Shares BTW backend settings. |
 | `/bro btw` | **[Side questions](docs/features/btw.md#bro-btw-side-conversation).** A separate conversation seeded with recent context, so you can ask without interrupting the agent. ⚠️ [Full-permission mode](#what-leaves-your-machine) can edit files. |
-| `/bro guided-review <PR>` | **[Guided Review](docs/guided-review.md).** An explanation and quality assessment of a GitHub PR, with ranked findings, source evidence and private questions. Claude or Muse is recommended for untrusted PRs. |
-| `bro_advisor` tool | **[Second opinion](docs/features/advisor.md#bro-advisor).** A tool your agent can call mid-task; a fresh backend process investigates and returns advice to the agent. ⚠️ [Runs with permissions bypassed](#what-leaves-your-machine). |
+| `/bro guided-review <PR>` | **[Guided Review](docs/guided-review.md).** An explanation and quality assessment of a GitHub PR, with ranked findings, source evidence and private questions. Claude, Muse, or Pi is recommended for untrusted PRs. |
+| `bro_advisor` tool | **[Second opinion](docs/features/advisor.md#bro-advisor).** A tool your agent can call mid-task; a fresh backend process reviews the session snapshot, can inspect the workspace when needed, and returns advice to the agent. ⚠️ [Runs with permissions bypassed](#what-leaves-your-machine). |
 | `/bro config`, `/bro preferences` | **[Settings](docs/reference/settings.md#settings) and [preferences](docs/user-guide.md#preferences).** Pick the backend, model and effort per feature, and tell Bro how you like answers. |
 
 For help by task, start at the **[docs home](docs/README.md)**; see the [command reference](docs/reference/commands.md) for syntax.
@@ -72,11 +72,10 @@ Guided Review has its own [guide](docs/guided-review.md).
 
 ## Requirements
 
-- Pi `>=0.84.2` (tested on 0.84.2 and 1.2) and Node.js `>=22.19.0`.
+- Pi `>=1.3.0` and Node.js `>=22.19.0`.
 - macOS or Linux. Windows is untested; there, cancelling stops only the
   backend's direct process, not anything it started.
-- At least one backend CLI on your `PATH`, signed in once from your terminal.
-  You only need the one you use:
+- At least one backend on your `PATH`, signed in once from your terminal, **or the built-in Pi backend**. You only need the one you use:
 
 | Backend | CLI | Notes |
 | --- | --- | --- |
@@ -85,9 +84,10 @@ Guided Review has its own [guide](docs/guided-review.md).
 | [Grok Build](https://docs.x.ai/build/overview) | `grok` | Guided Review uses its read-only sandbox (shell-enabled). |
 | [Codex CLI](https://github.com/openai/codex) | `codex` | Guided Review uses its read-only sandbox (shell-enabled). |
 | [Muse Code](https://dev.meta.ai/docs/muse-code) | `muse` | Works for every feature; strict file-only inspection for Guided Review. |
+| **Pi** (in-process) | none | Runs a Pi SDK session inside this process using your Pi models and credentials. No extra install. Restricted features get no tools; Guided Review is file-only; the advisor and full-access BTW get workspace tools. |
 
 - Guided Review also needs Git and an authenticated [`gh`](https://cli.github.com/).
-  Claude or Muse is recommended for untrusted PRs (strict file-only inspection); Codex, Grok and Agy run with shell available under their sandbox, with an advisory.
+  Claude, Muse, or Pi is recommended for untrusted PRs (strict file-only inspection); Codex, Grok and Agy run with shell available under their sandbox, with an advisory.
 - [PiG](docs/pig-compatibility.md) support is experimental.
 
 ## What leaves your machine
@@ -106,11 +106,13 @@ which may keep it under their own policies. Paths below are under
 | Advisor | The agent's system instructions, tool list and whole conversation, including tool calls and results (reasoning and images omitted), plus your steering | Steering in `bro-advisor.md` and the session file |
 
 `/bro url` also connects straight to the website, which sees your IP address.
-Bro runs each CLI as you, with your environment. It never reads or copies Pi's
-provider credentials, but the CLI signs in its own way, which can include API
-keys set in your environment. Nothing Bro produces enters Pi's conversation
-unless you insert it, except advisor answers, which return to the agent as
-tool results.
+Bro runs each CLI as you, with your environment. It never reads or copies an
+external CLI's provider credentials, but a CLI signs in its own way, which can
+include API keys set in your environment. The built-in **Pi** backend is the
+exception: it runs in-process, so it reads your Pi `auth.json` and reuses your
+Pi provider credentials for the model you select. Nothing Bro produces enters
+Pi's conversation unless you insert it, except advisor answers, which return to
+the agent as tool results.
 
 > [!WARNING]
 > These run the backend in your workspace with its permission checks bypassed:

package/docs/features/advisor.md

@@ -24,14 +24,15 @@ presence, and backend compatibility (for Agy, a minimum CLI version with an
   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 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
+  backend** for every consultation. Nothing is resumed or reused across calls.
+- **Snapshot first, workspace tools when needed**: the advisor process has real
   tool access in the workspace with permissions auto-approved — there is no
-  enforced read-only isolation. It is instructed to verify claims itself and
-  return advice, leaving edits to the executor, but that boundary is a
-  behavioral prompt instruction rather than an enforced sandbox constraint, so
-  treat its findings as advice to verify, not a guaranteed hands-off review.
+  enforced read-only isolation. It is instructed to rely on the captured
+  snapshot (including its tool calls and results) first, inspect the workspace
+  only when something is missing or a key claim is in doubt, and return advice
+  while leaving edits to the executor. That boundary is a behavioral prompt
+  instruction rather than an enforced sandbox constraint, so treat its findings
+  as advice to verify, not a guaranteed hands-off review.
 - **Steering**: The advisor reads standing priorities from `~/.pi/agent/bro-advisor.md`
   and session-specific priorities from `/bro advisor-steer`.
   `/bro advisor-steer` opens an editor for one session steering brief — e.g. "quick
@@ -47,24 +48,18 @@ presence, and backend compatibility (for Agy, a minimum CLI version with an
   session file (`bro-advisor-steering`) and is restored on resume or reload. Forking a
   session inherits session steering; edits made after the fork are independent of the
   original branch. Clearing session steering leaves durable steering intact.
-- **Retries**: on an invocation failure (not a completed answer — "I need
-  more evidence" is a normal result, not a failure), Bro retries with the
-  identical snapshot, steering, and question: once after 5 seconds, once more
-  after 10 seconds, then returns the backend's own diagnostic — including a
-  context-length error, verbatim — as the failure. Host-imposed deadlines and
-  cancellation are terminal: neither starts another attempt or a backoff wait.
-  The advisor CLI is asked to stop at 10 minutes; Bro's host deadline is 610
-  seconds plus bounded process cleanup. A CLI-reported error before that host
-  deadline remains an invocation failure and can be retried.
-  Cancelling the tool call skips any pending retry wait.
-- **Progress and provenance**: while an attempt is running, Bro shows the last
+- **Single attempt, no automatic retries**: each consultation runs once (the
+  advisor CLI is asked to stop at 10 minutes; Bro's host deadline is 610
+  seconds plus bounded process cleanup). Any backend failure, timeout, or
+  cancellation is returned immediately — including a context-length error,
+  verbatim — without waiting or restarting the consultation from scratch.
+- **Progress and provenance**: while a consultation is running, Bro shows the last
   thing the advisor actually reported — a tool name or a user-facing response
   line, never hidden reasoning — and how long ago it arrived, e.g. `last
   reported: Read src/app.ts (2s ago)`, or "awaiting first activity" before
   anything arrives. Expanding a running consultation shows up to the last 4
-  reported activity lines; each retry starts the trail over. The returned
-  answer starts with backend, model, effort, attempt count, duration,
-  workspace, steering presence, snapshot size, and known omission/compaction
-  notes; the advisor's complete answer follows unchanged.
+  reported activity lines. The returned answer starts with backend, model,
+  effort, duration, workspace, steering presence, snapshot size, and known
+  omission/compaction notes; the advisor's complete answer follows unchanged.
 - **Model/effort**: resolved the same way as explain/show/btw, through
   `/bro config` (shared default or per-capability override).

package/docs/getting-started.md

@@ -4,7 +4,7 @@ Pi-bro helps you understand agent replies, ask side questions, and review work w
 
 ## 1. Install
 
-You need **Pi**, Node.js 22.19.0 or later, and one supported backend CLI already installed and signed in (Agy, Claude, Grok, Codex, or Muse). See [requirements](../README.md#requirements).
+You need **Pi**, Node.js 22.19.0 or later, and one supported backend already installed and signed in (Agy, Claude, Grok, Codex, or Muse) — or the built-in **Pi** backend, which uses your Pi session's own models and needs no extra CLI. See [requirements](../README.md#requirements).
 
 ```sh
 pi install npm:pi-bro
@@ -44,4 +44,4 @@ See the [docs home](README.md) for detailed workflows.
 
 ## Data and access before you use Bro at work
 
-Bro sends your selected text and some context to the backend CLI and model provider you configure. BTW and the advisor have different access rules; some modes can read or change local files. Read [What leaves your machine](../README.md#what-leaves-your-machine) and the [backend access matrix](reference/data-and-permissions.md#backends-access-and-retention) before using private data. A model prompt saying 'do not access' is not a security boundary.
+Bro sends your selected text and some context to the backend CLI and model provider you configure. BTW and the advisor have different access rules; some modes can read or change local files. The Pi backend runs in-process but still sends the prompt to whichever Pi model provider you select. Read [What leaves your machine](../README.md#what-leaves-your-machine) and the [backend access matrix](reference/data-and-permissions.md#backends-access-and-retention) before using private data. A model prompt saying 'do not access' is not a security boundary.

package/docs/guided-review.md

@@ -6,7 +6,7 @@ The normal journey is: **open a PR → read and investigate → leave when satis
 
 ## Open a review
 
-Requirements: local Pi interactive mode, Git, authenticated GitHub CLI (`gh`), and a configured review backend (Claude or Muse is recommended for untrusted PRs). Run `gh auth status` to check GitHub authentication; `/bro doctor` checks Bro's selected backend setup and shows an advisory when the review backend uses a shell-capable sandbox, without proving GitHub access or model connectivity.
+Requirements: local Pi interactive mode, Git, authenticated GitHub CLI (`gh`), and a configured review backend (Claude, Muse, or Pi is recommended for untrusted PRs). Run `gh auth status` to check GitHub authentication; `/bro doctor` checks Bro's selected backend setup and shows an advisory when the review backend uses a shell-capable sandbox, without proving GitHub access or model connectivity.
 
 ```text
 /bro guided-review https://github.com/OWNER/REPO/pull/123
@@ -83,9 +83,9 @@ Use Overview → Regenerate guide only when you want a fresh explanation/assessm
 
 ## Access, privacy and storage
 
-Review never runs with full-access or bypass flags. **Claude and Muse provide strict file-only inspection** and are recommended for untrusted PRs: Claude runs with `--restricted`, Read/Grep/Glob only, `dontAsk`, safe mode and no MCP; Muse disables write, shell and web tools, foreign personal context and native session logs, without trusting repository rules. No model-run project tests, commands, Git or network tools are available on Claude or Muse.
+Review never runs with full-access or bypass flags. **Claude, Muse, and Pi provide strict file-only inspection** and are recommended for untrusted PRs: Claude runs with `--restricted`, Read/Grep/Glob only, `dontAsk`, safe mode and no MCP; Muse disables write, shell and web tools, foreign personal context and native session logs, without trusting repository rules; Pi runs in-process with `read/grep/find/ls` only, no shell, and an isolated session. No model-run project tests, commands, Git or network tools are available on Claude, Muse, or Pi.
 
-**Codex, Grok and Agy run with shell available inside their own sandbox**, and each sandbox is different: Codex and Grok apply a read-only sandbox (`codex exec --sandbox read-only --ephemeral`, `grok --sandbox read-only --permission-mode dontAsk`), while Agy's `--sandbox` only restricts terminal commands and still lets them write inside the project. All three inspect the captured checkout with a 10-minute review deadline, and **none is shell-free**. When one of these backends is selected for review, Bro shows an advisory during acquisition, in the live review workspace, and in `/bro doctor` (as a non-fatal informational note). Set the **review** override to Claude or Muse in `/bro config` for untrusted PRs; saved reviews remain readable with any backend. Unsupported/older CLI flags fail visibly; there is no bypass fallback.
+**Codex, Grok and Agy run with shell available inside their own sandbox**, and each sandbox is different: Codex and Grok apply a read-only sandbox (`codex exec --sandbox read-only --ephemeral`, `grok --sandbox read-only --permission-mode dontAsk`), while Agy's `--sandbox` only restricts terminal commands and still lets them write inside the project. All three inspect the captured checkout with a 10-minute review deadline, and **none is shell-free**. When one of these backends is selected for review, Bro shows an advisory during acquisition, in the live review workspace, and in `/bro doctor` (as a non-fatal informational note). Set the **review** override to Claude, Muse, or Pi in `/bro config` for untrusted PRs; saved reviews remain readable with any backend. Unsupported/older CLI flags fail visibly; there is no bypass fallback.
 
 Captured evidence is read from pinned Git blobs, so a shell-capable backend that writes inside the checkout cannot alter the code shown as evidence — but it can still change what it later reads, so treat very large changes with suspicion when using Agy.
 
@@ -108,7 +108,7 @@ One open writer per review is supported within a Pi process. Concurrent editing
 | Problem | What to do |
 | --- | --- |
 | GitHub unavailable when reopening | Use bare `/bro guided-review` to choose a saved review; the picker does not fetch |
-| Sandboxed shell review backend (Codex, Grok, Agy) | Advisory shown; choose Claude or Muse in `/bro config` for strict file-only inspection on untrusted PRs |
+| Sandboxed shell review backend (Codex, Grok, Agy) | Advisory shown; choose Claude, Muse, or Pi in `/bro config` for strict file-only inspection on untrusted PRs |
 | Git/gh authentication or fetch error | Read the acquisition error; check Git/`gh auth status`; retry explicitly |
 | Invalid/failed preparation | Changed files remain available; use Prepare guide to retry when ready for another call |
 | Failed regeneration | Current guide is kept; retry only if you want another call |

package/docs/reference/data-and-permissions.md

@@ -9,6 +9,10 @@ credentials, and does not copy credentials or rewrite backend configuration.
 Each backend and your model provider may retain sessions, logs, and request
 data under their own settings and policies.
 
+The **Pi** backend is the in-process exception: it does not spawn a CLI. It runs a
+Pi SDK session inside the host process using your own Pi model registry and its
+configured credentials, so it uses the same account route as your Pi session.
+
 | | Explain / show | BTW conversation-only | BTW full permission | Advisor | Guided Review |
 | --- | --- | --- | --- | --- | --- |
 | **Agy** | Temporary directory, Agy sandbox | Temporary directory, Agy sandbox | Workspace, permissions bypassed | Fresh workspace process, permissions bypassed | Captured checkout, Agy sandbox (shell and in-project writes allowed; advisory) |
@@ -16,6 +20,7 @@ data under their own settings and policies.
 | **Grok** | Temporary directory, **prompt instruction only** | Workspace, **prompt instruction only** | Workspace, permissions bypassed | Fresh workspace process, permissions bypassed | Captured checkout, read-only sandbox (shell-enabled; advisory) |
 | **Codex** | Scratch directory, read-only sandbox, ephemeral session | Workspace, read-only sandbox | Workspace, approvals and sandbox bypassed | Fresh workspace process, approvals and sandbox bypassed | Captured checkout, read-only sandbox, ephemeral (shell-enabled; advisory) |
 | **Muse** | Scratch directory, approval/write/shell disabled, no session log | Workspace, approval/write/shell disabled | Workspace, permissions bypassed (`--yolo`) | Fresh workspace process, permissions bypassed (`--yolo`) | Captured checkout; writes/shell/web disabled, no session log |
+| **Pi** | No tools at all (isolated in-process session) | No tools at all | Workspace, read/bash/edit/write (no nested delegation or MCP) | Workspace, read/bash/edit/write (no nested delegation or MCP) | Captured checkout, read/grep/find/ls only (no shell) |
 
 - Grok always runs explain, show, btw and the advisor with its sandbox off and
   permissions bypassed; its tools, hooks, skills, plugins, and MCP may remain
@@ -41,7 +46,15 @@ data under their own settings and policies.
   including across `/mode` switches. An Agy conversation stays bound to the
   workspace it started in, so after a `/mode` switch — or whenever a thread
   has turns but no native session ID — Bro starts a fresh native session
-  seeded with the main-session context and every earlier turn.
+  seeded with the main-session context and every earlier turn. Pi keeps its side
+  session in memory only (nothing is written under `~/.pi/agent/sessions`) and,
+  like Agy, drops it on a `/mode` switch.
+- Pi runs in-process with no CLI, no extensions, no skills, no prompt templates,
+  no context files, MCP or codemode, and auto-retry and compaction disabled. Its
+  Guided Review uses read/grep/find/ls only and cannot run shell commands, and it
+  ignores the captured checkout's `.pi/settings.json` so an untrusted PR cannot
+  steer the reviewing session. In restricted explain/show/elevate/btw it has no
+  tools at all.
 - Cancellation, deadlines, and invalid output streams stop the backend's
   process group on POSIX, escalating after a five-second grace period. On
   Windows only the direct child is targeted. Detached shell work or external
@@ -53,7 +66,7 @@ data under their own settings and policies.
 When resolving backend, model, and reasoning effort:
 1. **Per-capability override**: `overrides.<capability>` (`explain`, `show`, `btw`, `advisor`, or `review`) pins that capability's complete selection.
 2. **Shared default**: otherwise the capability inherits `default` (root `model`/`effort` in older flat files).
-3. **Agy catalog normalization**: for Agy selections, Bro maps suffixed variant IDs and handles fixed-effort models.
+3. **Backend-specific normalization**: Agy selections are mapped against its installed catalog (suffixed variants, fixed-effort models); Pi selections are `<provider>/<id>` physical models resolved against your Pi registry.
 4. **Initial file creation only**: `PI_BRO_MODEL` has no effect once the settings file exists.
 
 When resolving turn count for `/bro show`:
@@ -80,7 +93,7 @@ When shaping an answer, each part has one owner:
   seeded main-session conversation text (plus earlier turns when a native
   session is reseeded) to the selected backend. In full permission mode the
   side agent can additionally read and edit the workspace.
-- **Guided Review requests**: PR identity/description, captured diff, relevant private discussion and preferences go to the selected backend, which can inspect captured files. Main-session context is not attached. Claude (`--restricted`, file tools only) and Muse (write/shell/web disabled) use strict file-only inspection and are recommended for untrusted PRs. Codex and Grok inspect the captured checkout under a read-only sandbox; Agy's `--sandbox` still allows in-project writes. All three run shell commands and show an advisory. Prompt injection can still corrupt conclusions or reveal captured content to the provider; this is not a general confidentiality guarantee. See [Guided Review access and storage](../guided-review.md#access-privacy-and-storage).
+- **Guided Review requests**: PR identity/description, captured diff, relevant private discussion and preferences go to the selected backend, which can inspect captured files. Main-session context is not attached. Claude (`--restricted`, file tools only), Muse (write/shell/web disabled), and Pi (`read/grep/find/ls` only, in-process) use strict file-only inspection and are recommended for untrusted PRs. Codex and Grok inspect the captured checkout under a read-only sandbox; Agy's `--sandbox` still allows in-project writes. All three run shell commands and show an advisory. Prompt injection can still corrupt conclusions or reveal captured content to the provider; this is not a general confidentiality guarantee. See [Guided Review access and storage](../guided-review.md#access-privacy-and-storage).
 - **Preferences**: `bro-preferences.md` is sent with every explain, Show,
   BTW, Elevate, and Guided Review request to the selected backend. It is never sent to the advisor or
   to Pi's main model.

package/docs/reference/settings.md

@@ -32,7 +32,8 @@ Settings live in this user-editable file, created when the extension loads
   "showTurns": 1,
   "overrides": {
     "explain": { "backend": "claude", "model": "sonnet", "effort": "medium" },
-    "advisor": { "backend": "grok", "model": "grok-4.7", "effort": "high" }
+    "advisor": { "backend": "grok", "model": "grok-4.7", "effort": "high" },
+    "review": { "backend": "pi", "model": "anthropic/claude-sonnet-4-5", "effort": "high" }
   }
 }
 ```
@@ -47,7 +48,11 @@ Bro reads the file again before each request, so manual edits apply next time.
   model decide). Agy selections are normalized against Agy's installed model
   catalog. Claude, Grok, Codex, and Muse accept seeded or custom model IDs; a model/effort
   combination the account does not support fails with the backend's own error
-  instead of silently falling back.
+  instead of silently falling back. **Pi** selections are a `"<provider>/<id>"` pair
+  from your Pi model catalog, chosen from your configured scoped models
+  (`enabledModels`, falling back to every model with configured credentials).
+  Explicit Pi efforts are clamped to the model's supported reasoning levels; the
+  picker's own step 1 chooses the backend and step 2 the model.
 - `mode` is `brief`, `balanced` (the default), or `faithful`. `showTurns` is
   the default number of turns `/bro show` draws (default 1); `/bro show
   <n-turns>` overrides it for one run.

package/docs/reference/troubleshooting.md

@@ -16,6 +16,11 @@ feature. Failed checks explain what to fix.
 - **Codex**: installed version and configured authentication.
 - **Muse**: installed version only; authentication and connectivity are not
   verified.
+- **Pi**: physical model catalog, configured authentication, scope membership,
+  effective reasoning effort, and each feature's tool set. Uses the in-process
+  SDK with host registrations and runtime credentials plus current on-disk
+  models/auth; workspace settings follow the host's trust decision. No CLI or
+  connectivity probe runs.
 
 Doctor never sends source text or runs a model completion. A successful check
 confirms the setup but cannot guarantee that a later provider request will

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-bro",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "A sidekick for you and your Pi agent: plain-language explanations, side questions, diagrams, PR review and second opinions, without cluttering the agent's context.",
   "type": "module",
   "license": "MIT",
@@ -98,13 +98,15 @@
     "image": "https://raw.githubusercontent.com/tranhoangnguyen03/pi-bro/main/docs/images/social-preview.png"
   },
   "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "1.2.0",
-    "@earendil-works/pi-tui": "1.2.0",
+    "@earendil-works/pi-ai": "1.3.0",
+    "@earendil-works/pi-coding-agent": "1.3.0",
+    "@earendil-works/pi-tui": "1.3.0",
     "@types/node": "^24.0.0",
     "typebox": "1.3.27",
     "typescript": "6.0.3"