🤖 feat: add review_pane_update tool + Assisted review toggle (#3331)

## Summary

Adds two new agent tools — `review_pane_update` and `review_pane_get` —
that let an agent flag specific code regions in the Review pane for the
user to review next. The Review pane gains an "Assisted" toggle that
filters to those hunks; flagged hunks are always pinned at the top in
agent-declared order, the agent's optional comment is rendered above
each hunk, and the hunk body is trimmed to just the flagged new-side
line range with the surrounding diff hidden behind a "Show N lines …"
affordance. Both new tools get purpose-built transcript renderers
instead of the generic JSON-dump fallback. The Review tab auto-focuses
on agent-flagged hunks and shows a pulsing Sparkles indicator while
there's unread agent focus pending. Tool state is persisted under the
workspace session dir so `add` semantics survive backend restarts.

## Background

When an agent makes a large or risky change, the user often wants to
know *where to look first*. Today there's no signal from the agent into
the review surface — every hunk has equal weight, and a 500-line diff
buries the 20 lines that actually matter. This feature gives the agent a
first-class way to say "review these regions, in this order, with this
context."

## Implementation

**Tools (single source of truth in `toolDefinitions.ts`):**

- `review_pane_update({ operation: "add" | "replace", hunks: [{ path,
comment? }] })` — paths use a familiar `path[:start-end]` syntax
(`"src/foo.ts"`, `"src/foo.ts:42"`, or `"src/foo.ts:10-20"`, new-side
line numbers). `replace` overwrites the set; `add` appends with
dedup-by-`path:range` (preferring the latest comment).
- `review_pane_get()` — returns the current set in declared order so the
agent can inspect before adding more.

**State model:**

- Backend tool state is persisted under
`<workspaceSessionDir>/assistedReview.json` (parallel to `todos.json`),
with writes serialized via `workspaceFileLocks` and `writeFileAtomic`.
The file is unlinked on a clear so a stale file can't shadow a fresh
start. `coerceAssistedReviewHunks` survives corrupted JSON per the
self-healing doctrine — bad data is treated as empty rather than thrown.
- `StreamingMessageAggregator.processToolResult` parses each successful
`review_pane_update` output and rebuilds `assistedReviewHunks` on the
frontend. Because the tool returns the *resulting* list directly,
replaying history naturally reconstructs final state on reload.
- Exposed via `WorkspaceStore.getAssistedReviewHunks(workspaceId)`,
consumed by `ReviewPanel` through `useSyncExternalStore`.

**Review pane UI:**

- One shared module `src/common/utils/review/assistedReview.ts` owns
parsing, matching, and formatting — reused by the tool handler,
aggregator, and panel.
- `applyFrontendFilters` gains an optional `isAssisted` predicate so the
existing read/search pipeline is untouched.
- `ReviewPanel`'s `filteredHunks` memo applies the existing sort, then
partitions into `[assistedBucket, rest]` preserving agent-declared
index, so assisted hunks are always pinned first regardless of the
toggle.
- `ReviewControls` shows an "Assisted ✦ (N)" toggle only when
`assistedCount > 0`, keeping the toolbar compact for normal sessions.
- `HunkViewer` renders the comment in an accent-bordered row above the
diff header; a hunk flagged without a comment gets a subtle left-border
accent.

**Range trimming + show-more:**

- New helper `sliceHunkByNewLineRange`
(`src/browser/utils/review/sliceHunkContent.ts`) walks the diff body
using the same algorithm as `groupDiffLines`, partitions lines into
`before` / `inside` / `after` (attaching `-` lines to the next visible
region; trailing `-` lines to the previous), and returns `null` for
no-op cases (full coverage, out-of-bounds, pure deletions, pure renames)
so the existing single-renderer path still applies.
- `HunkViewer` now renders the inside slice always; before/after stay
hidden behind a `ContextCollapseIndicator` that gained a `mode: "expand"
| "collapse"` prop, so "Show N lines above" and "Collapse N lines above"
share the same squiggle pattern.
- Agent-flagged hunks override the auto-collapse behavior that kicks in
for large hunks / heavy reviews — otherwise the assistance signal got
buried under "Click to expand".

**Chat-transcript renderers:**

- `ReviewPaneUpdateToolCall.tsx` (≈120 LOC) — collapsed header shows the
operation (Add / Replace / Cleared) + "N hunks pinned" + rejected count
when present. Expanded view lists each path:range with a
Sparkles-accented comment row. Prefers the *post-merge* result list so
dedup outcomes are visible.
- `ReviewPaneGetToolCall.tsx` (≈45 LOC) — single-line preview
("Inspected N pinned hunks"); no expand affordance because the full list
lives in the Review pane.
- Both are registered in `TOOL_REGISTRY` (`getToolComponent.ts`);
`TOOL_NAME_TO_ICON` maps `review_pane_update` → `Sparkles` and
`review_pane_get` → `ScanEye`.

**Focus mode + Review tab pizzazz:**

- The Assisted toggle now auto-flips ON the first time the agent flags
hunks in a session, so the Review pane lands directly on the critical
changes instead of the full diff. A ref-guarded latch makes the user's
subsequent manual toggles stick; a drop-to-zero (agent cleared its hint
set) re-arms the latch so the next batch of flagged hunks gets focus
again.
- `ReviewStats` gains an `unreadAssisted` field — the count of
agent-flagged hunks intersecting the current diff that the user hasn't
acked. Computed in `ReviewPanel` alongside the existing `readHunkCount`
summary and pushed through the unchanged `onStatsChange` callback.
- `ReviewTabLabel` renders a Sparkles pill in `--color-review-accent`
with `animate-pulse` when `unreadAssisted > 0`, alongside the existing
`read/total` badge. Stops pulsing once everything assisted is marked
read. Tooltip explains "N agent-flagged hunk(s) pending review."

Matching is exact on workspace-relative paths (with `oldPath` fallback
for renames), and overlap-based on new-side line numbers (old-side
fallback for pure deletions), so the syntax does what an agent would
naturally expect.

## Validation

- 42 new unit tests:
  - 12 for the parser/matcher (`assistedReview.test.ts`)
- 6 for `applyReviewPaneUpdate` semantics (add/replace, dedup, comment
normalization, rejection of malformed filters, clear-via-empty-replace)
- 7 for `sliceHunkByNewLineRange` (whole-hunk coverage, out of bounds,
pure deletions, context-only split, deletion grouping, empty-inside
short-circuit, boundary cases)
- 5 for `ReviewTabLabel` pizzazz indicator (presence/absence gating,
accent + pulse classes, singular/plural aria-labels, null-stats safety)
- 4 for `coerceAssistedReviewHunks` (non-arrays, missing/invalid path,
malformed ranges, empty-string comment)
- 4 for end-to-end persistence (restart-survives-state,
clear-unlinks-file, per-workspace isolation, corrupted-file self-heal)
- Full `make test` deltas: +42 passing tests, no new failures. The 21
`GitStatusStore` and 1 `NestedToolRenderer` cross-test interference
failures observed in full-suite runs are **pre-existing on baseline
`main`** and reproduce without these changes.

## Risks

Low. The new state is opt-in and entirely additive:

- The Assisted toggle, per-hunk comment row, range trimming, auto-focus
latch, and tab pizzazz pill are all conditional on the agent having
flagged something, so users who never see the tool fire get the
unchanged Review pane and tab strip.
- The slicer is a pure transform and returns `null` for any edge case it
doesn't fully handle, falling back to the unchanged full-hunk render
path.
- Ordering changes only when at least one hunk matches — the existing
file-order / last-edit sort still owns the rest of the list.
- The tools only persist a small JSON file under the workspace session
dir; no git or other filesystem side effects.
- `ContextCollapseIndicator`'s new `mode` prop defaults to `"collapse"`,
preserving existing call-site behavior.
- The auto-on Assisted effect is ref-latched so it won't churn against
user toggles; it only re-arms when the agent clears the hint set
entirely.
- File reads self-heal from corruption (treated as empty), so a
hand-edited / partial-write `assistedReview.json` can't brick the tool.

Touched files outside the feature scope:
`StreamingMessageAggregator.processToolResult` (added a guarded branch
alongside `todo_write`), `applyFrontendFilters` (added an optional
predicate), `ContextCollapseIndicator` (additive `mode` prop), and
`ReviewStats` (additive `unreadAssisted` field). All are narrowly scoped
and covered by existing or new tests.

---

_Generated with `mux` • Model: `anthropic:claude-opus-4-7` • Thinking:
`max` • Cost: `$26.13`_

<!-- mux-attribution: model=anthropic:claude-opus-4-7 thinking=max
costs=26.13 -->

Author: ammar-agent

docs/hooks/tools.mdx

@@ -587,6 +587,18 @@ If a value is too large for the environment, it may be omitted (not set). Mux al
 
 </details>
 
+<details>
+<summary>review_pane_update (4)</summary>
+
+| Env var                                | JSON path                | Type   | Description                                                                                                                                       |
+| -------------------------------------- | ------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MUX_TOOL_INPUT_HUNKS_<INDEX>_COMMENT` | `hunks[<INDEX>].comment` | string | Short note (~1 sentence) telling the user what to look at and why.                                                                                |
+| `MUX_TOOL_INPUT_HUNKS_<INDEX>_PATH`    | `hunks[<INDEX>].path`    | string | Filter in `path[:range]` form, e.g. "src/foo.ts" or "src/foo.ts:42-58". Path is workspace-relative; range uses new-file line numbers (inclusive). |
+| `MUX_TOOL_INPUT_HUNKS_COUNT`           | `hunks.length`           | number | Number of elements in hunks (List of hunks to flag for review.)                                                                                   |
+| `MUX_TOOL_INPUT_OPERATION`             | `operation`              | enum   | 'replace' overwrites the assisted set; 'add' appends to it.                                                                                       |
+
+</details>
+
 <details>
 <summary>skills_catalog_read (3)</summary>
 

src/browser/features/RightSidebar/CodeReview/ContextCollapseIndicator.tsx

@@ -4,24 +4,35 @@ interface ContextCollapseIndicatorProps {
   lineCount: number;
   onCollapse: (e: React.MouseEvent) => void;
   position: "above" | "below";
+  /**
+   * - "collapse" (default): button text reads "Collapse N lines …"; used to
+   *   hide previously-loaded context.
+   * - "expand": button text reads "Show N lines …"; used to reveal context
+   *   that is currently hidden (Assisted-review trim).
+   */
+  mode?: "collapse" | "expand";
 }
 
 /**
- * Visual indicator for collapsing expanded context lines.
+ * Visual indicator for collapsing/expanding context lines.
  * Uses the squiggly line pattern established in BashOutputCollapsedIndicator.
- * Placed between expanded context and the main hunk content.
+ * Used between the main hunk content and surrounding context.
  */
 export const ContextCollapseIndicator: React.FC<ContextCollapseIndicatorProps> = ({
   lineCount,
   onCollapse,
   position,
+  mode = "collapse",
 }) => {
+  const verb = mode === "collapse" ? "Collapse" : "Show";
+  const ariaLabel =
+    mode === "collapse" ? `Collapse context ${position}` : `Show context ${position}`;
   return (
     <div className="flex items-center justify-center">
       <button
         onClick={onCollapse}
         className="text-muted hover:bg-background-highlight inline-flex cursor-pointer items-center gap-1 rounded px-1.5 py-px transition-colors"
-        aria-label={`Collapse context ${position}`}
+        aria-label={ariaLabel}
       >
         {/* Squiggly line SVG - horizontal orientation for separator */}
         <svg
@@ -41,7 +52,7 @@ export const ContextCollapseIndicator: React.FC<ContextCollapseIndicatorProps> =
           />
         </svg>
         <span className="text-[10px] font-medium">
-          Collapse {lineCount} line{lineCount === 1 ? "" : "s"} {position}
+          {verb} {lineCount} line{lineCount === 1 ? "" : "s"} {position}
         </span>
         <svg
           className="text-border shrink-0"

src/browser/features/RightSidebar/CodeReview/HunkViewer.tsx

@@ -4,7 +4,7 @@
  */
 
 import React, { useState, useMemo } from "react";
-import { Check, Circle } from "lucide-react";
+import { Check, Circle, Sparkles } from "lucide-react";
 import type { DiffHunk, Review, ReviewNoteData } from "@/common/types/review";
 import { SelectableDiffRenderer } from "../../Shared/DiffRenderer";
 import type { ReviewActionCallbacks } from "../../Shared/InlineReviewNote";
@@ -25,6 +25,7 @@ import { formatRelativeTime } from "@/browser/utils/ui/dateTime";
 import { cn } from "@/common/lib/utils";
 import { ContextCollapseIndicator } from "./ContextCollapseIndicator";
 import { useReadMore } from "./useReadMore";
+import { sliceHunkByNewLineRange } from "@/browser/utils/review/sliceHunkContent";
 
 interface HunkViewerProps {
   hunk: DiffHunk;
@@ -51,6 +52,25 @@ interface HunkViewerProps {
   reviewActions?: ReviewActionCallbacks;
   /** Prefer a collapsed default for huge reviews so opening Review doesn't mount every diff line. */
   preferCollapsed?: boolean;
+  /**
+   * Optional comment from the agent (via `review_pane_update`) explaining
+   * why this hunk was flagged for review. Rendered above the hunk's header
+   * row when present.
+   */
+  assistedComment?: string;
+  /**
+   * Whether this hunk was flagged by the agent. Used to surface a subtle
+   * accent indicator on the hunk header even when no comment was provided.
+   */
+  isAssisted?: boolean;
+  /**
+   * When set, the hunk body is trimmed to just these new-side line numbers
+   * (inclusive) by default. Lines before/after the range hide behind a
+   * "Show N lines …" affordance that reuses the existing context-collapse
+   * indicator. Pass a stable reference (e.g. memoized lookup) to keep
+   * `React.memo` working.
+   */
+  visibleNewLineRange?: { start: number; end: number };
 }
 
 function renderHighlightedFilePath(
@@ -129,6 +149,9 @@ export const HunkViewer = React.memo<HunkViewerProps>(
     reviewActions,
     includeUncommitted,
     preferCollapsed = false,
+    assistedComment,
+    isAssisted = false,
+    visibleNewLineRange,
   }) => {
     // Ref for the hunk container to track visibility
     const hunkRef = React.useRef<HTMLDivElement>(null);
@@ -192,6 +215,25 @@ export const HunkViewer = React.memo<HunkViewerProps>(
       [hunk.filePath, searchConfig]
     );
 
+    // Assisted-review trim: when the agent flagged a specific new-side range,
+    // render only those lines by default and hide the surrounding diff behind
+    // a "Show N lines …" affordance. The slicer returns null when trimming
+    // would be a no-op (range covers the whole hunk, pure deletions, etc.),
+    // so the existing single-renderer path still applies in those cases.
+    const hunkSlice = useMemo(
+      () => (visibleNewLineRange ? sliceHunkByNewLineRange(hunk, visibleNewLineRange) : null),
+      [hunk, visibleNewLineRange]
+    );
+    const [showSliceBefore, setShowSliceBefore] = useState(false);
+    const [showSliceAfter, setShowSliceAfter] = useState(false);
+    // Reset show-more state when the underlying slice changes (e.g. the agent
+    // updates the assisted range, or the user navigates to a different hunk
+    // that reuses this memoized component instance).
+    React.useEffect(() => {
+      setShowSliceBefore(false);
+      setShowSliceAfter(false);
+    }, [hunkSlice]);
+
     // Persist manual expand/collapse state across remounts per workspace
     // Maps hunkId -> isExpanded for user's manual preferences
     // Enable listener to synchronize updates across all HunkViewer instances
@@ -205,7 +247,13 @@ export const HunkViewer = React.memo<HunkViewerProps>(
     const hasManualState = hunkId in expandStateMap;
     const manualExpandState = expandStateMap[hunkId];
 
-    const shouldAutoExpand = !isRead && !isLargeHunk && (!preferCollapsed || Boolean(isSelected));
+    // Agent-flagged hunks should default to expanded even when they're "large"
+    // or in a heavy review where everything else is collapsed — otherwise the
+    // assisted-review focus signal gets buried.
+    const shouldAutoExpand =
+      !isRead &&
+      (!isLargeHunk || Boolean(visibleNewLineRange)) &&
+      (!preferCollapsed || Boolean(isSelected) || Boolean(visibleNewLineRange));
 
     // Determine initial expand state (priority: manual > read status > size/review scale)
     const [isExpanded, setIsExpanded] = useState(() => {
@@ -301,7 +349,25 @@ export const HunkViewer = React.memo<HunkViewerProps>(
         tabIndex={0}
         data-hunk-id={hunkId}
       >
-        <div className="border-border-light font-monospace flex items-center gap-1.5 border-b px-2 py-1 text-[11px]">
+        {(assistedComment ?? isAssisted) && (
+          <div
+            className="border-review-accent/40 bg-review-accent/5 text-foreground flex items-start gap-2 border-b px-2 py-1.5 text-[11px] leading-[1.4]"
+            data-testid="hunk-assisted-comment"
+          >
+            <Sparkles aria-hidden="true" className="text-review-accent mt-[2px] h-3 w-3 shrink-0" />
+            {assistedComment ? (
+              <span className="min-w-0 break-words whitespace-pre-wrap">{assistedComment}</span>
+            ) : (
+              <span className="text-muted italic">Flagged by agent for review</span>
+            )}
+          </div>
+        )}
+        <div
+          className={cn(
+            "border-border-light font-monospace flex items-center gap-1.5 border-b px-2 py-1 text-[11px]",
+            isAssisted && !assistedComment && "border-l-review-accent border-l-2"
+          )}
+        >
           {onToggleRead && (
             <Tooltip>
               <TooltipTrigger asChild>
@@ -401,28 +467,104 @@ export const HunkViewer = React.memo<HunkViewerProps>(
               </>
             )}
 
-            {/* Original hunk content */}
-            <SelectableDiffRenderer
-              content={hunk.content}
-              filePath={hunk.filePath}
-              inlineReviews={inlineReviews}
-              oldStart={hunk.oldStart}
-              newStart={hunk.newStart}
-              fontSize="11px"
-              maxHeight="none"
-              className="rounded-none border-0 [&>div]:overflow-x-visible"
-              onReviewNote={onReviewNote}
-              onLineClick={() => {
-                const syntheticEvent = {
-                  currentTarget: { dataset: { hunkId } },
-                } as unknown as React.MouseEvent<HTMLElement>;
-                onClick?.(syntheticEvent);
-              }}
-              searchConfig={searchConfig}
-              enableHighlighting={isVisible}
-              onComposingChange={handleComposingChange}
-              reviewActions={reviewActions}
-            />
+            {/* Original hunk content (sliced when the agent flagged a range). */}
+            {(() => {
+              const renderBody = (content: string, oldStart: number, newStart: number) => (
+                <SelectableDiffRenderer
+                  content={content}
+                  filePath={hunk.filePath}
+                  inlineReviews={inlineReviews}
+                  oldStart={oldStart}
+                  newStart={newStart}
+                  fontSize="11px"
+                  maxHeight="none"
+                  className="rounded-none border-0 [&>div]:overflow-x-visible"
+                  onReviewNote={onReviewNote}
+                  onLineClick={() => {
+                    const syntheticEvent = {
+                      currentTarget: { dataset: { hunkId } },
+                    } as unknown as React.MouseEvent<HTMLElement>;
+                    onClick?.(syntheticEvent);
+                  }}
+                  searchConfig={searchConfig}
+                  enableHighlighting={isVisible}
+                  onComposingChange={handleComposingChange}
+                  reviewActions={reviewActions}
+                />
+              );
+
+              if (!hunkSlice) {
+                return renderBody(hunk.content, hunk.oldStart, hunk.newStart);
+              }
+
+              return (
+                <>
+                  {hunkSlice.beforeLineCount > 0 &&
+                    (showSliceBefore ? (
+                      <>
+                        {renderBody(
+                          hunkSlice.beforeContent,
+                          hunkSlice.beforeOldStart,
+                          hunkSlice.beforeNewStart
+                        )}
+                        <ContextCollapseIndicator
+                          lineCount={hunkSlice.beforeLineCount}
+                          onCollapse={(e) => {
+                            e.stopPropagation();
+                            setShowSliceBefore(false);
+                          }}
+                          position="above"
+                          mode="collapse"
+                        />
+                      </>
+                    ) : (
+                      <ContextCollapseIndicator
+                        lineCount={hunkSlice.beforeLineCount}
+                        onCollapse={(e) => {
+                          e.stopPropagation();
+                          setShowSliceBefore(true);
+                        }}
+                        position="above"
+                        mode="expand"
+                      />
+                    ))}
+                  {renderBody(
+                    hunkSlice.insideContent,
+                    hunkSlice.insideOldStart,
+                    hunkSlice.insideNewStart
+                  )}
+                  {hunkSlice.afterLineCount > 0 &&
+                    (showSliceAfter ? (
+                      <>
+                        <ContextCollapseIndicator
+                          lineCount={hunkSlice.afterLineCount}
+                          onCollapse={(e) => {
+                            e.stopPropagation();
+                            setShowSliceAfter(false);
+                          }}
+                          position="below"
+                          mode="collapse"
+                        />
+                        {renderBody(
+                          hunkSlice.afterContent,
+                          hunkSlice.afterOldStart,
+                          hunkSlice.afterNewStart
+                        )}
+                      </>
+                    ) : (
+                      <ContextCollapseIndicator
+                        lineCount={hunkSlice.afterLineCount}
+                        onCollapse={(e) => {
+                          e.stopPropagation();
+                          setShowSliceAfter(true);
+                        }}
+                        position="below"
+                        mode="expand"
+                      />
+                    ))}
+                </>
+              );
+            })()}
 
             {/* Expanded content below */}
             {downContent && (

src/browser/features/RightSidebar/CodeReview/ReviewControls.tsx

@@ -3,7 +3,7 @@
  */
 
 import React from "react";
-import { ArrowLeft, Maximize2 } from "lucide-react";
+import { ArrowLeft, Maximize2, Sparkles } from "lucide-react";
 import { usePersistedState } from "@/browser/hooks/usePersistedState";
 import { useTutorial } from "@/browser/contexts/TutorialContext";
 import {
@@ -42,6 +42,12 @@ interface ReviewControlsProps {
   isImmersive?: boolean;
   /** Toggle immersive review mode */
   onToggleImmersive?: () => void;
+  /**
+   * Number of agent-flagged "Assisted" hunks the agent has pinned via
+   * the `review_pane_update` tool. When zero, the Assisted toggle is hidden
+   * so the control bar stays compact for normal review sessions.
+   */
+  assistedCount?: number;
 }
 
 export const ReviewControls: React.FC<ReviewControlsProps> = ({
@@ -57,6 +63,7 @@ export const ReviewControls: React.FC<ReviewControlsProps> = ({
   lastRefreshFailure,
   isImmersive = false,
   onToggleImmersive,
+  assistedCount = 0,
 }) => {
   // Per-project default base (used for new workspaces in this project)
   const [defaultBase, setDefaultBase] = usePersistedState<string>(
@@ -89,6 +96,11 @@ export const ReviewControls: React.FC<ReviewControlsProps> = ({
     onFiltersChange((prev) => ({ ...prev, showReadHunks: checked }));
   };
 
+  const handleAssistedToggle = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const checked = e.target.checked;
+    onFiltersChange((prev) => ({ ...prev, assistedOnly: checked }));
+  };
+
   const handleSortChange = (e: React.ChangeEvent<HTMLSelectElement>) => {
     const sortOrder = e.target.value as ReviewSortOrder;
     onFiltersChange((prev) => ({ ...prev, sortOrder }));
@@ -186,6 +198,29 @@ export const ReviewControls: React.FC<ReviewControlsProps> = ({
         />
       </label>
 
+      {assistedCount > 0 && (
+        <>
+          <div className="bg-border-light h-3 w-px" />
+          <TooltipIfPresent
+            tooltip={`Show only the ${assistedCount} hunk${assistedCount === 1 ? "" : "s"} the agent flagged for review`}
+            side="bottom"
+          >
+            <label className="text-muted hover:text-foreground flex cursor-pointer items-center gap-1 whitespace-nowrap">
+              <Sparkles aria-hidden="true" className="text-review-accent h-3 w-3 shrink-0" />
+              <span>Assisted:</span>
+              <input
+                type="checkbox"
+                aria-label="Show only agent-flagged hunks"
+                checked={filters.assistedOnly}
+                onChange={handleAssistedToggle}
+                className="h-3 w-3 cursor-pointer"
+              />
+              <span className="text-dim text-[10px]">({assistedCount})</span>
+            </label>
+          </TooltipIfPresent>
+        </>
+      )}
+
       <div className="bg-border-light h-3 w-px" />
 
       <label className="text-muted flex items-center gap-1 whitespace-nowrap">