@dieulc/workflow 0.7.0 → 0.8.0

package/review.ts

@@ -78,10 +78,21 @@ export interface ReviewModeConfig {
   fallbackOnError: ReviewFallbackOnError;
   /** Max `review_explore` subagents per review round (cost ceiling). */
   exploreBudget: number;
+  /**
+   * Max chars of shared Plan Mode context in the pass-1 prompt (step 7).
+   * Diet default keeps the review fast; the truncation marker tells the
+   * reviewer to re-read via read/grep anything it relies on.
+   */
+  contextChars: number;
+  /** Max pruned entries handed to the context renderer. */
+  contextEntries: number;
+  /** Max chars kept per tool-result string when pruning entries. */
+  contextToolChars: number;
   /**
    * Optional wall-clock cap for a single review round, in milliseconds.
-   * 0 = unlimited (default). When unlimited, a pass ends on
-   * `review_pass_done`, the run settling, an abort, or a prompt error.
+   * 0 = unlimited (explicit opt-out). Default 300_000 (5 minutes, step 10):
+   * a hung reviewer must not hold the handoff forever; the settle race still
+   * ends a silent pass in seconds either way.
    */
   timeoutMs: number;
 }
@@ -92,8 +103,11 @@ export const DEFAULT_REVIEW_MODE_CONFIG: Readonly<ReviewModeConfig> = {
   passes: 2,
   verify: true,
   fallbackOnError: "skip",
-  exploreBudget: 3,
-  timeoutMs: 0,
+  exploreBudget: 1,
+  timeoutMs: 300_000,
+  contextChars: 15_000,
+  contextEntries: 30,
+  contextToolChars: 1_000,
 };
 
 const ROUNDS_MIN = 1;
@@ -104,6 +118,12 @@ const EXPLORE_MIN = 0;
 const EXPLORE_MAX = 8;
 const TIMEOUT_MIN = 0;
 const TIMEOUT_MAX = 3_600_000;
+const CONTEXT_CHARS_MIN = 1_000;
+const CONTEXT_CHARS_MAX = 60_000;
+const CONTEXT_ENTRIES_MIN = 1;
+const CONTEXT_ENTRIES_MAX = 120;
+const CONTEXT_TOOL_CHARS_MIN = 200;
+const CONTEXT_TOOL_CHARS_MAX = 4_000;
 
 /** A JSON object parsed from an untrusted source (settings file, fragment). */
 export type JsonObject = Record<string, unknown>;
@@ -161,6 +181,24 @@ export function coerceReviewModeConfig(
       base.exploreBudget,
     ),
     timeoutMs: clampInt(r.timeoutMs, TIMEOUT_MIN, TIMEOUT_MAX, base.timeoutMs),
+    contextChars: clampInt(
+      r.contextChars,
+      CONTEXT_CHARS_MIN,
+      CONTEXT_CHARS_MAX,
+      base.contextChars,
+    ),
+    contextEntries: clampInt(
+      r.contextEntries,
+      CONTEXT_ENTRIES_MIN,
+      CONTEXT_ENTRIES_MAX,
+      base.contextEntries,
+    ),
+    contextToolChars: clampInt(
+      r.contextToolChars,
+      CONTEXT_TOOL_CHARS_MIN,
+      CONTEXT_TOOL_CHARS_MAX,
+      base.contextToolChars,
+    ),
   };
 }
 
@@ -280,7 +318,11 @@ export function readReviewModeConfig(
 }
 
 /**
- * The single gate used by every Review Mode hook.
+ * The automatic-review gate: true only when the persisted
+ * `workflow.reviewMode.enabled` flag is on. This gates AUTOMATIC review
+ * only (background handoff kickoff, reviewer prefetch, planner prompt
+ * note). Manual one-shot commands (`/review`, `/review say|pause|resume|
+ * abort|status`) intentionally bypass this gate — see `canRunManualReview`.
  * Never throws.
  */
 export function isReviewEnabled(cwd: string, agentDir: string): boolean {
@@ -291,6 +333,31 @@ export function isReviewEnabled(cwd: string, agentDir: string): boolean {
   }
 }
 
