pi-bro 0.13.2 → 0.15.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to pi-bro are documented here.
 
+## [0.15.0] - 2026-09-22
+
+### Changed
+
+- In the `/bro btw` modal, `/copy` and `/copy-all` now copy the latest answer or the full thread to the **system clipboard** instead of the main editor. New `/insert` and `/insert-all` commands (with `/insert!`/`/insert-all!` force variants to replace an existing main-editor draft) insert into the main editor without submitting. Removed the legacy `/send` aliases and the spaced `/copy all`/`/insert all` spellings.
+
+## [0.14.0] - 2026-09-20
+
+### Added
+
+- `bro_advisor` — a tool the **executor agent** (not the human) can voluntarily call mid-task for a second opinion from a fresh, standalone Agy process with real, unsandboxed tool access in the workspace (`--dangerously-skip-permissions`). Bro automatically captures a harness-neutral snapshot of the executor's system instructions, active tools, and conversation so far (including tool calls and results) and sends it, plus an optional executor-supplied question, to the advisor. The advisor is instructed to investigate before advising and to leave edits to the executor, but that boundary is behavioral, not enforced. Invocation failures retry twice (5s, then 10s) with the identical snapshot before surfacing Agy's own diagnostic.
+- `/bro advisor-steer` — an editor for one persistent, session-scoped steering brief the advisor always reads (e.g. "quick prototype; keep A and B careful, everything else minimal"). The brief is stored as session-only extension data, is never added to Pi's conversation or sent to the main model, persists across resume/reload, and is inherited by forks.
+- `/bro advisor` — a quick notice of whether `bro_advisor` is currently exposed and active, pointing at `/bro config`, `/bro advisor-steer`, and `/bro doctor`. `/bro doctor` carries the full diagnostic, including the Agy 1.1.15+ compatibility check.
+- `/bro config` — a production settings screen replacing the earlier configuration-only spike: a shared default model/effort (still owned by `/bro model`/`/bro effort`) plus optional per-capability overrides for `explain`, `show`, `btw`, and `advisor`. An override always pins both model and effort together and is only ever cleared by an explicit "Default" selection. Saves are serialized and coalesced, with in-place revert and an inline error notice on failure.
+
+### Changed
+
+- Requires Earendil Pi `>=0.84.2 <1` and `agy >=1.1.15` (up from `>=0.78.1 <1` and `>=1.1.11`).
+
 ## [0.13.2] - 2026-09-19
 
 ### Changed

package/README.md

@@ -11,7 +11,7 @@ with your selected model.
 
 ## Quick start
 
-You need Earendil Pi `>=0.78.1 <1`, Node.js `>=22.19.0`, and `agy >=1.1.11`
+You need Earendil Pi `>=0.84.2 <1`, Node.js `>=22.19.0`, and `agy >=1.1.15`
 installed and available on your `PATH`. Run `agy` once in your terminal to sign
 in, then install Bro:
 
@@ -63,10 +63,13 @@ text directly captures a new source the same way.
 | `/bro show [n-turns] [query]` | Draw recent session turns (default last 1) as shapes instead of prose, from user and assistant conversation text only — tool calls, tool results, reasoning, and images are omitted. An optional query steers what the shapes focus on, with or without a leading turn count. |
 | `/bro doctor` | Check Bro's settings, Agy installation, account, model, effort, and mode. |
 | `/bro usage [--provider agy]` | Show current Agy resource limits. |
-| `/bro model [id]` | View or choose the Agy model. |
-| `/bro effort [low\|medium\|high]` | View or choose the supported reasoning effort. |
+| `/bro model [id]` | View or choose the shared default Agy 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. |
 | `/bro btw [--fresh] [--full] [question]` | Open a side conversation in a modal. Sandboxed (read-only) by default; `--full` lets it read and edit the workspace, `--fresh` skips main-session context. |
+| `/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:
@@ -108,25 +111,105 @@ your terminal mode; press **C** to copy the complete explanation reliably.
 `/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
-conversation unless you explicitly copy it into the editor.
+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.
 - `/bro btw <question>` asks immediately; `/bro btw` opens an empty thread.
 - `--fresh` starts a thread without seeding the main session's recent
