pi-bro 0.24.0 → 0.25.1

package/docs/features/advisor.md

@@ -0,0 +1,65 @@
+# Agent second opinions (Advisor)
+
+[Docs home](../README.md) · [All commands](../reference/commands.md) · [Safety and permissions](../reference/data-and-permissions.md)
+
+## Bro advisor
+
+`bro_advisor` is a tool the **executor agent** — not you — can voluntarily
+call mid-task for a second opinion. Unlike `/bro btw`, which is a side
+conversation for you, `bro_advisor` is a tool for the model you're working
+with; it shows up as a normal tool call/result in the transcript, not a
+modal. It is registered like any other tool when the extension loads and has
+no on/off switch of its own — whether the executor can actually call it
+depends entirely on this host's own tool restrictions.
+
+`/bro advisor` is a quick notice of whether `bro_advisor` is available right
+now, pointing at `/bro config`, `/bro advisor-steer`, and `/bro doctor`.
+`/bro doctor` has the full diagnostic: whether this host exposes and
+activates `bro_advisor`, its resolved backend/model/effort, steering
+presence, and backend compatibility (for Agy, a minimum CLI version with an
+`agy update` action when it is too old).
+
+- **Automatic context, no prep needed**: the executor does not need to assemble
+  a 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 process of the selected
+  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 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
+  prototype; keep A and B careful, everything else minimal". Session steering takes
+  precedence over durable standing defaults where they conflict.
+  **Ctrl+S** saves and keeps the editor open; **Enter** or **Shift+Enter** inserts
+  a newline; **Ctrl+K** clears both the saved session brief and draft while staying open;
+  **Ctrl+C** copies the entire current draft, including unsaved edits; and **Esc**
+  closes without saving unsaved edits. Neither steering source is **ever added to Pi's
+  conversation or sent to the main model** — the advisor is the only thing that reads them.
+- **Persistence**: standing defaults persist across all sessions in `~/.pi/agent/bro-advisor.md`.
+  The session steering brief persists with the Pi session as custom extension data in the
+  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.
+- **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. 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/features/btw.md

