pi-bro 0.23.1 → 0.25.0

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.

package/docs/reference/settings.md

@@ -0,0 +1,108 @@
+# Set up models and preferences
+
+[Docs home](../README.md) · [All commands](commands.md) · [Safety and permissions](data-and-permissions.md)
+
+## Settings
+
+Use `/bro config` to review or change the shared default backend/model/effort
+and any per-capability (explain/show/btw/advisor/review) overrides, the explanation
+mode, and the default show turn count. Changes save immediately. Esc inside a
+picker cancels that pick; Esc on the settings screen closes it, keeping
+whatever was already saved. If the terminal becomes too small, config blocks
+hidden actions; Esc closes config even if a picker was open, after pending saves
+finish. A failed save cancels that close and shows its error inline; if the error
+alone makes config too small, any other key clears it so you can try again. `/bro mode` changes the mode directly (**M** in an explanation
+tries another mode without saving it), and `/bro help` shows the active settings
+and file path.
+
+Elevate inherits the **BTW** backend/model/effort selection. There is no separate Elevate setting in this release. See the [Elevate guide](../elevate.md).
+
+Settings live in this user-editable file, created when the extension loads
+(under `$PI_CODING_AGENT_DIR` instead when that is set):
+
+```text
+~/.pi/agent/bro-settings.json
+```
+
+```json
+{
+  "version": 2,
+  "default": { "backend": "agy", "model": "gemini-3.7-flash", "effort": "low" },
+  "mode": "balanced",
+  "showTurns": 1,
+  "overrides": {
+    "explain": { "backend": "claude", "model": "sonnet", "effort": "medium" },
+    "advisor": { "backend": "grok", "model": "grok-4.7", "effort": "high" }
+  }
+}
+```
+
+Bro reads the file again before each request, so manual edits apply next time.
+
+- Each selection is one atomic backend/model/effort choice. An override pins
+  its own complete selection and ignores the shared default, even when it
+  happens to match it; select **Default** in `/bro config` to inherit again.
+  Omitted overrides inherit `default`.
+- `effort` must be one the backend offers (`default` omits it and lets the
+  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.
+- `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.
+- `PI_BRO_MODEL` picks the initial Agy model only when Bro creates a missing
+  settings file, for example `PI_BRO_MODEL=gemini-3.7-flash-low pi`.
+- Older flat settings files (root `model`/`effort`) still load and mean Agy.
+
+## Preferences
+
+Tell Bro about yourself and how you like answers. Bro adds what you write to
+every explain, `/bro show`, `/bro btw`, `/bro elevate`, and Guided Review prompt as a labelled section,
+alongside its own instructions. It never replaces them: modes, **M**, and the
+source rules keep working. The advisor never receives your preferences; use
+`/bro advisor-steer` for it.
+
+Run `/bro preferences` to edit them: **Ctrl+S** saves, **Ctrl+K** deletes the
+file, **Ctrl+C** copies, and **Esc** closes without saving. The first time,
+the editor opens with this starter text, which is not saved until you press
+**Ctrl+S**:
+
+```md
+## About me
+I'm an overworked white-collar worker, and so are my colleagues. By the end of a
+hard day our brains are fried and we can only handle simple language, no matter
+how sharp we are at our best.
+
+## How I like answers
+- Explain it like I'm a simpleton: plain, everyday words.
+- Go easy on analogies. No forced ones.
+```
+
+You can also edit the file directly (under `$PI_CODING_AGENT_DIR` instead when
+that is set):
+
+```text
+~/.pi/agent/bro-preferences.md
+```
+
+- **Free-form**: no placeholder or structure is required. Bro re-reads the
+  file on every request, so edits apply next time. A missing or empty file
+  means no preferences, and Bro's prompts are then exactly the built-in ones.
+- **What preferences can change**: wording, tone, technical depth, length in
+  BTW, and the answer language. If you name a language, code, commands, paths,
+  names, and numbers still stay exactly as written. In `/bro show`,
+  preferences only change wording and language. Guided Review also receives preferences for explanation/answer wording; they do not override its evidence or review rules. A per-run choice (the mode,
+  **M**, a Show steering query, or what a BTW/review question asks for) wins over a
+  standing preference.
+- **Limit**: 4,000 characters, because the text goes with every request. A
+  longer file stops explain, Show, BTW, and Guided Review with an error until you trim it;
+  Bro never cuts it silently. `/bro doctor` reports the problem, and the
+  editor still opens the file so you can fix it.
+- **BTW threads**: when your preferences change, the next side question starts
+  a fresh backend session that is caught up on the thread, so old preferences
+  don't linger.
+
+`bro-prompt.md`, the full prompt template from earlier versions, is no longer
+read. Move what you want to keep into `/bro preferences`, and choose
+`/bro mode brief` for the original ELI-simpleton instruction.

package/docs/reference/troubleshooting.md

@@ -0,0 +1,55 @@
+# Diagnostics and troubleshooting
+
+[Docs home](../README.md) · [All commands](commands.md) · [Safety and permissions](data-and-permissions.md)
+
+## Check your setup
+
+Run `/bro doctor` when Bro is newly installed or something is not working. It
+checks Bro's settings and preferences, then probes only the backends some feature
+actually selects, and reports the effective backend/model/effort for each
+feature. Failed checks explain what to fix.
+
+- **Agy**: installed version, model catalog, and account access.
+- **Claude Code**: installed version and configured authentication.
+- **Grok**: installed version only; authentication and connectivity are not
+  verified.
+- **Codex**: installed version and configured authentication.
+- **Muse**: installed version only; authentication and connectivity are not
+  verified.
+
+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
+succeed.
+
+## Troubleshooting and current limits
+
+If an explanation fails, run `/bro doctor` first. If a webpage cannot be
+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.
+
+- An unsupported model, effort, or missing backend fails with that backend's
+  diagnostic; Bro never falls back to another backend.
+- 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
+  100,000 extracted characters. JavaScript-only, authenticated, paywalled,
+  blocked, paginated, and media-first pages are not supported.
+- Direct webpage fetching does not currently use `HTTP_PROXY`, `HTTPS_PROXY`,
+  or other proxy environment variables.
+- `/bro elevate` is pre-execution only. It does not validate expert claims, run source research or keep a persistent thread. Invalid discovery JSON can be retried with the [Retry] button; if it recurs, choose another BTW backend/model in `/bro config`. See [Elevate](../elevate.md).
+- `/bro btw` threads are memory-only and do not survive reloads or restarts.
+- The Agy advisor requires Agy CLI `>=1.1.15`.
+- Show captures only the conversation text of what already happened in the
+  current session — the last few turns' user and assistant messages, with
+  tool calls, tool results, reasoning, and images always omitted; its shapes
+  reflect what was reported in the conversation, not independent verification.
+- Diagrams open in your default browser; pressing **O** on a remote or
+  headless session with no display reports the failure instead of opening
+  anything.
+- Explain keeps only the latest result in memory and does not export directly to files. Guided Review separately persists review records and captured source.
+- Guided Review is local-Pi interactive only, keeps its captured revision on reopen, and does not publish, review a branch or fetch later PR changes. See [review recovery and limits](../guided-review.md#if-something-goes-wrong).
+- Bro temporarily captures mouse input while its modal is open so mouse-wheel
+  and trackpad scrolling work in regular and fullscreen modes. Native mouse
+  selection may be unavailable or visually extend outside the Bro window;
+  press **C** to copy the full explanation instead.