-  conversation text.
+  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
+  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
   side agent can also read the repo itself when running in `--full` mode.
 - **In the modal**: type a question and press Enter (empty Enter re-asks the
-  last question). `/copy` copies the latest answer into the main editor
-  without submitting (use `/copy!` to replace an existing draft); `/copy-all`
-  copies the full thread; `/retry` re-asks
-  the last question; `/clear` resets the thread; Esc closes. A visible
-  `full · edits repo` badge shows whenever `--full` mode is active.
+  last question). Composer actions trigger only on these exact commands:
+  - `/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 (use `/insert!` to replace an existing editor draft)
+  - `/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.
 - The thread lives in memory only — it clears when you switch Pi sessions,
   reload extensions, or quit Pi.
 
+## 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 model/effort, steering presence, and
+the Agy compatibility floor — it also checks the installed Agy version and
+gives an `agy update` action when it is too old.
+
+- **Automatic context, no prep needed**: the executor never assembles 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 Agy process** 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
+  (`--dangerously-skip-permissions`) — 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.
+- **Steering**: `/bro advisor-steer` opens an editor for one persistent
+  steering brief — e.g. "quick prototype; keep A and B careful, everything
+  else minimal" — that the advisor always reads. **Ctrl+S** saves and keeps
+  the editor open; **Enter** or **Shift+Enter** inserts a newline; **Ctrl+K**
+  clears both the saved brief and draft while staying open; **Ctrl+C** copies
+  the entire current draft, including unsaved edits; and **Esc** closes without
+  saving unsaved edits. Actions and clipboard errors are reported inline. The
+  brief is stored as session-only extension data and is **never added to Pi's
+  conversation or sent to the main model** — the advisor is the only thing
+  that reads it.
+- **Persistence**: the steering brief persists with the Pi session (not
+  globally, not per project) as custom extension data in the session file and
+  is restored on resume or reload. Forking a session inherits it; edits made
+  after the fork are independent of the original branch. The advisor tool has
+  no separate activation state persisted or toggled.
+- **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 Agy's own diagnostic — including a
+  context-length error, verbatim — as the failure. Cancelling the tool call
+  aborts immediately and skips any pending retry wait.
+- **Progress and provenance**: while an attempt is running, Bro parses the
+  advisor's own stream for the last thing it actually reported — either a
+  tool name or a user-facing response line (hidden reasoning is never
+  surfaced) — and shows it with how long ago it arrived, e.g. `last reported:
+  Read src/app.ts (2s ago)`. Before Agy reports anything, this reads
+  explicitly as "awaiting first activity from Agy" rather than guessing at
+  what it might be doing. This is what was actually reported, not a live
+  claim about Agy's current tool, and silence is never described as
+  "stalled". Expanding a running consultation shows up to the last 4 reported
+  activity lines. Each retry starts this trail over empty — a failed
+  attempt's activity never carries into the next one. Elapsed running time
+  still ticks once a second regardless of activity; a retry countdown with
+  the last failure is shown the same way as before. The returned answer
+  starts with model, effort, actual attempt count, duration, workspace,
+  steering presence, snapshot size, no-Bro-truncation status, and known
+  omission/compaction notes; the advisor's complete answer follows unchanged.
+- **Model/effort**: resolved the same way as explain/show/btw, through
+  `/bro model`/`/bro effort` (shared default) or `/bro config` (per-capability
+  override).
+
+See [docs/plans/2026-09-19-bro-advisor-design.md](docs/plans/2026-09-19-bro-advisor-design.md)
+for the full design.
+
 ## Bro show
 
 Where the explanation modes rewrite dense prose in simpler words, `/bro show`
@@ -160,11 +243,14 @@ 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.
 
-Only the first word is ever read as the turn count — a query that starts with
-digits is not ambiguous. `/bro show 1 404 handler` captures 1 turn and steers
-on "404 handler"; `/bro show 404 handler` (no leading count) steers on the
-whole phrase "404 handler" using the default turn count, since "404" alone
-would be a count but "404 handler" is not.
+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
 