@@ -0,0 +1,51 @@
+# Side questions (BTW)
+
+[Docs home](../README.md) · [All commands](../reference/commands.md) · [Safety and permissions](../reference/data-and-permissions.md)
+
+## 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 the
+selected backend and never adds anything to Pi's conversation unless you
+explicitly insert it into the editor. Bro writes for a tired reader: the point
+first, in plain words, at a length that fits the question, in the language you
+asked in.
+
+- `/bro btw <question>` asks immediately; `/bro btw` opens an empty thread.
+  Reopening keeps the thread and its mode.
+- **Two modes, toggled with `/mode`**: a new thread starts
+  **conversation-only**; type `/mode` in the modal to switch to **full
+  permission** (read and edit the workspace, run commands) and again to switch
+  back. The conversation is kept across switches. How conversation-only is
+  enforced depends on the backend — see
+  [Backends: access and retention](../reference/data-and-permissions.md#backends-access-and-retention).
+  **Conversation-only does not mean a hard sandbox on every backend:** Grok
+  relies on an instruction; Codex and Muse can retain some read, shell, or
+  network abilities under their own restricted settings. Do not send secrets
+  on the assumption that the model cannot access anything else.
+- Every new or cleared thread is seeded with up to the last 8 turns of
+  main-session user/assistant conversation text (40,000 characters max, with a
+  truncation notice). Later turns continue the backend's native session; in
+  full permission mode the side agent can also read the repo itself.
+- **In the modal**: type a question and press Enter (empty Enter re-asks the
+  last question). Composer actions trigger only on these exact commands:
+  - `/mode`: toggles conversation-only / full permission, keeping the thread
+  - `/copy`: copies the latest answer to the system clipboard
+  - `/copy-all`: copies the full thread to the system clipboard
+  - `/insert`: inserts the latest answer into the main editor without submitting
+  - `/insert-all`: inserts the full thread into the main editor without submitting
+  - `/retry`: re-asks the last question (empty Enter does the same)
+  - `/clear`: resets the thread
+
+  `/insert` and `/insert-all` never replace an existing main-editor draft:
+  edit or clear it first. Any other text, including other slash-prefixed input
+  such as `/send`, is sent as a question. Esc closes the modal and stops a
+  running turn; the thread is kept. The view follows the newest text while you
+  are at the bottom; scroll up to read earlier turns. The header shows the model and reasoning effort the latest
+  turn used (`default` when the model's own effort applies) and the current
+  mode.
+- A turn is capped at 2 minutes in conversation-only mode and 10 minutes in
+  full permission mode.
+- Bro's thread lives in memory only — it clears when you switch Pi sessions,
+  reload extensions, or quit Pi. Changing the BTW backend starts a fresh
+  thread; native session IDs never cross backends.

package/docs/features/explain.md

@@ -0,0 +1,92 @@
+# Explain text, files and webpages
+
+[Docs home](../README.md) · [All commands](../reference/commands.md) · [Safety and permissions](../reference/data-and-permissions.md)
+
+## Explanation modes
+
+Bro treats quoted source as data and asks the model to ignore embedded
+instructions found in it. This is a prompt instruction, not an enforced security
+boundary. Bro preserves the source's language (unless your [preferences](../reference/settings.md#preferences) name another), and avoids
+adding facts, advice, or conclusions in every mode. Choose
+a persistent mode with `/bro mode`, or press **M** in an explanation to try the
+next mode without saving it:
+
+- **`brief`**: Uses the original audience-led ELI-simpleton prompt with no fixed
+  word target.
+- **`balanced`**: The default. Keeps important details, conditions, warnings,
+  context, code, and formatting while trimming fluff and repetition.
+- **`faithful`**: Simplifies the language while preserving every claim,
+  qualification, warning, number, command, code block, and formatting choice.
+
+### Modal controls
+
+- **Mouse wheel / trackpad**: Scroll in regular or fullscreen mode
+- **↑ / ↓**: Scroll in any mode
+- **PgUp / PgDn**: Scroll a page at a time (also in btw)
+- **C**: Copy the complete explanation
+- **R**: Simplify the captured source again in the mode shown, or run the
+  current Doctor check again
+- **M**: Re-simplify the captured source in the next mode (brief → balanced →
+  faithful → brief). It applies to this explanation only and does not change
+  the mode saved by `/bro mode`; pressing it again while Bro is working skips
+  ahead
+- **O**: Open the diagram (an HTML layout or a rendered sequence 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), followed by the
+explanation mode, and `prefs` when your [preferences](../reference/settings.md#preferences) shaped the
+result; `/bro open` keeps the original labels, mode, and tag.
+
+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.
+
+## Explain pasted text
+
+Paste text directly after the command:
+
+```text
+/bro text OAuth refresh tokens are rotated after every successful use.
+```
+
+Bro explains the pasted text instead of the latest assistant reply. With no text
+after `/bro text`, it falls back to the latest completed reply. Press **R**
+to simplify the same captured text again.
+
+## Explain a document
+
+Use a path relative to Pi's current workspace, or an absolute path inside it:
+
+```text
+/bro file "docs/incident review.pdf"
+```
+
+Paths may contain spaces; matching single or double quotes are also accepted.
+Bro extracts text locally, then sends that text through the same explanation
+flow used by `/bro`. Pressing **R** retries the extracted snapshot; running a
+new `/bro file <path>` command reads the file again.
+
+Files are limited to 10 MiB and 100,000 extracted characters. Scanned PDFs are
+not supported because Bro does not perform OCR.
+
+## Explain a webpage
+
+Pass one public HTTP or HTTPS page:
+
+```text
+/bro url https://example.com/complicated-article
+```
+
+Bro fetches the page, extracts its main readable text locally, and sends only
+that text through the existing explanation flow. The completed modal shows the
+final website and page title. Pressing **R** retries the captured page without
+fetching again; running a new `/bro url <url>` command fetches a fresh copy.
+
+The first version is intentionally limited to one public, text-based page. It
+does not use browser cookies, sign in, run page JavaScript, bypass paywalls or
+bot protection, load complete discussion threads, follow pagination, or
+understand images and video. Pages that depend on those features may fail.
+
+If Bro cannot read a page, copy its content into a `.txt` or `.md` file, or save
+it as a PDF, then use `/bro file <path>`.

package/docs/features/show.md

@@ -0,0 +1,154 @@
+# Visualize a session (Show)
+
+[Docs home](../README.md) · [All commands](../reference/commands.md) · [Safety and permissions](../reference/data-and-permissions.md)
+
+## Bro show
+
+Where the explanation modes rewrite dense prose in simpler words, `/bro show`
+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 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 do not affect it. Your
+[preferences](../reference/settings.md#preferences) can change only its wording and language, never
+which shapes it draws or its rules.
+
+Because the draw model only ever sees conversation text, its shapes reflect
+what was *reported* in the conversation — what the assistant said it did or
+found — not an independent check against the actual code or system state.
+
+Shapes are terminal-first: pseudocode, call trees, file trees, component
+trees, diffs, and types and signatures. Bro picks the shape from what
+happened in the session; there is no flag to request a specific one. When the source has no code structure
+to draw, Bro falls back to a plain outline instead of forcing a diagram. A
+reply that ends in one self-contained HTML block — layout, a state comparison,
+anything where position itself carries meaning — is written to a file and
+opened with **O**.
+
+When the turns describe messages passing among three or more participants in
+a set order (for example browser → API → database), a reply can instead end in
+one Mermaid `sequenceDiagram`. The modal keeps its source visible with
+`[Diagram saved — press O to render]`; **O** opens a page that draws it with
+the Mermaid copy bundled in Bro. Any other Mermaid stays plain text.
+
+Pressing **R** redraws the same captured turns; running `/bro show` again
+captures the latest turns afresh. `/bro show <n-turns>` overrides the default turn
+count for a single run.
+
+Add a query to steer what the shapes focus on, either after a turn count or on
+its own: `/bro show what changed in the auth flow`, or `/bro show 3 what
+changed in the auth flow`. The query is used as a lens on the captured turns,
+not as additional evidence, and its casing is preserved as typed. Pressing
+**R** retries with the same turn count and query.
+
+Any leading whitespace-delimited word that looks like a number is treated as the
+requested turn count: for example, `/bro show 3 what changed` captures 3 turns
+and steers on "what changed", while `/bro show 404 handler` parses "404" as the
+turn count and "handler" as the steering query. To steer on a phrase that starts
+with digits while choosing a turn count, specify the turn count explicitly
+first: `/bro show 1 404 handler` captures 1 turn and steers on "404 handler".
+If the first word is not a number, the whole input is treated as the steering
+query using the saved `showTurns` default.
+
+### A slow session-create, traced
+
+The agent followed a two-second delay from the handler down to the worker.
+`/bro show` drew the chain:
+
+```text
+handleCreateSession(req)
+├── validateRequest(req)
+├── SessionStore.insert(req.body)
+└── publish('session.created')
+    └── AgentWorker.run(sessionId)
+        ├── loadContext(sessionId)
+        ├── callModel(context)
+        └── persistResult(sessionId, result)
+```
+
+### The shape of code before it exists
+
+A design discussion agreed on the data model ahead of implementation. `/bro
+show` kept just the shape:
+
+```typescript
+interface Item { id: ItemId; parentId: ItemId | null }
+interface Cursor { position: ItemId; direction: 'up' | 'down' }
+function resolveTarget(items: Item[], cursor: Cursor): ItemId | null
+```
+
+### A layout that collapses at narrow widths
+
+Text can't show a before/after layout change at a glance, so Bro ends with one
+self-contained HTML block and **O** opens it (the terminal first shows
+`[HTML diagram saved — press O to open]`):
+
+<p align="center">
+  <a href="https://raw.githubusercontent.com/tranhoangnguyen03/pi-bro/main/docs/images/bro-show-layout.png">
+    <img alt="A before/after dashboard grid" src="https://raw.githubusercontent.com/tranhoangnguyen03/pi-bro/main/docs/images/bro-show-layout.png" width="720">
+  </a>
+</p>
+
+<details>
+<summary><strong>More shapes</strong></summary>
+
+**Diff** — what changed in the save handler:
+
+```diff
+ on(save)
+-  write content
++  if content is unchanged
++    return cached result
++  write new content
++  invalidate cache
+```
+
+**File layout** — where everything lives, for a refactor:
+
+```text
+src/
+├── commands/           # user intents
+│   ├── registry.ts
+│   └── show-me.ts
+├── sessions/           # state and lifecycle
+│   ├── events.ts
+│   ├── store.ts
+│   └── worker.ts
+├── transport/          # API
+│   ├── client.ts
+│   └── stream.ts
+└── config.ts           # root config
+```
+
+**Component tree** — what the session page renders:
+
+```text
+SessionPage (apps/example/src/routes/session.tsx)
+├── [hook] useSessionEvents
+├── SessionToolbar (packages/ui)
+│   └── RunSkillButton
+└── SessionTimeline (packages/ui)
+    └── SkillResultCard
+```
+
+**Pseudocode** — how scroll capture and restore work:
+
+```text
+capture(blocks, targetRect, scrollRect) -> Snapshot:
+  target = focusedBlock ?? firstBlockIntersectingViewportTop(blocks)
+  anchor = wholeBlockAnchor(blocks, target)
+  offset = targetRect.top - scrollRect.top
+  return { anchor, offset, scrollTop, revision + 1 }
+
+restore(snapshot, blocks) -> number:
+  placement = resolveAnchor(blocks, snapshot.anchor)
+  if placement: return scrollRect.top + targetRect.top - snapshot.offset
+  return snapshot.scrollTop
+```
+
+</details>
+
+Prose in, outline out: a purely conversational session with no code to draw
+degrades to a plain outline of the discussion — never a forced diagram.

package/docs/getting-started.md

@@ -0,0 +1,47 @@
+# Getting started with Pi-bro
+
+Pi-bro helps you understand agent replies, ask side questions, and review work without filling your main Pi conversation.
+
+## 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).
+
+```sh
+pi install npm:pi-bro
+```
+
+Restart Pi (or run `/reload`). Then run:
+
+```text
+/bro doctor
+```
+
+**Expected:** A diagnostic view shows your selected backend, model, and any setup problems. This check does not prove that a live provider request will succeed. If it fails, [check your setup](reference/troubleshooting.md#check-your-setup).
+
+## 2. Get your first result
+
+Copy this complete command into Pi:
+
+```text
+/bro text A request limit means a service allows only a certain number of calls in a given time.
+```
+
+**Expected:** A Bro window opens and explains the sentence in simpler words. The exact answer depends on the backend. Use the arrow keys to scroll, **C** to copy, or **Esc** to close. Bro doesn't insert this result into your main agent's context.
+
+This step makes a **real model call**, which may use your backend account's quota or incur charges.
+
+## 3. Try the next useful command
+
+| I want to… | Command |
+| --- | --- |
+| Understand the last agent answer | `/bro` (after the main agent has replied) |
+| Ask a side question | `/bro btw What is a race condition?` |
+| Visualize what we discussed | `/bro show` (after at least one user turn) |
+| Explain a file in my workspace | `/bro file docs/my-report.md` (**replace with an existing path**) |
+| Explain an actual public webpage | `/bro url https://your-public-page.example` (**replace with a real URL**) |
+
+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.

package/docs/pig-compatibility.md

@@ -22,6 +22,7 @@ Bro follows the host's `getAgentDir()`: normally `~/.pi/agent` on Pi and `~/.pig
 
 - **PiG 0.3.0 RPC does not enforce `--exclude-tools`.** Excluded tools may remain active and reach provider requests. This is not a sandbox boundary. Use an explicit `--tools` allowlist instead; do not rely on `/bro doctor` to prove exclusion. Bro does not mask this defect by falsely reporting an active tool as unavailable.
 - The smoke suite retains Pi's strict exclusion assertion. The PiG lane has an explicit version-specific expected failure; a changed result fails the lane so the exception must be reviewed/removed.
+- Elevate is not yet qualified end-to-end on PiG. Interactive behavior, keyboard shortcut delivery and guarded editor insertion must be checked on PiG before claiming support.
 - Guided Review currently targets local Pi interactive mode. Its capture/reading/question/regeneration journey is not qualified on PiG or RPC/Desktop; existing Bro PiG checks do not establish review support. See [current review scope](guided-review.md#not-available-yet).
 - Mouse-wheel forwarding is not qualified; use keyboard scrolling.
 - Remote/SSH OSC 52 clipboard forwarding is not qualified. Local clipboard behavior depends on the host and installed platform utilities.

package/docs/reference/commands.md

@@ -0,0 +1,50 @@
+# Command reference
+
+[Docs home](../README.md) · [All commands](commands.md) · [Safety and permissions](data-and-permissions.md)
+
+## What Bro can explain
+
+| Source | Command | What Bro does |
+| --- | --- | --- |
+| Latest assistant reply | `/bro` | Explains the latest completed reply without adding the result to the conversation. |
+| Pasted text | `/bro text <text>` | Explains text supplied directly in the command. |
+| Local document | `/bro file <path>` | Extracts text from a workspace-local Markdown, text, PDF, or DOCX file. |
+| Public webpage | `/bro url <url>` | Fetches one public HTML page and extracts its main readable content. |
+| Recent session turns | `/bro show` | Draws the last turns' conversation text as shapes instead of prose (tool calls, tool results, reasoning, and images are omitted). |
+| Any of the above, auto-detected | `/bro <input>` | Routes a lone URL to the webpage reader, an existing workspace file with a supported extension to the document reader, and anything else to pasted text. |
+
+Pressing **R** simplifies the captured source again in the mode shown, and
+**M** re-simplifies it in the next mode. These commands capture a
+new source: `/bro text`, `/bro file`, `/bro url`, and `/bro show`. Giving `/bro` a URL, path, or
+text directly captures a new source the same way.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `/bro`, `/bro simplify`, or `/bro text` | Explain the latest completed assistant response. |
+| `/bro text <text>` | Explain pasted text. |
+| `/bro <input>` | Explain it directly: a lone URL runs the webpage reader, an existing workspace file with a supported extension runs the document reader, and anything else is pasted text. A quoted path with spaces is routed too when the file exists. |
+| `/bro file <path>` | Explain a workspace-local `.md`, `.markdown`, `.txt`, `.pdf`, or `.docx` file. |
+| `/bro url <url>` | Explain one public, text-based webpage. |
+| `/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, preferences, and each selected backend, with the effective backend/model/effort per feature. |
+| `/bro mode [brief\|balanced\|faithful]` | View or choose the explanation mode. |
+| `/bro preferences` | View or edit what Bro knows about you and how you like answers; see [Preferences](settings.md#preferences). |
+| `/bro config` | Open settings for the shared backend/model/effort, explain mode, show turns, and per-capability (explain/show/btw/advisor/review) overrides. |
+| `/bro guided-review <PR number or URL>` | Automatically explain and assess a captured PR in local Pi, with source evidence and optional private questions. Opening the same PR restores its saved review. |
+| `/bro guided-review` | List saved reviews; `resume` is an alias. |
+| `/bro elevate [request]` | Improve an assignment before execution. Discover up to five gaps, choose useful findings, and insert a revised request without submitting it. **Ctrl+Shift+E** can use your unsent draft. See [Elevate](../elevate.md). |
+| `/bro btw [question]` | Open a side conversation in a modal, seeded with recent main-session context. Starts conversation-only; type `/mode` inside to toggle full permission (read and edit the workspace) without losing the thread. |
+| `/bro advisor` | Quick notice of whether the executor's `bro_advisor` tool is available right now, pointing at `/bro config`, `/bro advisor-steer`, and `/bro doctor`. |
+| `/bro advisor-steer` | View, edit, save, or clear the one persistent steering brief the advisor always sees. |
+| `/bro help` | Open the built-in quick reference. |
+
+Giving `/bro` the input directly works the same way:
+
+```text
+/bro https://example.com/article
+/bro docs/report.pdf
+/bro any other text is explained as pasted text
+```

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

@@ -0,0 +1,130 @@
+# Backend access, privacy and retention
+
+[Docs home](../README.md) · [All commands](commands.md) · [Safety and permissions](data-and-permissions.md)
+
+## Backends: access and retention
+
+Bro uses each CLI's own account and billing route, never Pi provider
+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.
+
+| | 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) |
+| **Claude Code** | Scratch directory, tools/MCP/skills disabled, no session persistence | Workspace, tools disabled | Workspace, permissions bypassed | Fresh workspace process, permissions bypassed | Restricted Read/Grep/Glob only; confined checkout, no persistence |
+| **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 |
+
+- 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
+  available. "Answer only from the supplied context" is a request, not an
+  enforced restriction. Guided Review is the exception: it runs with
+  `--sandbox read-only --permission-mode dontAsk` but still executes shell
+  commands inside that sandbox.
+- Codex's read-only sandbox is not a tool-free mode: workspace reads and
+  sandboxed commands remain available, including for Guided Review. Bro does
+  not disable configured MCP servers or web search; their access is governed
+  by Codex configuration.
+- Agy's Guided Review runs under `--sandbox`, which restricts terminal
+  commands but still permits writes inside the project; it has no file-only
+  tool filter.
+- Muse's restricted mode disables write and shell tools and approval prompts,
+  not all tools: workspace reads and web tools remain available without approval.
+  It is not a tool-free or network-isolated mode.
+- Claude's restrictions are tool/configuration settings (with safe mode), not
+  an OS sandbox; built-in and managed Claude behavior can remain. Running a
+  permission-bypassing mode as root may be rejected by Claude.
+- BTW continues natively: Agy by conversation ID, Claude and Grok by
+  `--resume`, Codex by `resume`, and Muse by `--session-id` of the same session,
+  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.
+- 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
+  services a backend started are not contained. Bro removes its private
+  temporary prompt files.
+
+### Configuration precedence
+
+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.
+4. **Initial file creation only**: `PI_BRO_MODEL` has no effect once the settings file exists.
+
+When resolving turn count for `/bro show`:
+1. **Command argument**: an explicit count like `/bro show 3` or `/bro show 1 query` overrides for that run.
+2. **Saved setting**: `showTurns` (defaults to 1).
+
+When shaping an answer, each part has one owner:
+
+| Part | Decided by |
+| --- | --- |
+| Bro's source rules: quoted source treated as data, no added facts, Show's traceability rules, BTW access mode | Built in; nothing overrides them |
+| How much of the source an explanation keeps | The mode: **M** for one explanation, otherwise the saved `mode` |
+| What a Show drawing focuses on | The steering query |
+| Who the answer is for: wording, tone, depth, and answer language | Your [preferences](settings.md#preferences), otherwise Bro's built-in defaults |
+
+## Privacy and safety
+
+- **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 the selected backend and its configured model provider.
+- **Elevate requests**: `/bro elevate` sends your objective, preferences, and all user/assistant text on the current branch by default, without a fixed history cap. Its visible Context switch can include tool-call arguments and text results (Full), potentially including sensitive file contents or command output. Both modes exclude hidden reasoning and image binaries. Only explicit Retry after a context-overload error trims older history; the UI discloses reduced context. Its optional rewrite call includes only approved findings. It makes fresh restricted calls through the BTW model setting, but a backend's restricted mode is not a universal file/network sandbox (Grok restrictions are prompt-only). It does not insert or submit anything to Pi unless you approve insertion. In the terminal, insertion can replace the draft Elevate was opened on, if it is unchanged; an explicit `/bro elevate <request>` requires an empty editor. See the [Elevate guide](../elevate.md).
+- **Side conversation requests**: `/bro btw` sends your side questions and the
+  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).
+- **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.
+- **Advisor requests**: `bro_advisor` sends the executor agent's system
+  instructions, active tool list (excluding `bro_advisor`), ordered
+  conversation history including tool calls and tool results (unlike Show,
+  which omits them), your steering brief, and the executor's optional question
+  to the selected backend. Reasoning and image bodies are omitted with explicit
+  markers (`[reasoning omitted]`, `[image omitted]`). The advisor process runs
+  in your workspace with auto-approved permissions; its instruction to only
+  advise is behavioral, not an enforced boundary.
+- **Access enforcement** differs by backend; see
+  [Backends: access and retention](data-and-permissions.md#backends-access-and-retention). Prompt
+  instructions are not access enforcement.
+- **Context isolation**: Bro does not add explanations, BTW answers, or the
+  steering brief to Pi's conversation history or main-agent context. BTW text
+  reaches the main editor only through `/insert` or `/insert-all`, and advisor
+  results appear as normal tool results in the executor's transcript.
+- **Saved reviews**: Guided Review records, questions, drafts and captured Git source persist under the host's `getAgentDir()/bro-reviews/`. No automatic cleanup or sync is provided; see [storage and removal](../guided-review.md#access-privacy-and-storage).
+- **Memory**: the latest explanation (for `/bro open`) and the BTW thread live
+  only in process memory and clear when you switch Pi sessions, reload
+  extensions, or quit Pi. Backend-native sessions can persist independently.
+  Standing advisor priorities are stored in `~/.pi/agent/bro-advisor.md`, and
+  the session steering brief is stored as session-scoped extension data
+  (`bro-advisor-steering`) in the session file.
+- **File safety**: `/bro file` reads only regular files whose resolved path is
+  inside Pi's current workspace, including after resolving symlinks. Bro's
+  extractor does not modify them.
+- **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
+  reserved network destinations, including redirects. Avoid private or signed
+  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 the selected backend; it does not
+  separately send the requested URL or raw page HTML.
+- **Show diagrams**: When a show reply ends in one self-contained HTML block
+  or one Mermaid sequence diagram, Bro writes a page to
+  `pi-bro-<uid>/bro-show-<hash>.html` in your system temp folder with a
+  restrictive Content-Security-Policy, and opens it in your browser only when
+  you press **O**. HTML pages run no scripts. Sequence-diagram pages run only
+  Bro's bundled Mermaid and its fixed setup script; the model's diagram text is
+  inserted as escaped text and nothing is loaded from the network. **C**
+  copies the full reply, including the diagram source.
+- **Clipboard**: **C**, `/copy`, `/copy-all`, and Guided Review's Copy finding copy text to your system
+  clipboard, where your operating system or clipboard manager may retain it.