chainlesschain 0.162.61 → 0.162.65

package/src/commands/review.js

@@ -0,0 +1,463 @@
+/**
+ * cc review — diff-first code review (Claude-Code `/code-review` parity).
+ *
+ *   cc review                      review the working tree vs HEAD
+ *   cc review --staged             review staged changes only (git diff --cached)
+ *   cc review --base main          review this branch vs main (main...HEAD)
+ *   cc review --range A..B         review an explicit revision range
+ *   cc review high                 broader, more thorough pass (effort tier)
+ *   cc review --fix                apply fixes to the working tree (reversible)
+ *   cc review --security           security-focused review (/security-review)
+ *   cc review --simplify           cleanup-only review (/simplify), no bug hunt
+ *
+ * "Diff-first" means the changed lines are collected with git and handed to the
+ * agent up front, so the review is anchored on what actually changed instead of
+ * the whole repo. The agent still has read/search tools to open surrounding code
+ * for context.
+ *
+ * Two modes:
+ *  - review-only (default): runs in PLAN permission mode → the agent is clamped
+ *    to read-only tools and CANNOT modify files. It emits a Markdown findings
+ *    report on stdout.
+ *  - --fix: runs in acceptEdits mode with auto-checkpointing ON, so the agent
+ *    applies the fixes directly; every file edit is captured as a git-plumbing
+ *    shadow commit first, so the whole pass is reversible with `cc checkpoint
+ *    restore <id>`.
+ *
+ * Requires a git work tree (the diff is the input). LLM defaults follow
+ * .chainlesschain/config.json `llm` exactly like `cc agent` / `cc ask`.
+ */
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import chalk from "chalk";
+import { logger } from "../lib/logger.js";
+
+/** Diffs larger than this are truncated before going to the model. */
+const MAX_DIFF_CHARS = 200_000;
+/** Per-untracked-file and total caps when inlining brand-new files. */
+const MAX_UNTRACKED_FILE_CHARS = 32_000;
+const MAX_UNTRACKED_TOTAL_CHARS = 128_000;
+
+const VALID_EFFORTS = Object.freeze(["low", "medium", "high"]);
+
+/**
+ * Run git with an argv array (no shell → no quoting hazards). UTF-8 in/out.
+ * Returns trimmed stdout; throws with git's stderr on failure.
+ */
+function gitCli(args, { cwd } = {}) {
+  const res = spawnSync("git", args, {
+    cwd,
+    encoding: "utf-8",
+    windowsHide: true,
+    maxBuffer: 256 * 1024 * 1024,
+  });
+  if (res.error) throw res.error;
+  if (res.status !== 0) {
+    const msg = (res.stderr || res.stdout || "").toString().trim();
+    throw new Error(msg || `git ${args.join(" ")} failed (exit ${res.status})`);
+  }
+  return (res.stdout || "").toString();
+}
+
+function isGitRepo(cwd, git = gitCli) {
+  try {
+    return git(["rev-parse", "--is-inside-work-tree"], { cwd }).trim() === "true";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Build the `git diff` argv for the requested scope. Pure.
+ *
+ * @param {object} opts { staged, base, range, paths }
+ * @param {boolean} [stat] append --stat for the summary variant
+ * @returns {{ args:string[], scope:string, label:string }}
+ */
+export function resolveDiffArgs(opts = {}, stat = false) {
+  const { staged, base, range, paths } = opts;
+  let args;
+  let scope;
+  let label;
+  if (range) {
+    args = ["diff", range];
+    scope = "range";
+    label = `range ${range}`;
+  } else if (base) {
+    // three-dot: changes on HEAD since it diverged from <base> (PR-style).
+    args = ["diff", `${base}...HEAD`];
+    scope = "base";
+    label = `${base}...HEAD`;
+  } else if (staged) {
+    args = ["diff", "--cached"];
+    scope = "staged";
+    label = "staged changes";
+  } else {
+    args = ["diff", "HEAD"];
+    scope = "working";
+    label = "working tree vs HEAD";
+  }
+  if (stat) args.push("--stat");
+  const cleanPaths = Array.isArray(paths) ? paths.filter(Boolean) : [];
+  if (cleanPaths.length) args.push("--", ...cleanPaths);
+  return { args, scope, label };
+}
+
+/** Normalize/validate an effort tier; defaults to "medium". Pure. */
+export function normalizeEffort(value) {
+  if (!value) return "medium";
+  const v = String(value).toLowerCase().trim();
+  if (!VALID_EFFORTS.includes(v)) {
+    throw new Error(
+      `Invalid effort "${value}". Expected one of: ${VALID_EFFORTS.join(", ")}.`,
+    );
+  }
+  return v;
+}
+
+/** Resolve the review lens from flags. Pure. */
+export function resolveReviewMode({ security, simplify } = {}) {
+  if (security && simplify) {
+    throw new Error("--security and --simplify are mutually exclusive.");
+  }
+  if (security) return "security";
+  if (simplify) return "simplify";
+  return "default";
+}
+
+const LENS = Object.freeze({
+  default:
+    "Review the changes for, in priority order: (1) CORRECTNESS bugs — logic " +
+    "errors, unhandled edge cases, null/undefined hazards, off-by-one, race " +
+    "conditions, missing/incorrect error handling, resource leaks, wrong API " +
+    "usage, broken invariants; and (2) CLEANUP — duplicated logic that could " +
+    "reuse an existing helper, code that could be simplified, and obvious " +
+    "inefficiencies. Correctness findings come first.",
+  security:
+    "This is a SECURITY review. Look only for security-relevant defects: " +
+    "injection (SQL / shell / path), broken authentication or authorization, " +
+    "secrets committed in code, weak or misused cryptography, SSRF, unsafe " +
+    "deserialization, path traversal, XSS, insecure randomness, missing input " +
+    "validation, TOCTOU races, and insecure defaults. Ignore style and " +
+    "non-security cleanups.",
+  simplify:
+    "This is a CLEANUP-ONLY review — do NOT hunt for bugs. Look for: duplicated " +
+    "logic that could reuse existing code, over-complicated code that can be " +
+    "simplified, inefficient patterns, and wrong-altitude abstractions. Only " +
+    "propose changes that PRESERVE behavior.",
+});
+
+const EFFORT_GUIDE = Object.freeze({
+  low:
+    "Report ONLY the few highest-confidence, highest-impact findings. Skip " +
+    "anything speculative or minor.",
+  medium:
+    "Report high-confidence findings across the whole diff. Skip speculative " +
+    "nitpicks.",
+  high:
+    "Be thorough across the whole diff. You may include lower-confidence " +
+    "findings, but clearly mark each as such.",
+});
+
+/**
+ * Build the review prompt embedding the diff. Pure.
+ *
+ * @param {object} o { diff, summary, effort, mode, fix, label, untrackedBlocks, truncated }
+ * @returns {string}
+ */
+export function buildReviewPrompt(o = {}) {
+  const {
+    diff = "",
+    summary = "",
+    effort = "medium",
+    mode = "default",
+    fix = false,
+    label = "working tree vs HEAD",
+    untrackedBlocks = "",
+    truncated = false,
+  } = o;
+
+  const tail = fix
+    ? "First identify the issues as above. Then APPLY the fixes directly with " +
+      "your edit tools — make the smallest change that resolves each issue and " +
+      "match the surrounding code's style. Every file edit is automatically " +
+      "checkpointed and reversible, so edit confidently. Stay within the " +
+      "reviewed change and its immediate dependencies — do not refactor " +
+      "unrelated code. Do NOT run destructive shell commands. When done, output " +
+      "a Markdown summary: what you changed (with `path:line`) and any issue you " +
+      "deliberately did NOT fix, each with a one-line reason."
+    : "Output a Markdown report. For each finding give: a severity " +
+      "(Critical / High / Medium / Low), the `path:line`, a one-line title, " +
+      "why it matters, and a concrete suggested fix (a short code snippet when " +
+      "it helps). Group findings by severity, most severe first. If nothing is " +
+      "worth raising, say so plainly. Do NOT modify any files — this is a " +
+      "review only.";
+
+  return [
+    `You are an expert code reviewer. ${LENS[mode]}`,
+    EFFORT_GUIDE[effort],
+    "",
+    `The change under review is the ${label}, shown below as a unified diff. ` +
+      "Before judging a hunk, use your read/search tools to open the " +
+      "surrounding code so your findings reflect real context, not just the " +
+      "diff window.",
+    "",
+    summary ? "Diffstat:\n```\n" + summary.trim() + "\n```\n" : "",
+    "Unified diff:",
+    "```diff",
+    truncated
+      ? diff + "\n\n[... diff truncated — review what is shown; note the cutoff]"
+      : diff,
+    "```",
+    untrackedBlocks ? "\n" + untrackedBlocks : "",
+    "",
+    tail,
+  ]
+    .filter((s) => s !== "")
+    .join("\n");
+}
+
+/**
+ * Collect untracked files (working scope only) and render them as labeled
+ * "new file" blocks so brand-new code is reviewed too (git diff HEAD omits it).
+ */
+function collectUntracked(cwd, git) {
+  let list = [];
+  try {
+    list = git(["ls-files", "--others", "--exclude-standard"], { cwd })
+      .split("\n")
+      .map((s) => s.trim())
+      .filter(Boolean);
+  } catch {
+    return { blocks: "", files: [], skipped: [] };
+  }
+  if (!list.length) return { blocks: "", files: [], skipped: [] };
+
+  const parts = [];
+  const included = [];
+  const skipped = [];
+  let total = 0;
+  for (const rel of list) {
+    if (total >= MAX_UNTRACKED_TOTAL_CHARS) {
+      skipped.push(rel);
+      continue;
+    }
+    let content;
+    try {
+      content = fs.readFileSync(path.resolve(cwd, rel), "utf-8");
+    } catch {
+      skipped.push(rel);
+      continue;
+    }
+    // Skip files that look binary (NUL byte in the first chunk).
+    if (content.includes("\u0000")) {
+      skipped.push(rel);
+      continue;
+    }
+    let body = content;
+    if (body.length > MAX_UNTRACKED_FILE_CHARS) {
+      body = body.slice(0, MAX_UNTRACKED_FILE_CHARS) + "\n[... file truncated]";
+    }
+    total += body.length;
+    included.push(rel);
+    parts.push(`New file \`${rel}\`:\n\`\`\`\n${body}\n\`\`\``);
+  }
+  return {
+    blocks: parts.length ? "Untracked new files:\n\n" + parts.join("\n\n") : "",
+    files: included,
+    skipped,
+  };
+}
+
+/**
+ * Core review run — collects the diff and dispatches one headless agent turn.
+ * Deps are injected for tests (git / runAgentHeadless / config helpers).
+ *
+ * @returns {Promise<{exitCode:number, isError:boolean, scope:string, empty?:boolean}>}
+ */
+export async function runReview(options = {}, deps = {}) {
+  const cwd = options.cwd || process.cwd();
+  const git = deps.git || gitCli;
+  const repoCheck = deps.isGitRepo || isGitRepo;
+
+  if (!repoCheck(cwd, git)) {
+    throw new Error(
+      "cc review needs a git work tree (the diff is the review input).",
+    );
+  }
+
+  const effort = normalizeEffort(options.effort);
+  const mode = resolveReviewMode(options);
+  const fix = options.fix === true;
+
+  const scopeOpts = {
+    staged: options.staged === true,
+    base: options.base || null,
+    range: options.range || null,
+    paths: options.paths || [],
+  };
+
+  const { args: diffArgs, scope, label } = resolveDiffArgs(scopeOpts, false);
+  const { args: statArgs } = resolveDiffArgs(scopeOpts, true);
+
+  let diff = "";
+  let summary = "";
+  try {
+    diff = git(diffArgs, { cwd });
+    summary = git(statArgs, { cwd });
+  } catch (err) {
+    throw new Error(`git diff failed: ${err.message}`);
+  }
+
+  // Untracked new files only matter for the default working scope; staged /
+  // base / range are already fully described by git.
+  let untracked = { blocks: "", files: [], skipped: [] };
+  if (scope === "working" && options.untracked !== false) {
+    untracked = collectUntracked(cwd, git);
+  }
+
+  const hasDiff = Boolean(diff.trim());
+  const hasUntracked = Boolean(untracked.blocks);
+  if (!hasDiff && !hasUntracked) {
+    return { exitCode: 0, isError: false, scope, empty: true };
+  }
+
+  const truncated = diff.length > MAX_DIFF_CHARS;
+  if (truncated) diff = diff.slice(0, MAX_DIFF_CHARS);
+
+  const prompt = buildReviewPrompt({
+    diff: hasDiff ? diff : "(no tracked changes)",
+    summary,
+    effort,
+    mode,
+    fix,
+    label,
+    untrackedBlocks: untracked.blocks,
+    truncated,
+  });
+
+  // LLM defaults: honor .chainlesschain/config.json `llm` like cc agent/ask.
+  // Explicit flags win. Best-effort — never block the review.
+  try {
+    const loadConfig = deps.loadConfig || (await import("../lib/config-manager.js")).loadConfig;
+    const { applyConfigLlmDefaults } =
+      deps.applyConfigLlmDefaults
+        ? { applyConfigLlmDefaults: deps.applyConfigLlmDefaults }
+        : await import("../lib/llm-config-defaults.js");
+    applyConfigLlmDefaults(options, loadConfig().llm || {}, {
+      explicitModel: options.model,
+    });
+  } catch {
+    // fall back to runner defaults
+  }
+
+  // review-only → plan mode (clamped to read-only tools, cannot mutate).
+  // --fix     → acceptEdits + auto-checkpoint (reversible edits).
+  const permissionMode = fix ? "acceptEdits" : "plan";
+  const autoCheckpoint = fix && options.checkpoint !== false;
+  const defaultMaxTurns = fix ? 40 : 20;
+  const maxTurns = Number.isFinite(options.maxTurns)
+    ? options.maxTurns
+    : defaultMaxTurns;
+
+  const run = deps.runAgentHeadless ||
+    (await import("../runtime/headless-runner.js")).runAgentHeadless;
+
+  const outcome = await run({
+    prompt,
+    model: options.model,
+    provider: options.provider,
+    baseUrl: options.baseUrl,
+    apiKey: options.apiKey,
+    outputFormat: options.outputFormat || "text",
+    permissionMode,
+    autoCheckpoint,
+    checkpointSession: options.checkpointSession || `review-${scope}`,
+    maxTurns,
+    cwd,
+    // The diff carries `@@` hunk markers and may contain `@tokens`; never run
+    // the @file-reference expander over it.
+    expandFileRefs: false,
+  });
+
+  return { ...outcome, scope, empty: false };
+}
+
+export function registerReviewCommand(program) {
+  program
+    .command("review [effort]")
+    .description(
+      "Diff-first code review of your changes (Claude-Code /code-review parity)",
+    )
+    .option("--staged", "Review staged changes only (git diff --cached)")
+    .option("--base <ref>", "Review this branch vs a base ref (<ref>...HEAD)")
+    .option("--range <range>", "Review an explicit revision range (e.g. A..B)")
+    .option(
+      "--paths <paths...>",
+      "Limit the review to these paths (repeatable)",
+    )
+    .option("-e, --effort <level>", "low | medium | high (default: medium)")
+    .option("--fix", "Apply the fixes to the working tree (auto-checkpointed)")
+    .option("--security", "Security-focused review (/security-review parity)")
+    .option("--simplify", "Cleanup-only review, no bug hunt (/simplify parity)")
+    .option("--no-untracked", "Skip untracked new files (working scope)")
+    .option("--no-checkpoint", "With --fix: do not auto-checkpoint before edits")
+    .option("--model <model>", "Override the review model")
+    .option("--provider <provider>", "Override the LLM provider")
+    .option("--base-url <url>", "Override the API base URL")
+    .option("--api-key <key>", "Override the API key")
+    .option("--max-turns <n>", "Cap agent loop iterations")
+    .option("--json", "Emit the agent result envelope as JSON")
+    .action(async (effortArg, options) => {
+      try {
+        const merged = {
+          ...options,
+          effort: options.effort || effortArg,
+          // commander stores --no-untracked as untracked:false, --no-checkpoint
+          // as checkpoint:false; pass them through unchanged.
+          maxTurns: options.maxTurns
+            ? parseInt(options.maxTurns, 10)
+            : undefined,
+          outputFormat: options.json ? "json" : "text",
+          cwd: process.cwd(),
+        };
+
+        // Pre-flight messaging on stderr so stdout stays a clean payload.
+        const mode = resolveReviewMode(merged);
+        const effort = normalizeEffort(merged.effort);
+        const { label } = resolveDiffArgs({
+          staged: merged.staged,
+          base: merged.base,
+          range: merged.range,
+          paths: merged.paths,
+        });
+        const modeLabel =
+          mode === "security"
+            ? "security"
+            : mode === "simplify"
+              ? "cleanup-only"
+              : "bugs + cleanup";
+        logger.info(
+          chalk.gray(
+            `Reviewing ${label} · ${effort} effort · ${modeLabel}` +
+              (merged.fix ? " · applying fixes" : " · read-only"),
+          ),
+        );
+
+        const result = await runReview(merged, {});
+
+        if (result.empty) {
+          logger.log(chalk.gray("No changes to review."));
+          return;
+        }
+        if (result.isError) {
+          process.exitCode = result.exitCode || 1;
+        }
+      } catch (err) {
+        logger.error(chalk.red(`review failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+}

package/src/index.js

@@ -64,6 +64,7 @@ import { registerGoalCommand } from "./commands/goal.js";
 import { registerCommandCommand } from "./commands/command.js";
 import { registerCompactCommand } from "./commands/compact.js";
 import { registerLoopCommand } from "./commands/loop.js";
+import { registerReviewCommand } from "./commands/review.js";
 import { registerPermissionsCommand } from "./commands/permissions.js";
 import { registerOutputStyleCommand } from "./commands/output-style.js";
 import { registerStatuslineCommand } from "./commands/statusline.js";
@@ -477,6 +478,7 @@ export function createProgram(opts = {}) {
   registerCommandCommand(program);
   registerCompactCommand(program);
   registerLoopCommand(program);
+  registerReviewCommand(program);
   registerPermissionsCommand(program);
   registerOutputStyleCommand(program);
   registerStatuslineCommand(program);

package/src/lib/cost-budget.js

@@ -0,0 +1,109 @@
+/**
+ * cost-budget — a hard USD spend cap for unattended agent runs
+ * (Claude-Code `--max-budget-usd` parity).
+ *
+ * Where IterationBudget caps the number of agent-loop turns, CostBudget caps the
+ * estimated dollar cost: it accumulates the per-call cost (via llm-pricing) as
+ * token-usage events arrive and reports when the cap is reached, so the runner
+ * can stop BEFORE making another paid LLM call. Because a call's cost is only
+ * known after it returns, a run may overshoot by at most one call — it never
+ * starts a new turn once over budget.
+ *
+ * Local/free providers (ollama, …) and unpriced models cost $0 here, so a cap
+ * can never trigger for them; `shouldWarnInactive()` lets the caller surface a
+ * one-time "cap inactive" notice instead of silently doing nothing.
+ *
+ * Pure + dependency-light (only llm-pricing) so it is unit-testable without a
+ * real agent loop.
+ */
+
+import { estimateCost } from "./llm-pricing.js";
+
+const round = (n, dp = 6) => {
+  const f = Math.pow(10, dp);
+  return Math.round((Number(n) + Number.EPSILON) * f) / f;
+};
+
+/** Parse a `--max-budget-usd` value into a positive number, or null when unset. */
+export function parseBudgetUsd(value) {
+  if (value == null || value === "") return null;
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) {
+    throw new Error(
+      `Invalid --max-budget-usd "${value}". Expected a positive number of US dollars.`,
+    );
+  }
+  return n;
+}
+
+export class CostBudget {
+  /**
+   * @param {object} opts
+   * @param {number|null} [opts.limitUsd] cap in USD; null/≤0 → disabled
+   * @param {object} [opts.table]         merged price table (mergePricing output)
+   */
+  constructor({ limitUsd = null, table = undefined } = {}) {
+    const lim = Number(limitUsd);
+    this.limitUsd = Number.isFinite(lim) && lim > 0 ? lim : null;
+    this.table = table;
+    this.spentUsd = 0;
+    this.priced = false; // priced ≥1 non-free usage record
+    this.sawUnpriced = false; // saw tokens we couldn't price
+    this.sawFree = false; // saw a free/local provider
+    this._warned = false;
+  }
+
+  enabled() {
+    return this.limitUsd != null;
+  }
+
+  /**
+   * Fold one token-usage record into the running spend.
+   * @returns {object} the estimateCost() result for this record
+   */
+  add({ provider, model, usage } = {}) {
+    const est = estimateCost({
+      provider,
+      model,
+      inputTokens: usage?.input_tokens || 0,
+      outputTokens: usage?.output_tokens || 0,
+      table: this.table,
+    });
+    const tokens = (usage?.input_tokens || 0) + (usage?.output_tokens || 0);
+    if (est.free) {
+      this.sawFree = true;
+    } else if (est.matched) {
+      this.spentUsd = round(this.spentUsd + est.totalCost);
+      this.priced = true;
+    } else if (tokens > 0) {
+      this.sawUnpriced = true;
+    }
+    return est;
+  }
+
+  /** True once the running spend has reached/passed the cap. */
+  exceeded() {
+    return this.limitUsd != null && this.spentUsd >= this.limitUsd;
+  }
+
+  /** USD left under the cap (Infinity when disabled). */
+  remaining() {
+    return this.limitUsd == null
+      ? Infinity
+      : Math.max(0, round(this.limitUsd - this.spentUsd));
+  }
+
+  /**
+   * True the FIRST time we can tell the cap can't bite — a cap was set but every
+   * usage so far has been free/local or unpriced, so spend stays $0. Lets the
+   * caller print a one-time "cap inactive" warning instead of a silent no-op.
+   */
+  shouldWarnInactive() {
+    if (!this.enabled() || this._warned || this.priced) return false;
+    if (this.sawUnpriced || this.sawFree) {
+      this._warned = true;
+      return true;
+    }
+    return false;
+  }
+}

package/src/lib/ide-context.js

@@ -278,6 +278,13 @@ export function hasIdeOpenDiff(mcp) {
  * Run one blocking openDiff review in the connected IDE. Returns
  *   { outcome:"accepted", finalText|null }  — the IDE wrote the file itself
  *   { outcome:"rejected" }                  — nothing was written
+ *   { outcome:"changes-requested", comments, reviewedText }
+ *                                           — the user annotated the diff with
+ *                                             revision notes instead of
+ *                                             accepting/rejecting; nothing was
+ *                                             written and the caller should
+ *                                             feed `comments` back to the agent
+ *                                             so it revises and re-proposes.
  *   null                                    — IDE unavailable / transport
  *                                             error / malformed reply → the
  *                                             caller falls back to its normal
@@ -309,10 +316,53 @@ export async function requestIdeDiffApproval(mcp, req = {}) {
       finalText: typeof data.finalText === "string" ? data.finalText : null,
     };
   }
+  if (data?.outcome === "changes-requested") {
+    return {
+      outcome: "changes-requested",
+      comments: Array.isArray(data.comments) ? data.comments : [],
+      reviewedText:
+        typeof data.reviewedText === "string" ? data.reviewedText : null,
+    };
+  }
   if (data?.outcome === "rejected") return { outcome: "rejected" };
   return null; // anything else is not a verdict — fail safe to fallback
 }
 
+/**
+ * Render line-anchored review comments (from an openDiff "changes-requested"
+ * verdict) into a compact feedback block the agent can act on. Each comment is
+ * `{ line?, endLine?, lineText?, note }` with 0-based editor lines. Returns
+ * null when there is no actionable note. Pure — safe to unit-test.
+ */
+export function formatReviewComments(comments, { path: filePath } = {}) {
+  if (!Array.isArray(comments) || comments.length === 0) return null;
+  const lines = comments
+    .map((c) => {
+      if (!c || typeof c.note !== "string" || c.note.trim().length === 0) {
+        return null;
+      }
+      const start = Number.isInteger(c.line) ? c.line + 1 : null; // 0→1-based
+      const end = Number.isInteger(c.endLine) ? c.endLine + 1 : start;
+      const where =
+        start != null
+          ? end != null && end !== start
+            ? `lines ${start}-${end}`
+            : `line ${start}`
+          : "(general)";
+      const anchor =
+        typeof c.lineText === "string" && c.lineText.trim().length > 0
+          ? `  ⟪${c.lineText.trim().slice(0, 120)}⟫`
+          : "";
+      return `  • ${where}: ${c.note.trim()}${anchor}`;
+    })
+    .filter(Boolean);
+  if (lines.length === 0) return null;
+  const header = filePath
+    ? `Review comments on ${filePath}:`
+    : "Review comments:";
+  return `${header}\n${lines.join("\n")}`;
+}
+
 // ─── Explicit @selection / @diagnostics at-mentions (Claude-Code parity) ────
 //
 // The ambient `<ide-context>` block above shares the selection on every turn.