@@ -610,15 +696,41 @@ Bro creates this user-editable settings file when the extension loads:
 }
 ```
 
-Use `/bro model`, `/bro effort`, and `/bro mode` to update it from Pi, or edit
-it directly. Bro reads the file again before each explanation, so manual changes
+`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:
+
+```json
+{
+  "model": "gemini-3.7-flash",
+  "effort": "low",
+  "mode": "balanced",
+  "showTurns": 1,
+  "overrides": {
+    "show": { "model": "gemini-3.7-pro", "effort": "high" }
+  }
+}
+```
+
+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
+directly. Bro reads the file again before each explanation, so manual changes
 apply to the next `/bro`. Use a model ID shown by `/bro model`; `effort` must be
 one of the levels shown by `/bro effort`. Models without adjustable effort use
 `default`. `mode` must be `brief`, `balanced`, or `faithful`; existing settings
 without it use `balanced`. `showTurns` is the default number of turns `/bro
-show` draws (default 1); `/bro show <n-turns>` overrides it for a single run. There
-is no `/bro showTurns` command — edit the file directly. The choices remain active across Pi restarts until
-you change them. `/bro help` shows the active settings and exact file path.
+show` draws (default 1); `/bro show <n-turns>` overrides it for a single run. Settings
+written before per-capability overrides existed load unchanged, with no overrides. The choices remain
+active across Pi restarts until you change them. `/bro help` shows the active
+settings, any overrides, and the exact file path.
+
+`/bro config`'s changes save immediately as you make them. Pressing Esc inside
+a model or effort picker cancels that pick without changing anything; pressing
+Esc on the settings screen itself just closes it, keeping whatever was already
+saved. If a save fails (for example, a read-only settings file), the screen
+shows the error inline instead of losing the change silently.
 
 If `PI_CODING_AGENT_DIR` is set, the file lives there instead. `PI_BRO_MODEL`
 chooses the initial model only when Bro creates a missing settings file:
@@ -627,6 +739,23 @@ chooses the initial model only when Bro creates a missing settings file:
 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).
+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`:
+1. **Command argument**: An explicit count like `/bro show 3` or `/bro show 1 query` overrides for that single execution.
+2. **Saved setting**: `showTurns` in `bro-settings.json` (defaults to 1; configurable interactively via `/bro config` or direct file edit).
+
+When resolving explanation prompt (`explain` capability only):
+1. **Custom prompt**: `~/.pi/agent/bro-prompt.md` (or `$PI_CODING_AGENT_DIR/bro-prompt.md`), if present and valid (`{{response}}` exactly once), completely overrides all built-in modes.
+2. **Saved mode**: `mode` in `bro-settings.json` (`brief`, `balanced`, or `faithful`; defaults to `balanced`).
+3. Note: `bro-prompt.md` applies only to `/bro`, `/bro text`, `/bro file`, and `/bro url`; it does not affect `/bro show`, `/bro btw`, or `bro_advisor`.
+
 ## Custom prompt
 
 Bro uses a built-in prompt by default. To use your own, create:
@@ -705,6 +834,24 @@ run `/bro doctor` for the exact problem.
   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.
+- **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), human steering brief, and the executor's optional question to
+  Agy and your 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,
+  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.
+- **Advisor steering persistence**: The steering brief is saved as
+  session-scoped custom extension data (`bro-advisor-steering`) in the session
+  file. It persists across session resume and reload, and is inherited on
+  session fork (post-fork edits on branches remain independent). It is never
+  sent to the main model or added to Pi's conversation. The advisor tool has
+  no separate activation state.
 
 ## Troubleshooting and current limits
 
@@ -724,6 +871,11 @@ tool before giving it to Bro.
 - `/bro btw` threads are memory-only and do not survive reloads or restarts.
   The side conversation needs Agy's `--conversation` resume support; sandbox
   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
+  without enforced file-modification isolation; an attempt is capped at 10
+  minutes (`--print-timeout 10m`) and retries up to 2 times on invocation
+  failure (5-second, then 10-second backoff).
 - 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; it cannot