+/**
+ * What caused a review round: `"auto"` is the background handoff audit
+ * (requires the persisted `enabled` flag); `"manual"` is an explicit
+ * user command (`/review`, `/review-resume` fresh-plan branch) and bypasses
+ * only the `enabled` check — limits, model and prompt still come from saved
+ * config. Never persisted; the manual path never flips `enabled`.
+ */
+export type ReviewTrigger = "auto" | "manual";
+
+/**
+ * The manual-review gate: true whenever review settings are readable,
+ * regardless of the persisted `enabled` flag. A one-shot `/review` uses the
+ * saved rounds/passes/verify/budget/timeout/model as-is and never flips
+ * `enabled`. Returns false only when settings cannot be read at all.
+ * Never throws.
+ */
+export function canRunManualReview(cwd: string, agentDir: string): boolean {
+  try {
+    readReviewModeConfig(cwd, agentDir);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Read-modify-write `workflow.reviewMode` into a settings file, preserving
  * every other key in that file (Pi owns settings.json — we must not clobber it).
@@ -707,9 +774,18 @@ export function shouldRouteInputToReviewer(input: {
   reviewEnabled: boolean;
   reviewActive: boolean;
   hasReviewerSession: boolean;
+  /**
+   * Live ad-hoc session override: true while a manual one-shot review
+   * owns a live reviewer session (`reviewSessionLive()` in index.ts).
+   * Lets `/review say` and plain-chat steering reach the reviewer even
+   * when the persisted `enabled` flag is off. Never persisted.
+   */
+  manualSessionActive?: boolean;
 }): boolean {
+  const allowed =
+    input.reviewEnabled === true || input.manualSessionActive === true;
   return (
-    input.reviewEnabled === true &&
+    allowed &&
     input.reviewActive === true &&
     input.hasReviewerSession === true
   );
@@ -747,6 +823,166 @@ export interface ReviewRoundResult {
   planHash: string;
   state: ReviewState;
   reason?: string;
+  /**
+   * The round never started because the host signal was already aborted.
+   * A pre-aborted signal is an abort, never a pause (see
+   * `classifyReviewExecution`).
+   */
+  abortedBeforeStart?: boolean;
+}
+
+/**
+ * How one executed review round ended. Used for user notices and for deciding
+ * whether a paused gated handoff settles. `"paused"` is the only outcome that
+ * keeps the handoff open; everything else is terminal.
+ */
+export type ReviewExecutionOutcome =
+  | "rewritten"
+  | "unchanged"
+  | "paused"
+  | "aborted"
+  | "skipped"
+  | "fallback";
+
+/** Result of one `/review`, `/review-resume` or gated handoff execution. */
+export interface ReviewExecutionResult {
+  /** Plan to hand off: the reviewer's rewrite or the author's text. */
+  planText: string;
+  outcome: ReviewExecutionOutcome;
+  /** Human-facing reason for paused / aborted / skipped / fallback. */
+  reason?: string;
+  /** True when `pausedReview` holds this revision and the gate stays open. */
+  paused: boolean;
+}
+
+/**
+ * Classify one round outcome from the pieces the orchestrator already knows.
+ *
+ * Invariant: a pre-aborted/stale host signal (`abortedBeforeStart`) is an
+ * abort, never a pause. Only an explicit pause snapshot may keep the gate
+ * open, so `paused` is decided by the caller from `pausedReview.planHash`.
+ */
+export function classifyReviewExecution(input: {
+  ok: boolean;
+  aborted: boolean;
+  abortedBeforeStart?: boolean;
+  paused: boolean;
+  planChanged: boolean;
+}): ReviewExecutionOutcome {
+  if (input.paused === true) return "paused";
+  if (input.ok === true) return input.planChanged ? "rewritten" : "unchanged";
+  if (input.aborted === true || input.abortedBeforeStart === true) {
+    return "aborted";
+  }
+  return "fallback";
+}
+
+/** True when a resume outcome ends the round (everything except a re-pause). */
+export function reviewResumeSettles(result: ReviewExecutionResult): boolean {
+  return result.outcome !== "paused";
+}
+
+/**
+ * Gate outcome for a settled resume. Only a real rewrite counts as reviewed;
+ * an unchanged plan, a skip, an abort or a fallback hands off the author's
+ * plan. `undefined` means "keep the gate parked" (the round paused again).
+ */
+export function reviewResumeGateOutcome(
+  result: ReviewExecutionResult,
+): "reviewed" | "unreviewed" | undefined {
+  if (result.outcome === "paused") return undefined;
+  return result.outcome === "rewritten" ? "reviewed" : "unreviewed";
+}
+
+/** One accurate user-facing notice for a resume result. */
+export function reviewResumeNotice(result: ReviewExecutionResult): string {
+  const reason = result.reason ? ` (${result.reason})` : "";
+  switch (result.outcome) {
+    case "paused":
+      return "Review paused again — /review-resume to continue, /review-abort to stop.";
+    case "rewritten":
+      return "Review finished — plan rewritten and saved.";
+    case "unchanged":
+      return "Review finished — the reviewer kept the plan as-is.";
+    case "aborted":
+      return "Review stopped — the author's plan stands.";
+    case "skipped":
+      return `Review skipped${reason} — the plan will be handed over as-is.`;
+    case "fallback":
+    default:
+      return `Review could not complete${reason} — the plan will be handed over unreviewed (run /review to retry).`;
+  }
+}
+
+/**
+ * The transcript line for the run that is about to start.
+ *
+ * `agent_start` fires for every prompt on the same child session, so it cannot
+ * distinguish a cold reviewer boot from a warm resume or a next round. The
+ * runtime knows both facts (`created`, `resumed`) at the moment it sends the
+ * prompt, and this helper turns them into one truthful line.
+ *
+ * `created` wins over `resumed`: a resume whose session had to be rebuilt (the
+ * reviewer model changed) really did start a new session, and saying so is more
+ * useful than claiming a warm resume that did not happen.
+ */
+export function reviewRunLabel(input: {
+  /** The runtime had to create a reviewer session for this round. */
+  created: boolean;
+  /** `/review-resume` is continuing a paused round on the warm session. */
+  resumed?: boolean;
+  /** 1 for the audit pass, 2 for the self-verification pass. */
+  pass?: 1 | 2;
+}): string {
+  if (input.pass === 2) return "reviewer verifying — pass 2";
+  if (input.created === true) {
+    return input.resumed === true
+      ? "reviewer restarted — new reviewer session"
+      : "reviewer started";
+  }
+  return input.resumed === true ? "reviewer resumed" : "reviewer continuing";
+}
+
+/**
+ * Prefix a Review Mode notice exactly once.
+ *
+ * Callers already speak in sentences ("no reviewer model configured …"), while
+ * a few sources carried their own `Review Mode: `/`Review Mode ` prefix. Blindly
+ * interpolating produced `Review Mode: Review Mode: …`. Idempotent by design:
+ * anything already starting with `Review Mode` is returned unchanged.
+ */
+export function reviewNoticeText(message: string): string {
+  const text = String(message ?? "").trim();
+  if (text.length === 0) return "Review Mode: ";
+  return /^Review Mode\b/.test(text) ? text : `Review Mode: ${text}`;
+}
+
+/** Whether `/review-resume` may reuse the paused round or must start fresh. */
+export type ReviewResumePlanChoice = "fresh" | "warm";
+
+/**
+ * Decide whether a paused review can still be resumed as-is.
+ *
+ * The plan *file* is not a reliable witness on its own: the reviewer writes its
+ * rewrite to that same file during the round (`review_submit_plan`), so after a
+ * pause during pass 2 the file no longer matches the text the round started
+ * with. Comparing against the hash captured at pause time means only a change
+ * made **after** the pause — an author edit — starts a fresh round.
+ *
+ * A missing file (or a snapshot from before this field existed) keeps today's
+ * behaviour: resume the paused text.
+ */
+export function reviewResumePlanChoice(input: {
+  /** Hash of the text the paused round was auditing. */
+  pausedPlanHash: string;
+  /** Plan-file hash captured when the pause was recorded. */
+  pausedFileHash?: string;
+  /** Plan-file hash read by `/review-resume`; undefined when the file is gone. */
+  currentFileHash?: string;
+}): ReviewResumePlanChoice {
+  if (input.currentFileHash === undefined) return "warm";
+  const baseline = input.pausedFileHash ?? input.pausedPlanHash;
+  return input.currentFileHash === baseline ? "warm" : "fresh";
 }
 
 const DISPOSITIONS: readonly ReviewDisposition[] = [
@@ -926,7 +1162,7 @@ export function applySubmittedPlan(
 
   try {
     options.notify?.(
-      `Review Mode submitted the plan (${options.verdict}, ${options.findings.length} finding${
+      `submitted the plan (${options.verdict}, ${options.findings.length} finding${
         options.findings.length === 1 ? "" : "s"
       })`,
       "info",
@@ -993,6 +1229,10 @@ function deferredWait<T>(
 ): Promise<T | undefined> {
   const existing = current();
   if (existing !== undefined) return Promise.resolve(existing);
+  // A signal that is already aborted must resolve immediately: its `abort`
+  // event has already fired, so a listener registered below would never run
+  // and the caller (the gated handoff) would wait forever.
+  if (signal?.aborted === true) return Promise.resolve(undefined);
   return new Promise<T | undefined>((resolve) => {
     let settled = false;
     let timer: ReturnType<typeof setTimeout> | undefined;
@@ -1073,6 +1313,260 @@ export function createReviewRoundGate(): ReviewRoundGate {
   };
 }
 
+// ── Gated handoff (plan 2026-10-23 follow-up) ───────────────────────────
+//
+// The handoff waits for the review instead of racing it: `runHandoff`
+// awaits this gate, and `/review-resume` / `/review-abort` / teardown
+// settle it. A pause does NOT resolve the gate — the waiter keeps waiting
+// for the resume/abort outcome. Exactly-once: the first `resolve` wins;
+// a reload drops the gate (in-memory only), so a fresh `agent_end` simply
+// reviews again instead of rendering a phantom handoff.
+
+/** Lifecycle of the gated handoff review phase (in-memory, never persisted). */
+export type ReviewHandoffPhase = "idle" | "auditing" | "paused";
+
+/** How the gated review phase ended, for handoff rendering. */
+export type ReviewHandoffOutcome = "reviewed" | "unreviewed";
+
+/** The settled value the handoff renderer consumes. */
+export interface ReviewHandoffResult {
+  outcome: ReviewHandoffOutcome;
+  /** Final plan text; `undefined` means "keep the author's draft". */
+  planText: string | undefined;
+}
+
+export interface ReviewHandoffGate {
+  /** Clear the slot for a new gated phase. */
+  reset(): void;
+  /** Settle the gate; the first call wins, later calls are no-ops. */
+  resolve(result: ReviewHandoffResult): void;
+  /** True once `resolve` has run. */
+  settled(): boolean;
+  /** Latest settled result, if any (read-only peek for the waiter). */
+  peek(): ReviewHandoffResult | undefined;
+  /**
+   * Await settlement. Resolves `undefined` if the caller's signal aborts
+   * first — the handoff then falls back to the author's draft.
+   */
+  wait(signal?: AbortSignal): Promise<ReviewHandoffResult | undefined>;
+}
+
+export function createReviewHandoffGate(): ReviewHandoffGate {
+  let result: ReviewHandoffResult | undefined;
+  let waiters: Array<(value: ReviewHandoffResult | undefined) => void> = [];
+  return {
+    reset() {
+      result = undefined;
+      waiters = [];
+    },
+    resolve(r) {
+      if (result !== undefined) return;
+      result = r;
+      for (const resolve of waiters.splice(0)) {
+        try {
+          resolve(r);
+        } catch {
+          /* ignore */
+        }
+      }
+    },
+    settled() {
+      return result !== undefined;
+    },
+    peek() {
+      return result;
+    },
+    wait: (signal) =>
+      deferredWait<ReviewHandoffResult>(
+        () => result,
+        (resolve) => waiters.push(resolve),
+        undefined,
+        signal,
+      ),
+  };
+}
+
+/**
+ * Pure ESC-routing decision for the review input listener.
+ *
+ * The caller pre-filters raw input (`isKeyRelease` / `matchesKey(data,
+ * Key.escape)`); this decides from round state only: pause exactly once per
+ * round — a press while no round runs, or while already paused, falls
+ * through so the editor, questionnaire and handoff selector keep ESC.
+ */
+export function shouldPauseReviewOnEscape(input: {
+  roundActive: boolean;
+  paused: boolean;
+}): boolean {
+  return input.roundActive === true && input.paused !== true;
+}
+
+/** What the review ESC listener should do with one key press. */
+export type ReviewEscapeAction = "pause" | "swallow" | "pass";
+
+/**
+ * Route an ESC press while a review owns the turn.
+ *
+ * - A live, unpaused round pauses (exactly once per round).
+ * - A paused **gated** handoff swallows ESC with a hint: letting it reach the
+ *   editor aborts the parked parent turn and poisons `ctx.signal` for every
+ *   later `/review-resume` (the 2026-10-25 stall). `/review-abort` is the
+ *   explicit exit.
+ * - Everything else passes ESC through to the editor / questionnaire / handoff
+ *   selector.
+ */
+export function reviewEscapeAction(input: {
+  roundActive: boolean;
+  paused: boolean;
+  gatedPause: boolean;
+}): ReviewEscapeAction {
+  if (
+    shouldPauseReviewOnEscape({
+      roundActive: input.roundActive,
+      paused: input.paused,
+    })
+  ) {
+    return "pause";
+  }
+  if (input.paused === true && input.gatedPause === true) return "swallow";
+  return "pass";
+}
+
+/**
+ * Footer segment for a live review phase, composed into the single
+ * `"workflow"` status by `updateStatus`. Empty when no review is live, so
+ * callers can append unconditionally.
+ */
+export function reviewFooterSegment(
+  state: ReviewState | undefined,
+  paused: boolean,
+): string {
+  if (paused) return "🔍 review paused — /review-resume to continue";
+  if (!state) return "";
+  return reviewStateSummary(state);
+}
+
+/**
+ * Whether the review status surfaces (footer segment and status widget) should
+ * be visible at all.
+ *
+ * A review owns the turn only while a round is in flight (including the
+ * cold-start `activeReview` window before `isRoundActive()` flips) or a pause
+ * exists. `reviewState` alone is deliberately NOT enough: it is retained after
+ * a round for `/review-status` and the REVIEW SUMMARY band, and using it to
+ * drive the widget left a stale "🔍 review … aborted" line in Plan/Build mode.
+ */
+export function reviewStatusVisible(input: {
+  roundInFlight?: boolean;
+  roundActive?: boolean;
+  paused?: boolean;
+}): boolean {
+  return (
+    input.roundInFlight === true ||
+    input.roundActive === true ||
+    input.paused === true
+  );
+}
+
+// ── Mode-switch lock (plan 2026-10-25) ───────────────────────────────
+//
+// While a review owns the turn, mode transitions are refused: switching to
+// Build mid-review would swap the tool set and suspend the reviewer, and
+// switching to Default would leave the reviewer running outside Plan Mode.
+// The lock is a PROJECTION over existing state (never persisted), so every
+// existing exit — land, fail, pause/resume, abort, suspend, teardown —
+// releases it automatically. The post-review handoff prompt is deliberately
+// NOT part of the lock: the independent reviewer has already finished.
+
+/** Which mode-switch lock is active, if any. Derived, never persisted. */
+export type ReviewModeLockKind = "running" | "paused";
+
+export interface ReviewModeLockInput {
+  /** `activeReview !== undefined` — set before the child session boots. */
+  roundInFlight?: boolean;
+  /** `reviewRuntime.isRoundActive()` at call time. */
+  roundActive?: boolean;
+  /** `pausedReview !== undefined`. */
+  paused?: boolean;
+  /** The gated handoff phase; `"auditing"` counts as running. */
+  gatePhase?: ReviewHandoffPhase;
+}
+
+/**
+ * Decide whether a mode transition must be refused.
+ *
+ * A real pause snapshot wins over a round that is still aborting: ESC has
+ * already been pressed, so the notice should tell the user how to resume.
+ * A live round wins over a stale gate phase: `/review-resume` clears the
+ * snapshot and starts the round before the parked handoff resets its phase,
+ * so `gatePhase === "paused"` must not mask the running reviewer. A bare
+ * paused gate (no round, no snapshot) is the fallback for the small window
+ * between an abort and the handoff continuation.
+ */
+export function reviewModeLockKind(
+  input: ReviewModeLockInput,
+): ReviewModeLockKind | undefined {
+  if (input.paused === true) return "paused";
+  if (input.roundInFlight === true || input.roundActive === true) {
+    return "running";
+  }
+  if (input.gatePhase === "paused") return "paused";
+  if (input.gatePhase === "auditing") return "running";
+  return undefined;
+}
+
+/**
+ * Phase to use when `/review-resume` starts a paused gated round.
+ * A gated pause becomes an active audit again; a manual review (idle gate)
+ * is unchanged. This keeps a second ESC able to demote auditing → paused.
+ */
+export function reviewGatePhaseOnResume(
+  phase: ReviewHandoffPhase,
+): ReviewHandoffPhase {
+  return phase === "paused" ? "auditing" : phase;
+}
+
+/**
+ * Whether the gated handoff may park on the review gate.
+ *
+ * Invariant: parking requires all three — a paused phase, a pause snapshot for
+ * the current revision, and an unsettled gate. A phase without a snapshot (a
+ * stale/implicit pause) could never be released by `/review-resume`, so the
+ * handoff must settle with the author's plan instead of waiting forever.
+ */
+export function reviewHandoffParks(input: {
+  phase: ReviewHandoffPhase;
+  paused: boolean;
+  settled: boolean;
+}): boolean {
+  return (
+    input.phase === "paused" &&
+    input.paused === true &&
+    input.settled !== true
+  );
+}
+
+/** One short notice for a blocked mode transition. */
+export function reviewModeLockNotice(kind: ReviewModeLockKind): string {
+  return kind === "paused"
+    ? "Review is paused — mode switching stays locked. /review-resume to continue, /review-abort to stop, /review-mode off to end review."
+    : "Review is running — mode switching is locked. ESC or /review-pause to pause, /review-resume to continue, /review-abort to stop, /review-mode off to end review.";
+}
+
+/** Footer marker appended to the single `"workflow"` status while locked. */
+export function reviewModeLockFooter(
+  kind: ReviewModeLockKind | undefined,
+): string {
+  return kind ? "🔒 modes locked" : "";
+}
+
+/** `/review-status` row describing the lock and its allowed exits. */
+export function reviewModeLockStatusLine(
+  kind: ReviewModeLockKind | undefined,
+): string {
+  return kind ? `  lock    : ${kind} — ${reviewModeLockNotice(kind)}` : "";
+}
+
 // ── Step 16: reviewer transcript stream ──────────────────────────────
 
 /** Default cap on retained pane lines (the panes are a rolling window). */
@@ -1281,6 +1775,11 @@ export function formatActionLabel(toolName: unknown, args: unknown): string {
  * `auto_retry_end` or an `agent_end` that stopped on `stopReason === "error"`
  * appends an `error` line — a dead provider is then visible in the pane during
  * the review instead of resurfacing later as a mysterious "no plan" failure.
+ *
+ * Run-start lines are NOT produced here. `agent_start` fires for every prompt on
+ * the same child session, so it cannot tell a cold boot from a warm resume or a
+ * next round; the runtime emits the truthful line with `reviewRunLabel` at the
+ * moment it sends the prompt.
  */
 export function translateReviewEvent(
   event: unknown,
@@ -1315,9 +1814,6 @@ export function translateReviewEvent(
     ];
   }
 
-  if (type === "agent_start") {
-    return [{ op: "new", kind: "status", text: "reviewer started" }];
-  }
   return providerErrorOps(e, type);
 }
 
@@ -1325,9 +1821,10 @@ export function translateReviewEvent(
  * Provider-error events → transcript lines, split out of
  * `translateReviewEvent` to keep the dispatcher flat:
  *
- * - `agent_end`        → status line, plus an `error` line when the run
+ * - `agent_end`        → neutral run-end line, plus an `error` line when the run
  *   stopped on `stopReason === "error"` (auto-retry disabled, or the first
- *   failure was not retryable).
+ *   failure was not retryable). "Run ended" is truthful for a finished,
+ *   aborted or paused run alike.
  * - `auto_retry_start` → notice carrying the provider's message (truncated).
  * - `auto_retry_end`   → `error` line when the retry budget is exhausted
  *   (`success: false`); a recovered retry (`success: true`) stays silent.
@@ -1340,7 +1837,7 @@ function providerErrorOps(
 ): ReviewTranscriptOp[] {
   if (type === "agent_end") {
     const ops: ReviewTranscriptOp[] = [
-      { op: "new", kind: "status", text: "reviewer finished this run" },
+      { op: "new", kind: "status", text: "reviewer run ended" },
     ];
     const failed = lastAssistantErrorStop(e.messages);
     if (failed) {
@@ -1484,15 +1981,18 @@ export const REVIEW_SYSTEM_PROMPT = [
   "",
   "## Tools",
   "",
-  "- `read`, `grep`, `find`, `ls` — inspect the repository freely. Always verify a",
-  "  claim about the codebase with these before you rely on it.",
+  "- `read`, `grep`, `find`, `ls` — inspect the repository freely. The pass-1",
+  "  prompt carries Plan Mode's file inventory and recon summaries: trust them",
+  "  for what they cover, and re-read the files your findings anchor (plus a",
+  "  spot check or two) before you cite them.",
   "- `review_bash` — a READ-ONLY/VERIFY shell on the same role allowlist Plan Mode",
   "  uses (ls, cat, rg, fd, jq, diff, stat, git status/log/diff/show/branch, npm",
   "  test, npm run lint/typecheck, eslint, tsc --noEmit, node --test, pytest, cargo",
   "  clippy, ...). Mutating commands, redirects, installs and builds are refused.",
   "  Verify a plan's claims by reading the code and, where useful, by running its",
   "  tests or linters — but never assert that something passes unless you ran it.",
-  "- `review_explore` — delegate focused read-only reconnaissance to subagents.",
+  "- `review_explore` — delegate focused read-only reconnaissance to subagents",
+  "  (rarely needed: the pass-1 prompt already carries Plan Mode's recon).",
   "- `review_submit_plan` — submit the final rewritten plan. This is the ONLY way",
   "  your work reaches the user. A review that never submits is a failed review.",
   "- `review_pass_done` — end the current pass with a verdict and your findings.",