pi-bro 0.23.1 → 0.24.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to pi-bro are documented here.
 
+## [0.24.0] - 2026-10-19
+
+### Highlights
+
+- Guided Review now works with Codex, Grok and Agy, not just Claude and Muse. Those three run shell commands inside their own sandbox on the captured checkout.
+- Bro tells you plainly when a review backend can run shell commands (and that Agy's sandbox still allows writes), and recommends Claude or Muse for PRs you do not trust.
+- `/bro doctor` no longer treats a Codex/Grok/Agy review choice as a setup problem; it shows the same advisory as information.
+- Nothing changes for Claude and Muse, which still use strict file-only inspection.
+
+### Changed
+
+- Review generation and questions no longer fail before starting on Codex, Grok and Agy. Codex runs `--sandbox read-only --ephemeral`, Grok runs `--sandbox read-only --permission-mode dontAsk`, and Agy keeps `--sandbox` (which limits terminal commands, not file writes); all three use the captured checkout and the 10-minute review deadline. No bypass flag is ever added to a review, and Grok review no longer gets the "do not inspect" prompt restriction.
+- A new advisory appears while a review is being prepared, in the review window, and in `/bro doctor`: the backend runs commands inside its sandbox rather than doing strict file-only inspection.
+- Saved reviews still open with any backend.
+
 ## [0.23.1] - 2026-10-15
 
 ### Highlights

package/README.md

@@ -51,7 +51,7 @@ GitHub, use `pi install git:github.com/tranhoangnguyen03/pi-bro`.
 | `/bro`, `/bro text`, `/bro file`, `/bro url` | **[Explain](docs/user-guide.md#what-bro-can-explain).** A plain-language version of the agent's last reply, pasted text, a PDF/DOCX/Markdown file, or a public webpage. Three modes: `brief`, `balanced`, `faithful`. |
 | `/bro show` | **[Show](docs/user-guide.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 btw` | **[Side questions](docs/user-guide.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. Needs the Claude or Muse backend. |
+| `/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/user-guide.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 config`, `/bro preferences` | **[Settings](docs/user-guide.md#settings) and [preferences](docs/user-guide.md#preferences).** Pick the backend, model and effort per feature, and tell Bro how you like answers. |
 
@@ -68,14 +68,14 @@ Guided Review has its own [guide](docs/guided-review.md).
 
 | Backend | CLI | Notes |
 | --- | --- | --- |
-| [Google Antigravity](https://antigravity.google/docs/cli-install) | `agy` | Default for new settings. Needs `>=1.1.15`. Not for Guided Review. |
-| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `claude` | Works for every feature, including Guided Review. |
-| [Grok Build](https://docs.x.ai/build/overview) | `grok` | Not for Guided Review. |
-| [Codex CLI](https://github.com/openai/codex) | `codex` | Not for Guided Review. |
-| [Muse Code](https://dev.meta.ai/docs/muse-code) | `muse` | Works for every feature, including Guided Review. |
+| [Google Antigravity](https://antigravity.google/docs/cli-install) | `agy` | Default for new settings. Needs `>=1.1.15`. Guided Review uses `--sandbox`, which restricts shell commands but still allows writes inside the project. |
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `claude` | Works for every feature; strict file-only inspection for Guided Review. |
+| [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. |
 
 - Guided Review also needs Git and an authenticated [`gh`](https://cli.github.com/).
-  Choose Claude or Muse for it in `/bro config`.
+  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.
 - [PiG](docs/pig-compatibility.md) support is experimental.
 
 ## What leaves your machine
@@ -105,8 +105,9 @@ tool results.
 >   only an instruction.
 > - **BTW full-permission mode** (turned on with `/mode` inside BTW): it is
 >   meant to edit files and run commands.
-> - **Grok, wherever you use it:** its sandbox is always off. "Answer only from
->   the supplied context" is only an instruction.
+> - **Grok:** its sandbox is off except during Guided Review, which uses the
+>   read-only sandbox. "Answer only from the supplied context" is only an
+>   instruction.
 
 Details per backend:
 [Backends: access and retention](docs/user-guide.md#backends-access-and-retention)

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 Claude or Muse configured for review. Run `gh auth status` to check GitHub authentication; `/bro doctor` checks Bro's selected backend setup but does not prove GitHub access or model connectivity.
+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.
 
 ```text
 /bro guided-review https://github.com/OWNER/REPO/pull/123
@@ -20,12 +20,6 @@ A URL works even when your current workspace belongs to a different repository.
 
 A **new** review captures the PR's base/head commits outside your working tree and automatically makes one model request. Subsequent questions each make another request. Calls use your selected backend CLI's account and billing—not Pi's model account. Bro does not automatically retry a failed generation or switch backends.
 
-For fullscreen mouse scrolling, start Pi with:
-
-```sh
-pi --tui-mode fullscreen
-```
-
 Opening the **same PR again** restores its saved review without another model call. Bare `/bro guided-review` lists saved reviews; `/bro guided-review resume` remains an alias for that list.
 
 **Reopening keeps the captured code.** It does not fetch a new comparison when the author pushes commits. Opening by URL/number checks current metadata and reports newer source, but continues the saved capture. The saved-review picker does not check freshness. Reviewing newer revisions is not implemented.
@@ -63,7 +57,7 @@ The generation header shows observable application stages and elapsed time—not
 | Close | Save automatically and leave |
 | Stop and close | Stop active work, await cancellation, save partial work, then leave |
 
-In fullscreen mode, the wheel scrolls the pane under the pointer without moving its list selection or keyboard focus. Reading an active answer pauses following; deliberately returning to the bottom resumes it. In regular terminal mode, the wheel belongs to terminal scrollback.
+The wheel scrolls the pane under the pointer without moving its list selection or keyboard focus, in regular and fullscreen mode. Reading an active answer pauses following; deliberately returning to the bottom resumes it. In regular terminal mode, Bro captures the mouse while the review is open (as its other windows do), so terminal scrollback and mouse text selection return when you close it; use the copy actions meanwhile.
 
 ## Ask privately, if needed
 
@@ -89,13 +83,15 @@ Use Overview → Regenerate guide only when you want a fresh explanation/assessm
 
 ## Access, privacy and storage
 
-Review uses **file-only inspection**, not full-access execution. 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. Unsupported/older CLI flags fail visibly; there is no full-access fallback.
+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.
+
+**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.
 
-Agy, Grok and Codex are not available for review generation/questions: supported controls do not establish equivalent shell-free inspection (Codex read-only sandbox still executes commands). Set the **review** override to Claude or Muse in `/bro config`; shared defaults and other features are unchanged. Saved reviews remain readable without a supported model backend. Doctor shows the review override requirement as information; it does not make an otherwise healthy installation fail.
+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.
 
 These controls reduce malicious-code execution/write risk, but repository content can still manipulate the model's conclusions. Captured content, questions and answers go to the provider; do not use review as a secrets boundary or approval certificate. CLI enforcement and managed host policies remain the backend's responsibility.
 
-PR identity/description, diff, relevant saved discussion and your Bro preferences are sent to the selected backend. It can read the captured source. Main-session conversation is not automatically attached. Each request reconstructs context; review does not resume BTW/native sessions. Claude/Muse disable native session persistence where their CLIs support it; backend/provider retention policies still apply.
+PR identity/description, diff, relevant saved discussion and your Bro preferences are sent to the selected backend. It can inspect the captured source. Main-session conversation is not automatically attached. Each request reconstructs context; review does not resume BTW/native sessions. Claude, Muse and Codex disable native session persistence where their CLIs support it; backend/provider retention policies still apply.
 
 Records, private text and captured source remain under:
 
@@ -112,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 |
-| Unsupported review backend | Choose Claude or Muse for review in `/bro config`; no automatic switching |
+| Sandboxed shell review backend (Codex, Grok, Agy) | Advisory shown; choose Claude or Muse 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/user-guide.md

@@ -88,6 +88,7 @@ next mode without saving it:
 
 - **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
@@ -119,8 +120,9 @@ Nothing is automatically applied or posted to GitHub.
 /bro guided-review https://github.com/OWNER/REPO/pull/123
 ```
 
-Local Pi interactive mode, Git, authenticated `gh`, and Claude or Muse configured for review
-are required. A new review makes a model call using that backend's account.
+Local Pi interactive mode, Git, authenticated `gh`, and a configured review backend
+(Claude or Muse is recommended for untrusted PRs). A new review makes a model call
+using that backend's account.
 Opening the same PR restores its saved review without another model call.
 Bare `/bro guided-review` lists saved reviews (`resume` is an alias).
 
@@ -138,8 +140,15 @@ Optional conveniences:
 
 Reopening also keeps the captured revision, even after the author pushes.
 Findings are model suggestions, not approval; citations show real locations,
-not proof of the conclusion. Review uses Claude or Muse file-only inspection: shell, writes and web tools are disabled. Agy/Grok/Codex review requests fail clearly; choose a review override in `/bro config`. Saved reviews remain readable with any selection. Repository text can still mislead the model; tool restrictions are not proof of its conclusions.
-Use `pi --tui-mode fullscreen` for pane-local wheel scrolling.
+not proof of the conclusion. Claude and Muse use strict file-only inspection
+(shell, writes and web tools disabled). Codex and Grok use a read-only sandbox;
+Agy's sandbox only restricts terminal commands and still allows writes inside
+the project. All three run shell commands, and an advisory says so.
+Claude or Muse is recommended for untrusted PRs; choose a review override in
+`/bro config`. Saved reviews remain readable with any selection. Repository
+text can still mislead the model; sandboxing and tool restrictions are not
+proof of its conclusions.
+The wheel scrolls the pane under the pointer in regular and fullscreen mode.
 
 See the [Guided Review guide](guided-review.md) for controls, calls and
 costs, source freshness, access/privacy, local storage, recovery and current
@@ -207,8 +216,8 @@ 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 never assembles a
-  summary. Bro captures a harness-neutral snapshot — the executor's system
+- **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
@@ -748,8 +757,10 @@ 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. A failed save (for example, a read-only file) is
-shown inline. `/bro mode` changes the mode directly (**M** in an explanation
+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.
 
@@ -800,18 +811,25 @@ 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 | Unavailable; choose Claude/Muse |
+| **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 | Unavailable; choose Claude/Muse |
-| **Codex** | Scratch directory, read-only sandbox, ephemeral session | Workspace, read-only sandbox | Workspace, approvals and sandbox bypassed | Fresh workspace process, approvals and sandbox bypassed | Unavailable; command execution is not allowed for review |
+| **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 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.
+- 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. Bro does not disable configured MCP
-  servers or web search; their access is governed by Codex configuration.
+  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.
@@ -914,7 +932,7 @@ read. Move what you want to keep into `/bro preferences`, and choose
   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 using Claude/Muse read-only tools. Main-session context is not attached. Review shell/write/web tools are disabled; Claude file tools are confined with `--restricted`, Muse uses workspace-scoped inspection. 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) 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, and Guided Review request to the selected backend. It is never sent to the advisor or
   to Pi's main model.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-bro",
-  "version": "0.23.1",
+  "version": "0.24.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",
@@ -56,6 +56,7 @@
     "src/sources.ts",
     "src/config-ui.ts",
     "src/ui-capabilities.ts",
+    "src/modal-kit.ts",
     "src/backend.ts",
     "src/prompt.ts",
     "src/vendor/mermaid.min.js",
@@ -75,7 +76,7 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "npm run typecheck && node .github/scripts/release-utils.mjs selftest && node --test test/review-ux.test.mjs test/review-doctor.test.mjs test/review-versions.test.mjs test/review-regeneration.test.mjs test/review-modal.test.mjs test/review.test.ts test/review-ui.test.mjs test/review-session.test.mjs test/helpers.test.mjs test/prompt.test.ts test/backend.test.ts test/claude.test.ts test/grok.test.ts test/codex.test.ts test/muse.test.ts test/settings.test.ts test/sources.test.ts test/release.test.ts test/show-html.test.ts test/smoke-rpc.test.ts test/ui-capabilities.test.ts benchmark/*.test.ts && sh ./test/smoke-test.sh",
+    "test": "npm run typecheck && node .github/scripts/release-utils.mjs selftest && node --test test/review-ux.test.mjs test/review-doctor.test.mjs test/review-versions.test.mjs test/review-regeneration.test.mjs test/review-modal.test.mjs test/review.test.ts test/review-ui.test.mjs test/review-session.test.mjs test/helpers.test.mjs test/prompt.test.ts test/backend.test.ts test/claude.test.ts test/grok.test.ts test/codex.test.ts test/muse.test.ts test/settings.test.ts test/sources.test.ts test/release.test.ts test/show-html.test.ts test/smoke-rpc.test.ts test/ui-capabilities.test.ts test/modal-contract.test.mjs benchmark/*.test.ts && sh ./test/smoke-test.sh",
     "benchmark:dry-run": "node benchmark/run.ts dry-run",
     "benchmark:run": "node benchmark/run.ts run",
     "benchmark:report": "node benchmark/run.ts report",

package/src/advisor.ts

@@ -460,11 +460,11 @@ export function registerAdvisorTool(pi: ExtensionAPI): void {
 		name: ADVISOR_TOOL_NAME,
 		label: "Bro advisor",
 		description:
-			"Consult a fresh, independent process of the configured advisor backend for a second opinion mid-task. It has real, unsandboxed tool access in the current workspace (read files, search, run commands) with permissions auto-approved, and is instructed to investigate before advising and to leave edits to you — that is a behavioral instruction to the advisor, not an enforced restriction, so treat its findings as advice rather than a delegated implementation. You never need to prepare a summary or evidence first: Bro automatically captures your system instructions, active tools, and the conversation so far, plus any human-set steering priorities, and sends them to the advisor.",
+			"Consult a fresh, independent process of the configured advisor backend for a second opinion mid-task. It has real, unsandboxed tool access in the current workspace (read files, search, run commands) with permissions auto-approved, and is instructed to investigate before advising and to leave edits to you — that is a behavioral instruction to the advisor, not an enforced restriction, so treat its findings as advice rather than a delegated implementation. No need to prepare a summary or evidence first: Bro automatically captures your system instructions, active tools, and the conversation so far, plus any human-set steering priorities, and sends them to the advisor.",
 		promptSnippet: "Consult a fresh configured-backend process for a second opinion mid-task; it investigates the workspace itself and returns advice",
 		promptGuidelines: [
-			"Call bro_advisor before or after a non-trivial design or scope decision, or when genuinely uncertain, for a second opinion from a fresh, independent process of the configured advisor backend.",
-			"bro_advisor's question parameter is optional — never delay a call to first prepare a summary or evidence; Bro captures context automatically.",
+			"Use bro_advisor when the user asks for an independent opinion, or when one would likely settle real uncertainty or catch a costly mistake. Routine decisions do not require consultation.",
+			"bro_advisor's question parameter is optional — Bro captures context automatically, so you do not need to prepare a summary or evidence before calling.",
 			"Any human-set steering priorities are applied automatically by bro_advisor; you don't need to relay or repeat them.",
 			"bro_advisor is instructed to only return advice and leave edits to you — that instruction is not enforced, so verify its findings yourself rather than treating them as a completed implementation.",
 		],

package/src/backend.ts

@@ -8,12 +8,28 @@ import { join } from "node:path";
 // (Agy, Claude Code, Grok, Codex, Muse): it owns CLI selection, process invocation,
 // progress/outcome normalization, continuation, and single-attempt cleanup. Feature code
 // keeps retries, UI, source/session capture and settings.
+// For Guided Review (`feature: "review"`), Claude and Muse enforce strict file-only inspection;
+// Agy, Grok, and Codex run inside their own sandbox with shell available, and the UI owns telling
+// the user via `reviewBackendNotice`.
 
 export type BackendFeature = "explain" | "show" | "btw" | "advisor" | "review";
 export type BackendAccess = "restricted" | "workspace-full";
-export function reviewBackendError(backend: string): string | undefined {
-	if (backend !== "claude" && backend !== "muse") return "Guided Review requires Claude or Muse for file-only inspection. Set the review backend in /bro config; saved reviews remain readable.";
+// Per-backend truth, not one shared sentence: Codex and Grok have a read-only sandbox, Agy's
+// sandbox only restricts terminal commands and still lets it write inside the project. Kept short
+// enough that the whole notice fits the review window's advisory rows on a narrow terminal.
+export function reviewBackendNotice(backend: "agy" | "claude" | "grok" | "codex" | "muse"): string | undefined {
+	if (backend === "claude" || backend === "muse") return undefined;
+	const sandbox = backend === "agy" ? "sandboxed shell (project writes allowed)" : "sandboxed shell in a read-only sandbox";
+	return `Guided Review on ${backend} uses ${sandbox}, not strict file-only inspection. Claude or Muse is recommended for untrusted PRs.`;
 }
+// One default deadline table for every adapter: workspace-full, Guided Review and the advisor get
+// the long bound; btw the middle one; explain/show the short one.
+export const REVIEW_DEADLINE_MS = 610_000;
+export function backendDeadlineMs(feature: BackendFeature, access: BackendAccess): number {
+	if (access === "workspace-full" || feature === "review") return REVIEW_DEADLINE_MS;
+	return feature === "btw" ? 130_000 : 125_000;
+}
+
 export type AgySelection = { model: string; effort?: "low" | "medium" | "high" };
 export const CLAUDE_EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;
 export const GROK_EFFORTS = ["low", "medium", "high", "xhigh"] as const;
@@ -232,16 +248,17 @@ async function executeArgvPrint(
 	// stdin protocol rather than risking Linux's per-argument byte limit.
 	const stdinPrompt = Buffer.byteLength(request.prompt, "utf8") >= 120_000;
 	const isBtw = request.feature === "btw";
+	const inspect = request.feature === "review";
 	const full = request.access === "workspace-full";
-	const deadlineMs = deadlineMsOverride ?? (full ? 610_000 : isBtw ? 130_000 : 125_000);
-	const printTimeout = full ? "10m" : "2m";
-	const action = request.feature === "review" ? "complete the guided review request" : isBtw ? "answer the side question" : "simplify the response";
-	const timeoutVerb = request.feature === "review" ? "during the guided review request" : isBtw ? "during the side conversation" : "while simplifying the response";
-	const emptyTextMessage = request.feature === "review" ? "Agy returned no response for Guided Review." : isBtw ? "Agy returned no answer for the side question." : "Agy returned no final explanation.";
+	const deadlineMs = deadlineMsOverride ?? backendDeadlineMs(request.feature, request.access);
+	const printTimeout = full || inspect ? "10m" : "2m";
+	const action = inspect ? "complete the guided review request" : isBtw ? "answer the side question" : "simplify the response";
+	const timeoutVerb = inspect ? "during the guided review request" : isBtw ? "during the side conversation" : "while simplifying the response";
+	const emptyTextMessage = inspect ? "Agy returned no response for Guided Review." : isBtw ? "Agy returned no answer for the side question." : "Agy returned no final explanation.";
 
 	if (signal.aborted) return { status: "cancelled", message: "Canceled." };
 
-	const runDirectory = full ? undefined : await mkdtemp(join(tmpdir(), "pi-bro-"));
+	const runDirectory = full || inspect ? undefined : await mkdtemp(join(tmpdir(), "pi-bro-"));
 	if (signal.aborted) {
 		if (runDirectory) await rm(runDirectory, { recursive: true, force: true });
 		return { status: "cancelled", message: "Canceled." };
@@ -264,7 +281,7 @@ async function executeArgvPrint(
 				...(stdinPrompt ? ["--input-format", "stream-json"] : ["--print", request.prompt]),
 			],
 			{
-				cwd: full ? request.cwd : runDirectory,
+				cwd: full || inspect ? request.cwd : runDirectory,
 				stdio: [stdinPrompt ? "pipe" : "ignore", "pipe", "pipe"],
 				windowsHide: true,
 				detached: process.platform !== "win32",
@@ -446,7 +463,7 @@ async function executeAdvisorStdin(
 ): Promise<BackendOutcome> {
 	if (signal.aborted) return { status: "cancelled", message: "Canceled." };
 
-	const deadlineMs = deadlineMsOverride ?? 610_000;
+	const deadlineMs = deadlineMsOverride ?? backendDeadlineMs(request.feature, request.access);
 	const child = spawn(
 		"agy",
 		[
@@ -570,7 +587,7 @@ async function executeClaude(
 	const isBtw = request.feature === "btw";
 	const inspect = request.feature === "review";
 	const full = request.access === "workspace-full";
-	const deadlineMs = deadlineMsOverride ?? (full || inspect ? 610_000 : isBtw ? 130_000 : 125_000);
+	const deadlineMs = deadlineMsOverride ?? backendDeadlineMs(request.feature, request.access);
 	const action = request.feature === "review" ? "complete the guided review request" : isAdvisor ? "complete the advisor consultation" : isBtw ? "answer the side question" : "simplify the response";
 
 	if (signal.aborted) return { status: "cancelled", message: "Canceled." };
@@ -751,18 +768,21 @@ export const GROK_RESTRICTED_PREFIX =
 	"Bro restricted mode (a request, not a technical restriction): answer only from the context supplied in this prompt. " +
 	"Do not inspect, read, or write workspace files, run commands, or use web or other external tools unless the user explicitly asks you to in this prompt.";
 
-// Grok runs every feature with all capabilities on (--sandbox off, bypassPermissions, no tool
-// blacklist). explain/show run in a fresh mkdtemp scratch cwd removed afterwards (the Agy pattern);
+// Grok runs explain, show, btw, and advisor with all capabilities on (--sandbox off,
+// bypassPermissions, no tool blacklist); Guided Review (`review`) runs in the caller's workspace
+// under Grok's read-only sandbox (--sandbox read-only, --permission-mode dontAsk).
+// explain/show run in a fresh mkdtemp scratch cwd removed afterwards (the Agy pattern);
 // btw (both accesses) runs in the caller's workspace cwd and continues natively with --resume, whose
-// session keeps the cwd it was created in; the advisor runs fresh in the workspace. Restricted
-// requests get GROK_RESTRICTED_PREFIX. The prompt goes through a private 0600 file in its own
-// mkdtemp directory, removed once the attempt ends.
+// session keeps the cwd it was created in; the advisor and review run fresh in the workspace.
+// Restricted requests other than review get GROK_RESTRICTED_PREFIX (review must be allowed to
+// inspect the captured checkout). The prompt goes through a private 0600 file in its own mkdtemp
+// directory, removed once the attempt ends.
 // Only a top-level terminal `result` with success/is_error false/end_turn is authoritative; the
 // first failure (a failed result or a top-level `error` event, even after a success) is latched.
-// Nested (subagent) frames are ignored. The advisor reports activity labels only; explain/show/btw
-// report top-level text_delta progress, falling back to an assistant message's text blocks only when
-// no delta streamed for it. Thinking is never reported. btw requires init/result session ids to
-// agree (and to equal the resumed id) and returns that id as the continuation.
+// Nested (subagent) frames are ignored. The advisor reports activity labels only; explain/show/btw/review
+// report top-level text_delta progress, falling back to an assistant message's text
+// blocks only when no delta streamed for it. Thinking is never reported. btw requires init/result
+// session ids to agree (and to equal the resumed id) and returns that id as the continuation.
 async function executeGrok(
 	request: BackendRequest,
 	selection: { model: string; effort?: string },
@@ -773,11 +793,13 @@ async function executeGrok(
 ): Promise<BackendOutcome> {
 	const isAdvisor = request.feature === "advisor";
 	const isBtw = request.feature === "btw";
-	const deadlineMs = deadlineMsOverride ?? (request.access === "workspace-full" ? 610_000 : isBtw ? 130_000 : 125_000);
-	const action = request.feature === "review" ? "complete the guided review request" : isAdvisor ? "complete the advisor consultation" : isBtw ? "answer the side question" : "simplify the response";
-	const timeoutVerb = request.feature === "review" ? "during the guided review request" : isAdvisor ? "during the advisor consultation" : isBtw ? "during the side conversation" : "while simplifying the response";
-	const emptyTextMessage = request.feature === "review" ? "Grok returned no response for Guided Review." : isAdvisor ? "Grok returned no advice." : isBtw ? "Grok returned no answer for the side question." : "Grok returned no final explanation.";
-	const prompt = request.access === "restricted" ? `${GROK_RESTRICTED_PREFIX}\n\n${request.prompt}` : request.prompt;
+	const inspect = request.feature === "review";
+	const deadlineMs = deadlineMsOverride ?? backendDeadlineMs(request.feature, request.access);
+	const action = inspect ? "complete the guided review request" : isAdvisor ? "complete the advisor consultation" : isBtw ? "answer the side question" : "simplify the response";
+	const timeoutVerb = inspect ? "during the guided review request" : isAdvisor ? "during the advisor consultation" : isBtw ? "during the side conversation" : "while simplifying the response";
+	const emptyTextMessage = inspect ? "Grok returned no response for Guided Review." : isAdvisor ? "Grok returned no advice." : isBtw ? "Grok returned no answer for the side question." : "Grok returned no final explanation.";
+	// Review inspects the captured checkout, so it must not carry the "do not inspect" restriction.
+	const prompt = request.access === "restricted" && !inspect ? `${GROK_RESTRICTED_PREFIX}\n\n${request.prompt}` : request.prompt;
 
 	if (signal.aborted) return { status: "cancelled", message: "Canceled." };
 	const promptDirectory = await mkdtemp(join(tmpdir(), "pi-bro-grok-"));
@@ -786,16 +808,14 @@ async function executeGrok(
 		if (signal.aborted) return { status: "cancelled", message: "Canceled." };
 		const promptFile = join(promptDirectory, "prompt.txt");
 		await writeFile(promptFile, prompt, { encoding: "utf8", mode: 0o600 });
-		if (request.access !== "workspace-full" && !isBtw) runDirectory = await mkdtemp(join(tmpdir(), "pi-bro-"));
+		if (request.access !== "workspace-full" && !isBtw && !inspect) runDirectory = await mkdtemp(join(tmpdir(), "pi-bro-"));
 		if (signal.aborted) return { status: "cancelled", message: "Canceled." };
 
 		const child = spawn(
 			"grok",
 			[
-				"--sandbox",
-				"off",
-				"--permission-mode",
-				"bypassPermissions",
+				// Review never auto-approves: dontAsk denies unpromptable asks instead of bypassing them. Unverified against a local grok CLI; an unsupported flag fails visibly rather than falling back to --sandbox off.
+				...(inspect ? ["--sandbox", "read-only", "--permission-mode", "dontAsk"] : ["--sandbox", "off", "--permission-mode", "bypassPermissions"]),
 				"--output-format",
 				"streaming-messages-json",
 				"--include-partial-messages",
@@ -836,8 +856,14 @@ async function executeGrok(
 			}
 			if (event.parent_tool_use_id !== undefined && event.parent_tool_use_id !== null) return;
 			if (event.type === "system" && event.subtype === "init") {
-				if (event.permissionMode !== "bypassPermissions") {
-					throw new Error("Grok did not apply the required bypassPermissions mode; check Grok policy/configuration.");
+				// Review asks for dontAsk, but `--sandbox read-only` in argv is the real boundary: another
+				// restricting mode is not a downgrade, and only auto-approval means the request was
+				// ignored. Both paths fail closed when the mode is missing, exactly like explain/btw.
+				const escalated = event.permissionMode === "bypassPermissions" || event.permissionMode === "always-approve";
+				if (inspect ? typeof event.permissionMode !== "string" || escalated : event.permissionMode !== "bypassPermissions") {
+					throw new Error(
+						`Grok did not apply the required ${inspect ? "restricted" : "bypassPermissions"} mode; check Grok policy/configuration.`,
+					);
 				}
 				if (typeof event.session_id === "string") initSessionId = event.session_id;
 			}
@@ -1007,14 +1033,15 @@ async function executeCodex(
 ): Promise<BackendOutcome> {
 	const isAdvisor = request.feature === "advisor";
 	const isBtw = request.feature === "btw";
+	const inspect = request.feature === "review";
 	const full = request.access === "workspace-full";
-	const deadlineMs = deadlineMsOverride ?? (full ? 610_000 : isBtw ? 130_000 : 125_000);
-	const action = request.feature === "review" ? "complete the guided review request" : isAdvisor ? "complete the advisor consultation" : isBtw ? "answer the side question" : "simplify the response";
-	const timeoutVerb = request.feature === "review" ? "during the guided review request" : isAdvisor ? "during the advisor consultation" : isBtw ? "during the side conversation" : "while simplifying the response";
-	const emptyTextMessage = request.feature === "review" ? "Codex returned no response for Guided Review." : isAdvisor ? "Codex returned no advice." : isBtw ? "Codex returned no answer for the side question." : "Codex returned no final explanation.";
+	const deadlineMs = deadlineMsOverride ?? backendDeadlineMs(request.feature, request.access);
+	const action = inspect ? "complete the guided review request" : isAdvisor ? "complete the advisor consultation" : isBtw ? "answer the side question" : "simplify the response";
+	const timeoutVerb = inspect ? "during the guided review request" : isAdvisor ? "during the advisor consultation" : isBtw ? "during the side conversation" : "while simplifying the response";
+	const emptyTextMessage = inspect ? "Codex returned no response for Guided Review." : isAdvisor ? "Codex returned no advice." : isBtw ? "Codex returned no answer for the side question." : "Codex returned no final explanation.";
 
 	if (signal.aborted) return { status: "cancelled", message: "Canceled." };
-	const runDirectory = full || isBtw ? undefined : await mkdtemp(join(tmpdir(), "pi-bro-"));
+	const runDirectory = full || isBtw || inspect ? undefined : await mkdtemp(join(tmpdir(), "pi-bro-"));
 	if (signal.aborted) {
 		if (runDirectory) await rm(runDirectory, { recursive: true, force: true });
 		return { status: "cancelled", message: "Canceled." };
@@ -1180,7 +1207,7 @@ async function executeMuse(
 	const isBtw = request.feature === "btw";
 	const inspect = request.feature === "review";
 	const full = request.access === "workspace-full";
-	const deadlineMs = deadlineMsOverride ?? (full || inspect ? 610_000 : isBtw ? 130_000 : 125_000);
+	const deadlineMs = deadlineMsOverride ?? backendDeadlineMs(request.feature, request.access);
 	const action = request.feature === "review" ? "complete the guided review request" : isAdvisor ? "complete the advisor consultation" : isBtw ? "answer the side question" : "simplify the response";
 	const timeoutVerb = request.feature === "review" ? "during the guided review request" : isAdvisor ? "during the advisor consultation" : isBtw ? "during the side conversation" : "while simplifying the response";
 	const emptyTextMessage = request.feature === "review" ? "Muse returned no response for Guided Review." : isAdvisor ? "Muse returned no advice." : isBtw ? "Muse returned no answer for the side question." : "Muse returned no final explanation.";
@@ -1369,10 +1396,6 @@ export async function execute(
 		(request.feature !== "btw" && request.continuation)
 	) return { status: "failure", message: "Unsupported execution request: check feature access, workspace cwd and continuation." };
 	const backend = (selection as { backend?: unknown }).backend;
-	if (request.feature === "review") {
-		const error = reviewBackendError(String(backend ?? "agy"));
-		if (error) return { status: "failure", message: error };
-	}
 	// An explicit tag guard: a stale or corrupt runtime tag must fail, never fall through to Agy.
 	if (backend !== undefined && backend !== "agy" && backend !== "claude" && backend !== "grok" && backend !== "codex" && backend !== "muse") {
 		return { status: "failure", message: `Unknown backend ${JSON.stringify(backend)}: pick Agy, Claude, Grok, Codex or Muse in \`/bro config\`.` };