pullfrog 0.1.35 → 0.1.36

package/dist/cli.mjs

@@ -28230,7 +28230,7 @@ var require_cross_spawn = __commonJS({
     var cp = __require("child_process");
     var parse5 = require_parse3();
     var enoent = require_enoent();
-    function spawn5(command, args2, options) {
+    function spawn6(command, args2, options) {
       const parsed2 = parse5(command, args2, options);
       const spawned = cp.spawn(parsed2.command, parsed2.args, parsed2.options);
       enoent.hookChildProcess(spawned, parsed2);
@@ -28242,8 +28242,8 @@ var require_cross_spawn = __commonJS({
       result.error = result.error || enoent.verifyENOENTSync(result.status, parsed2);
       return result;
     }
-    module.exports = spawn5;
-    module.exports.spawn = spawn5;
+    module.exports = spawn6;
+    module.exports.spawn = spawn6;
     module.exports.sync = spawnSync6;
     module.exports._parse = parse5;
     module.exports._enoent = enoent;
@@ -96055,14 +96055,14 @@ var require_turndown_cjs = __commonJS({
         } else if (node2.nodeType === 1) {
           replacement = replacementForNode.call(self2, node2);
         }
-        return join26(output, replacement);
+        return join27(output, replacement);
       }, "");
     }
     function postProcess(output) {
       var self2 = this;
       this.rules.forEach(function(rule) {
         if (typeof rule.append === "function") {
-          output = join26(output, rule.append(self2.options));
+          output = join27(output, rule.append(self2.options));
         }
       });
       return output.replace(/^[\t\r\n]+/, "").replace(/[\t\r\n\s]+$/, "");
@@ -96074,7 +96074,7 @@ var require_turndown_cjs = __commonJS({
       if (whitespace.leading || whitespace.trailing) content = content.trim();
       return whitespace.leading + rule.replacement(content, node2, this.options) + whitespace.trailing;
     }
-    function join26(output, replacement) {
+    function join27(output, replacement) {
       var s1 = trimTrailingNewlines(output);
       var s2 = trimLeadingNewlines(replacement);
       var nls = Math.max(output.length - s1.length, replacement.length - s2.length);
@@ -101730,7 +101730,7 @@ import { dirname as dirname6 } from "node:path";
 // main.ts
 import { existsSync as existsSync8, readdirSync as readdirSync2 } from "node:fs";
 import { readFile as readFile5 } from "node:fs/promises";
-import { join as join25 } from "node:path";
+import { join as join26 } from "node:path";
 
 // agents/claude.ts
 import { execFileSync as execFileSync3 } from "node:child_process";
@@ -103001,7 +103001,7 @@ var import_semver = __toESM(require_semver2(), 1);
 // package.json
 var package_default = {
   name: "pullfrog",
-  version: "0.1.35",
+  version: "0.1.36",
   type: "module",
   bin: {
     pullfrog: "dist/cli.mjs",
@@ -103675,8 +103675,9 @@ HARD CONSTRAINTS (non-negotiable, regardless of orchestrator instructions):
 - Your FIRST action MUST source the diff for review. If the orchestrator's dispatch names a diff PATH on disk (e.g. \`diffPath\` / \`incrementalDiffPath\` from a prior \`checkout_pr\` call), \`read\` that path \u2014 do not invoke git at all. The on-disk diff is the authoritative scope, and dispatches almost always include one; recomputing it via git also fails on shallow GitHub Actions checkouts where the base ref may be unfetched. When BOTH a diff path and a base branch appear in your dispatch, path always wins. When the dispatch names an \`incrementalDiffPath\` alongside \`diffPath\`, prefer the incremental path for scope and consult the full diff only for line-number anchoring.
 - If (and only if) NO diff path was provided, the dispatch names a base branch. Run \`git diff --merge-base origin/<base>\` (single MCP call, captures committed + staged + unstaged work, excludes commits landed on \`origin/<base>\` since your branch forked). The read-only \`git\` MCP tool is the right surface for this \u2014 \`--merge-base\` is a flag git accepts directly, so no shell substitution is needed. Do NOT run bare \`git diff origin/<base>\` or two-dot \`git diff origin/<base>..HEAD\`: those are symmetric diffs that include the inverse of every commit on \`<base>\` your branch is behind, which is pure noise (and the git tool will reject those forms when the divergence is detected). Do NOT try to expand \`$(...)\` subshell forms via the git tool \u2014 it runs git directly without shell interpolation. If \`git diff --merge-base origin/<base>\` fails with \`ambiguous argument 'origin/<base>'\` or \`no merge base\`, the runner is a shallow single-branch checkout AND the orchestrator failed to fetch the base ref before dispatching you. Surface that in one line (which ref is missing, and that the orchestrator needs to fetch it with \`git fetch --no-tags --deepen=1000 origin <base>:refs/remotes/origin/<base>\` before re-dispatching) and stop. Do NOT run \`git fetch\` yourself \u2014 your read-only contract below forbids mutating shell, and the \`git_fetch\` MCP tool is state-changing and therefore prohibited. Do NOT call \`checkout_pr\`, do NOT fetch alternative refs, do NOT list branches or all-refs looking for the work, do NOT run \`gh pr list\`. The orchestrator's dispatch is the source of truth for scope.
 - If the on-disk diff path you were given is empty (or unreadable), that is a checkout / formatting failure on the orchestrator side \u2014 reply EXACTLY: \`no changes in dispatched diff \u2014 scope appears empty; orchestrator should verify checkout_pr output\` (naming the path), do NOT fall through to running \`git diff\` against guessed refs. If the merge-base diff (the fallback path) returns empty AND the orchestrator's dispatch claims there are changes to review, the most likely cause is a pre-commit Build-mode self-review: the orchestrator dispatched you before committing AND there are no uncommitted edits either. Reply EXACTLY: \`no changes detected \u2014 likely pre-commit Build self-review; orchestrator should commit then re-dispatch\` and stop. Do NOT guess PR numbers (e.g. by extrapolating from \`git log\` output), do NOT check out other PRs, do NOT fetch from forks. The empty diff is the diagnosis \u2014 surface it; do not work around it.
+- Once the mandatory first diff read returns a non-empty scope, batch each next dependency layer: emit all independent read-only file reads, greps, globs, and directory listings together in one assistant turn before awaiting their results. Include MCP queries only when their contract explicitly guarantees they are read-only; a \`get_*\` or \`list_*\` name alone is not proof. Keep dependent calls in later turns, after the results they depend on are available.
 - Read-only tools only. Do NOT write or edit files. Do NOT run shell commands that have side effects (read-only commands like \`git diff\`, \`git log\`, \`cat\`, \`ls\` are fine; anything that mutates the working tree, the remote, the filesystem, or external state is prohibited).
-- Do NOT call any state-changing MCP tool. State-changing means: posts a comment, pushes a branch, creates/updates a PR or issue, changes labels, resolves review threads, persists learnings, sets workflow output, installs dependencies, uploads files, kills processes, etc. Read-only MCP queries (\`get_*\`, \`list_*\`, the \`git\` tool for read-only subcommands like \`diff\`/\`log\`/\`merge-base\`, log inspection, diff retrieval) are fine.
+- Do NOT call any state-changing MCP tool. State-changing means: posts a comment, pushes a branch, creates/updates a PR or issue, changes labels, resolves review threads, persists learnings, sets workflow output, installs dependencies, uploads files, kills processes, etc. MCP tool names are not evidence of safety: only use queries whose contract explicitly guarantees no side effects. The \`git\` tool is fine only for read-only subcommands like \`diff\`/\`log\`/\`merge-base\`.
 - Do NOT spawn further subagents. You are a leaf reviewer; recursive dispatch pre-aggregates findings through an intermediate model and defeats the design.
 - Test for any tool call before invoking it: would this still be a no-op if reverted? If not, do not call it. Apply this test to tools added after this prompt was written \u2014 the rule is the invariant, not the enumeration.
 
@@ -103939,20 +103940,15 @@ For simple, well-defined tasks, skip the plan phase and go straight to build.`
      - **immediately** call \`${t2("resolve_review_thread")}\` with that thread's \`thread=\` value as \`thread_id\`. Resolve every thread where you (a) made the requested code change in full \u2014 partial fixes leave the thread open \u2014 OR (b) replied with a substantive answer the user explicitly asked for. Do NOT resolve threads where you pushed back on the request and the disagreement is unresolved; leave those open for the human to mediate.
    - call \`${t2("report_progress")}\` with a brief summary`
     },
-    // Review and IncrementalReview use a 0-or-2+ lens pattern. The default is
-    // 0 lenses (orchestrator handles the review solo). Multi-lens (2+
-    // reviewfrog subagents in parallel) only fires for substantive PRs or
-    // high-stakes-subsystem touches — and when it fires, ALL lenses must
-    // dispatch in a single assistant turn or the parallelism win disappears.
-    // We never dispatch exactly one lens: a single lens is just a worse,
-    // slower version of doing the work yourself.
+    // Review and IncrementalReview route the minimum reviewfrog specialists
+    // needed to cover unresolved, disposition-changing hypotheses. Most runs
+    // use zero or one; multiple orthogonal hypotheses dispatch in parallel.
     //
     // Build mode self-review is a different problem shape: the orchestrator
     // wrote the code, so bias-mitigation comes from delegating to one
     // fresh-eyes subagent that doesn't share the implementation context. A
-    // single subagent there is appropriate; the 0-or-2+ rule applies only to
-    // the Review/IncrementalReview lens fan-out where independence between
-    // perspectives is what's being purchased.
+    // single subagent there is appropriate. Review-mode specialist routing
+    // instead scales with the unresolved hypotheses in someone else's diff.
     //
     // Severity categorization is split across two surfaces: the opening
     // callout (CAUTION/IMPORTANT/ℹ️/✅) sets the review's overall tier, and
@@ -103967,11 +103963,11 @@ For simple, well-defined tasks, skip the plan phase and go straight to build.`
 
 1. **task list**: create your task list for this run as your first action.
 
-2. **checkout**: call \`${t2("checkout_pr")}\` \u2014 this returns PR metadata and a \`diffPath\`. read the diff TOC end-to-end and treat its file line ranges as your coverage checklist.
+2. **checkout**: call \`${t2("checkout_pr")}\` \u2014 this returns PR metadata, a \`diffPath\`, and a supplemental \`impactPath\` when change-impact extraction is enabled. read the complete raw diff end-to-end, beginning with the TOC and using its file line ranges as your coverage checklist. only after that, use \`impactPath\` as an explicitly incomplete list of reference leads; it never replaces raw-diff reading or establishes coverage.
 
 3. **triage**: orient yourself on the PR \u2014 identify *what kind of thing this is* (domain it touches, seams it crosses, external contracts it depends on, user-facing surfaces it changes). pull as much context as you need to render a confident, well-grounded review: read related files, grep for callers of changed symbols, check tests that exercise the touched paths, fetch related GitHub state. **you are the synthesizer** \u2014 never delegate understanding to subagents.
 
-   if the PR is **genuinely trivial**, skip the fan-out entirely and submit a \`No new issues found.\` review per step 7.
+   if the PR is **genuinely trivial**, skip specialists entirely and submit a \`No new issues found.\` review per step 7.
 
    "Genuinely trivial" (skip):
    - single-word doc typo, whitespace/format-only, comment-only across any number of files
@@ -103990,22 +103986,24 @@ For simple, well-defined tasks, skip the plan phase and go straight to build.`
    - any "typo fix" in user-facing copy that changes meaning ("approved" \u2192 "denied")
    - mixed diffs where a semantic 1-liner is buried in whitespace/formatting changes
 
-4. **lens decision \u2014 0 or 2+, NEVER 1**.
+4. **specialist decision \u2014 minimum hypothesis coverage**.
 
-   The default is **0 lenses**: handle the review yourself end-to-end. Most PRs land here.
+   After full-diff coverage and triage, identify the load-bearing questions you still cannot resolve confidently yourself. A specialist hypothesis is load-bearing only when its answer could yield an actionable finding that changes the review disposition and warrants independent investigation, and falsifiable only when the specialist can return evidence that supports or refutes it. Generic requests for extra confidence, polish, or "another look" do not qualify.
 
-   Dispatch **2+ \`${REVIEWER_AGENT_NAME}\` lenses in parallel** ONLY when ALL of the following are true:
-   - the PR is substantive (>5 files changed AND >200 net lines), OR touches a high-stakes subsystem (auth, billing, payments, schema migration, webhooks, secrets, RBAC, multi-tenant isolation, cron/scheduling)
-   - you can name 2+ distinct concrete failure modes that warrant independent lenses (one lens per failure mode; orthogonal, not overlapping)
-   - parallel-orchestrated independent perspectives meaningfully outperform what you'd find solo
+   Route the **minimum number of \`${REVIEWER_AGENT_NAME}\` specialists** needed to cover those unresolved hypotheses. Most reviews need **0 or 1**:
+   - dispatch 0 when you can resolve every disposition-changing question directly
+   - dispatch 1 when exactly one falsifiable, load-bearing hypothesis warrants independent investigation
+   - dispatch 2+ in parallel when multiple orthogonal load-bearing hypotheses remain, or when the user explicitly requests an exhaustive or multi-angle review
 
-   **NEVER dispatch exactly one lens.** A single lens is just a more expensive version of doing the work yourself with a worse model \u2014 it adds wall time and a context-handoff for no orthogonality benefit. Either you have at least two genuinely independent failure-mode hypotheses (dispatch all in one turn), or you don't (do the review yourself).
+   **There is NO one-specialist cap or fixed maximum.** Cover every orthogonal load-bearing hypothesis that remains; do not collapse multiple real questions into one broad prompt just to reduce the count. There is also no file-count, line-count, schema, quota, or hard-budget threshold \u2014 diff size is not a proxy for review uncertainty.
 
-   When you do go multi-lens, lens framings come in two flavors:
+   The primary reviewer remains responsible for reading the complete raw diff, investigating surrounding code, validating every returned finding, and synthesizing the final review. Specialist reads supplement that work; they never replace it or satisfy the primary's diff-coverage obligation.
+
+   Specialist hypotheses can draw on two kinds of framing:
    - **themed lenses** \u2014 a perspective applied across the whole diff (correctness, security, user-journey, performance, etc.).
    - **subsystem lenses** \u2014 a domain-scoped frame for high-stakes subsystems the PR touches (e.g. "the auth lens", "the billing lens", "the schema-migration lens"). **for high-stakes domains, lead with the subsystem lens rather than the generic themed equivalent** \u2014 "billing-subsystem" outperforms "correctness on billing code" because the framing primes the subagent to remember domain-specific failure modes (double-charges, refund races, currency rounding, dispute flows) the generic lens misses.
 
-   starter menu (combine, omit, or invent your own):
+   starter menu for identifying hypotheses (combine, omit, or invent your own; do not dispatch a bare menu label without a falsifiable question):
    - **correctness & invariants** \u2014 bugs, races, error handling, edge cases, state-machine boundaries
    - **impact** \u2014 stale references in code/tests/docs/configs/UI after rename/remove
    - **research-validated assumptions** \u2014 third-party API contracts, SDK semantics, framework directives, version-gated behavior. **only pick when the PR's correctness depends on the contract behaving a specific way** \u2014 not when the API is merely used. The bar is "if the third-party contract differs from what the diff assumes, the PR is incorrect." When dispatched, the subagent must verify load-bearing claims via web search and quote source URLs.
@@ -104020,30 +104018,27 @@ For simple, well-defined tasks, skip the plan phase and go straight to build.`
 
    The only subagent type is \`${REVIEWER_AGENT_NAME}\` \u2014 used for lens judgment work ("is this safe / correct / well-tested?"), runs on a mid-tier model.
 
-5. **fan out (only if step 4 said 2+ lenses)**: dispatch every \`${REVIEWER_AGENT_NAME}\` subagent for this run **IN A SINGLE ASSISTANT TURN, AS MULTIPLE PARALLEL TASK TOOL_USE BLOCKS IN ONE MESSAGE.**
-
-   \u26A0\uFE0F  CRITICAL \u2014 PARALLELISM IS THE ONLY REASON LENSES EXIST. \u26A0\uFE0F
-   The default tool-call behavior of Claude Code (and most agent runtimes) is **serial dispatch**: emit one Task call, await result, emit next, await, etc. This collapses your fan-out into a sequential review where each lens adds N \xD7 (orchestrator-think-time + lens-execution-time) to wall time. **YOU MUST OVERRIDE THIS DEFAULT.** Emit ALL of your Task tool_use blocks in the SAME assistant message, BEFORE you read ANY result from ANY of them. If you find yourself emitting one Task call, then thinking about the result, then emitting another \u2014 STOP and re-issue them all together. The whole point of going multi-lens is the wall-clock speedup from parallel execution; serial dispatch defeats it entirely.
+5. **dispatch specialists (only if step 4 found unresolved hypotheses)**: dispatch one \`${REVIEWER_AGENT_NAME}\` for one hypothesis. For 2+ hypotheses, emit every Task tool_use block **IN A SINGLE ASSISTANT TURN** before reading any result so the investigations run in parallel rather than serially.
 
-   \u2705 Right pattern: one assistant turn with N Task tool_use blocks \u2192 wait \u2192 N results arrive together \u2192 aggregate.
-   \u274C Wrong pattern: turn 1 = Task(lens A) \u2192 turn 2 (after A's result) = Task(lens B) \u2192 turn 3 (after B's result) = Task(lens C). This is the failure mode. Do not do this.
+   \u2705 Right multi-specialist pattern: one assistant turn with N Task tool_use blocks \u2192 wait \u2192 N results arrive together \u2192 aggregate.
+   \u274C Wrong multi-specialist pattern: Task(hypothesis A) \u2192 wait for A \u2192 Task(hypothesis B).
 
    You can also include your own \`read\` / \`grep\` / \`webfetch\` calls in the SAME turn as the parallel \`${REVIEWER_AGENT_NAME}\` dispatches \u2014 concurrent context-pulling on the orchestrator side runs in parallel with the lens fan-out and costs zero extra wall time.
 
-   if a subagent errors out, times out, or returns nothing usable, retry once with the same lens; if it still fails, proceed with partial coverage and note the missing lens in the review body \u2014 do not skip the fan-out entirely on a single subagent failure. each subagent gets:
+   if a specialist errors out, times out, or returns nothing usable, retry it once with the same hypothesis. if it still fails, attempt to resolve the hypothesis yourself; if it remains disposition-changing and unresolved, surface the limitation and do not approve. each specialist gets:
    - **the absolute \`diffPath\` (and \`incrementalDiffPath\` if available) from step 2's \`${t2("checkout_pr")}\` return, named verbatim in the dispatch prompt** (e.g. \`diffPath: /tmp/pullfrog-XXXX/pr-NNN-SHA.diff\`). the reviewer's baked-in system prompt selects its FIRST action on this token \u2014 paraphrasing ("review the diff", "look at this PR") sends it down the \`git diff origin/<base>\` fallback, which fails on shallow GHA checkouts. the subagent \`read\`s those files for scope; it must NOT re-derive the diff via \`git diff\` (bare \`git diff origin/<base>\` is symmetric and pulls in the inverse of any commits that landed on \`<base>\` since the branch forked \u2014 pure noise, and the git tool rejects it). reading and codebase exploration are still its job.
-   - **only one lens** \u2014 never a multi-section "review for X, Y, and Z" prompt
-   - **a Task \`description\` set to the lens name** (e.g. \`"security"\`, \`"correctness"\`, \`"billing-subsystem"\`) \u2014 the harness reads this field to label the subagent's log lines so parallel runs can be told apart in CI output. without it, every subagent shows up as \`subagent#N\`.
+   - **exactly one falsifiable hypothesis with explicit scope boundaries** \u2014 ask for evidence that supports or refutes it, never a broad "review for X, Y, and Z" prompt
+   - **a Task \`description\` set to a short hypothesis label** (e.g. \`"webhook-replay"\`, \`"billing-rounding"\`) \u2014 the harness reads this field to label the subagent's log lines so parallel runs can be told apart in CI output. without it, every subagent shows up as \`subagent#N\`.
    - if the lens touches external contracts, instruct the subagent to verify load-bearing claims via web search rather than trust training data, and to quote source URLs in its reasoning. action runs are non-interactive \u2014 there's no human in the loop to catch "I'm pretty sure Stripe does X."
-   - ask the subagent to report findings with file paths and NEW line numbers from the diff so you can anchor inline comments without re-reading the entire diff.
+   - ask the subagent to report findings with file paths and NEW line numbers from the diff so you can validate and anchor them. you must still read the complete diff yourself.
 
    delegation discipline:
-   - do NOT summarize the PR for them (biases toward a validation frame)
+   - do NOT summarize the PR for them (a lossy summary biases toward a validation frame; the raw diff is the source)
    - do NOT hand them a curated reading list (let them discover scope)
    - do NOT pre-shape their output with a finding schema
    - do NOT mention the other lenses (independence is the point \u2014 overlapping findings are a strong signal)
 
-6. **aggregate & draft**: when the fan-out lands, merge findings; de-dup overlaps (two lenses catching the same issue = higher-confidence signal); trace each finding yourself before accepting it. drop praise, style preferences, speculative/unverified claims, findings about pre-existing code unrelated to the PR (heuristic: if the finding's root cause lives in lines this PR added or modified, it's in scope; otherwise drop unless the PR plausibly introduced or amplified the regression), and anything not actionable. also drop **bloat-shaped findings** \u2014 proposed fixes that would add defensive checks for cases that can't happen, abstractions used once, comments restating obvious code, tests asserting tautologies, or "just-in-case" guards. subagents are fallible and bias toward recommending changes; the bar for an actionable inline comment is sound + correct + elegant. recommending a change that improves only one of the three (or worse, degrades elegance to nominally improve correctness) makes the codebase worse, not better.
+6. **aggregate & draft**: when specialist results land, merge findings; de-dup overlaps (two specialists catching the same issue = higher-confidence signal); trace each finding yourself before accepting it. drop praise, style preferences, speculative/unverified claims, findings about pre-existing code unrelated to the PR (heuristic: if the finding's root cause lives in lines this PR added or modified, it's in scope; otherwise drop unless the PR plausibly introduced or amplified the regression), and anything not actionable. also drop **bloat-shaped findings** \u2014 proposed fixes that would add defensive checks for cases that can't happen, abstractions used once, comments restating obvious code, tests asserting tautologies, or "just-in-case" guards. subagents are fallible and bias toward recommending changes; the bar for an actionable inline comment is sound + correct + elegant. recommending a change that improves only one of the three (or worse, degrades elegance to nominally improve correctness) makes the codebase worse, not better.
 
    **Hunt for non-anchored concerns before drafting.** After collecting your anchored findings, deliberately scan for concerns that have no specific line to point at \u2014 typically: deletion / cleanup plans for code the diff replaces or shadows; rollout sequencing (what happens to in-flight state during deploy / revert?); coverage gaps the diff implies but doesn't add; scope questions that only the human can answer (e.g. is the legacy path going away or is this a long-term dual track?); architectural risks the diff opens up that aren't a single-line bug. On substantial PRs (migrations, refactors, multi-file rewrites, version bumps that change runtime semantics), at least one such concern almost always exists; if you can't think of any, your bar is probably too high.
 
@@ -104077,10 +104072,10 @@ For simple, well-defined tasks, skip the plan phase and go straight to build.`
 
 ${PR_SUMMARY_FORMAT}`
     },
-    // IncrementalReview shares Review's 0-or-2+ lens pattern AND its body
-    // format (PR_SUMMARY_FORMAT), scoped to the incremental delta against the
-    // prior pullfrog review. The "issues must be NEW since the last Pullfrog
-    // review" filter lives at aggregation time (step 8), NOT in the subagent
+    // IncrementalReview shares Review's minimum hypothesis-covering specialist
+    // routing and body format, scoped to the incremental delta against the
+    // prior Pullfrog review. The "issues must be NEW since the last Pullfrog
+    // review" filter lives at aggregation time, NOT in the subagent
     // prompt — pushing the filter into subagents matches the canonical anneal
     // anti-pattern of "list known pre-existing failures — don't flag these"
     // and suppresses signal on regressions the new commits amplified. A
@@ -104095,9 +104090,9 @@ ${PR_SUMMARY_FORMAT}`
 
 1. **task list**: create your task list for this run as your first action.
 
-2. **checkout**: call \`${t2("checkout_pr")}\` \u2014 this returns PR metadata, \`diffPath\` (full diff), and \`incrementalDiffPath\` (changes since last reviewed version, if available). read the diff TOC first and use its line ranges as your coverage checklist.
+2. **checkout**: call \`${t2("checkout_pr")}\` \u2014 this returns PR metadata, \`diffPath\` (full diff), \`incrementalDiffPath\` (changes since last reviewed version, if available), and a supplemental \`impactPath\` when change-impact extraction is enabled.
 
-3. **incremental scope**: if \`incrementalDiffPath\` is present, read it to see what changed since the last review. this is a range-diff that isolates the net changes, filtering out base branch noise. if not present, fall back to reviewing the full PR diff and determine what changed since Pullfrog's most recent review.
+3. **incremental scope**: if \`incrementalDiffPath\` is present, read it FIRST to see what changed since the last review. this is a range-diff that isolates the net changes, filtering out base branch noise. then read the authoritative full diff end-to-end, beginning with the TOC and using its line ranges as your coverage checklist. if no incremental diff is present, start with the full-diff TOC, determine what changed since Pullfrog's most recent review, and complete the raw-diff read. only after establishing that authoritative scope and completing raw-diff coverage, use \`impactPath\` as an explicitly incomplete list of reference leads; it never replaces raw-diff reading or establishes coverage.
 
 4. **prior feedback \u2014 read AND retire it**: fetch previous reviews via \`${t2("list_pull_request_reviews")}\`, then call \`${t2("get_review_comments")}\` on each prior Pullfrog review. Each thread renders as a section whose first line is a fenced tag \`comment author=<login> id=<fullDatabaseId> review=<reviewId> thread=<graphqlId>\`; section headers carry \`[RESOLVED]\` / \`[OUTDATED]\` when relevant. For every **open, Pullfrog-originated** thread, decide and act:
 
@@ -104111,49 +104106,48 @@ ${PR_SUMMARY_FORMAT}`
 
 5. **triage**: orient on the *incremental* changes \u2014 domain, seams, external contracts, user-facing surfaces. pull as much context as you need to render a confident review: read related files, grep for callers of changed symbols, check tests that exercise the touched paths. **you are the synthesizer.**
 
-   if the incremental changes are **genuinely trivial**, skip the fan-out entirely and jump to step 10's non-substantive path (do NOT submit a review).
+   if the incremental changes are **genuinely trivial**, skip specialists entirely and jump to step 10's non-substantive path (do NOT submit a review).
 
    "Genuinely trivial" (skip): formatting/comment tweaks, import reordering, lockfile regen, mechanical rename of import paths, whitespace-only.
    "Looks trivial but isn't" (do NOT skip \u2014 same anti-patterns as Review mode): 1-line changes to SQL/regex/auth/billing/permissions/signature-verification code; flipping feature-flag defaults or retry/timeout constants; money/tax/HTTP-method/redirect changes; tightening or loosening a comparison operator; mixed diffs with a semantic line buried in formatting.
    When unsure, treat as non-trivial.
 
-6. **lens decision \u2014 0 or 2+, NEVER 1**.
+6. **specialist decision \u2014 minimum hypothesis coverage**.
 
-   The default is **0 lenses**: handle the re-review yourself end-to-end. Most incremental reviews land here \u2014 especially thread-reply re-reviews where the user is asking "did you address X?" rather than "review the diff again."
+   After full-diff coverage and triage, identify the load-bearing questions about the incremental changes that you still cannot resolve confidently yourself. A specialist hypothesis is load-bearing only when its answer could yield an actionable new finding that changes the review disposition and warrants independent investigation, and falsifiable only when the specialist can return evidence that supports or refutes it. Generic requests for extra confidence, polish, or "another look" do not qualify.
 
-   Dispatch **2+ \`${REVIEWER_AGENT_NAME}\` lenses in parallel** ONLY when ALL of the following are true:
-   - the incremental changes are substantive (>5 files changed AND >200 net new lines), OR touch a high-stakes subsystem (auth, billing, payments, schema migration, webhooks, secrets, RBAC, multi-tenant isolation, cron/scheduling)
-   - you can name 2+ distinct concrete failure modes the new commits plausibly introduce that warrant independent lenses
-   - parallel-orchestrated independent perspectives meaningfully outperform what you'd find solo
+   Route the **minimum number of \`${REVIEWER_AGENT_NAME}\` specialists** needed to cover those unresolved hypotheses. Most incremental reviews need **0 or 1**, especially thread-reply re-reviews:
+   - dispatch 0 when you can resolve every disposition-changing question directly
+   - dispatch 1 when exactly one falsifiable, load-bearing hypothesis warrants independent investigation
+   - dispatch 2+ in parallel when multiple orthogonal load-bearing hypotheses remain, or when the user explicitly requests an exhaustive or multi-angle review
 
-   **NEVER dispatch exactly one lens.** Single-lens dispatch adds wall time and cost for no orthogonality benefit. Either go multi-lens (\u22652 in parallel) or do the re-review yourself.
+   **There is NO one-specialist cap or fixed maximum.** Cover every orthogonal load-bearing hypothesis that remains; do not collapse multiple real questions into one broad prompt just to reduce the count. There is also no file-count, line-count, schema, quota, or hard-budget threshold \u2014 diff size is not a proxy for review uncertainty.
 
-   Lens framing follows Review mode: themed lenses (correctness, security, etc.) and subsystem lenses (auth, billing, schema-migration, etc.) \u2014 for high-stakes domains lead with the subsystem lens.
+   The primary reviewer remains responsible for reading the complete raw full diff plus the incremental diff, investigating surrounding code, validating every returned finding, and synthesizing the final review. Specialist reads supplement that work; they never replace it or satisfy the primary's diff-coverage obligation.
 
-7. **fan out (only if step 6 said 2+ lenses)**: dispatch every \`${REVIEWER_AGENT_NAME}\` subagent for this run **IN A SINGLE ASSISTANT TURN, AS MULTIPLE PARALLEL TASK TOOL_USE BLOCKS IN ONE MESSAGE.**
+   Specialist hypotheses can draw on Review mode's themed or subsystem framings, but every dispatch must turn the framing into one falsifiable question with explicit scope boundaries.
 
-   \u26A0\uFE0F  CRITICAL \u2014 PARALLELISM IS THE ONLY REASON LENSES EXIST. \u26A0\uFE0F
-   Default tool-call behavior is **serial dispatch**: emit one Task call, await result, emit next, await, etc. This collapses your fan-out into a sequential review where each lens adds N \xD7 (orchestrator-think-time + lens-execution-time) to wall time. **YOU MUST OVERRIDE THIS DEFAULT.** Emit ALL of your Task tool_use blocks in the SAME assistant message, BEFORE you read ANY result from ANY of them.
+7. **dispatch specialists (only if step 6 found unresolved hypotheses)**: dispatch one \`${REVIEWER_AGENT_NAME}\` for one hypothesis. For 2+ hypotheses, emit every Task tool_use block **IN A SINGLE ASSISTANT TURN** before reading any result so the investigations run in parallel rather than serially.
 
-   \u2705 Right pattern: one assistant turn with N Task tool_use blocks \u2192 wait \u2192 N results arrive together \u2192 aggregate.
-   \u274C Wrong pattern: turn 1 = Task(lens A) \u2192 turn 2 (after A's result) = Task(lens B). This is the failure mode.
+   \u2705 Right multi-specialist pattern: one assistant turn with N Task tool_use blocks \u2192 wait \u2192 N results arrive together \u2192 aggregate.
+   \u274C Wrong multi-specialist pattern: Task(hypothesis A) \u2192 wait for A \u2192 Task(hypothesis B).
 
    You can also include your own \`read\` / \`grep\` / \`webfetch\` calls in the SAME turn as the parallel \`${REVIEWER_AGENT_NAME}\` dispatches.
 
-   if a subagent errors out, times out, or returns nothing usable, retry once with the same lens; if it still fails, proceed with partial coverage and note the missing lens in the review body. each subagent gets:
+   if a specialist errors out, times out, or returns nothing usable, retry it once with the same hypothesis. if it still fails, attempt to resolve the hypothesis yourself; if it remains disposition-changing and unresolved, surface the limitation and do not approve. each specialist gets:
    - **the absolute diff path(s) from step 2's \`${t2("checkout_pr")}\` return, named verbatim in the dispatch prompt.** when \`incrementalDiffPath\` is present, name BOTH (\`incrementalDiffPath: /tmp/.../pr-NNN-SHA-incremental.diff\` then \`diffPath: /tmp/.../pr-NNN-SHA.diff\`) \u2014 the reviewer's baked-in prompt reads incremental first and uses full for context; when only \`diffPath\` exists, name it alone. the subagent \`read\`s those files; it must NOT re-derive via \`git diff\` (bare \`git diff origin/<base>\` is symmetric and pulls in the inverse of base-branch progress \u2014 pure noise, and the git tool rejects it), and paraphrasing ("review the new commits") sends it down that fallback, which also fails on shallow GHA checkouts. do NOT tell them to skip pre-existing issues \u2014 that suppresses regressions the new commits amplified; the "issues must be NEW" filter lives at aggregation time (step 8), not in the subagent prompt.
-   - **only one lens** \u2014 never a multi-section "review for X, Y, and Z" prompt
-   - **a Task \`description\` set to the lens name** \u2014 the harness reads this field to label log lines so parallel runs can be told apart.
+   - **exactly one falsifiable hypothesis with explicit scope boundaries** \u2014 ask for evidence that supports or refutes it, never a broad "review for X, Y, and Z" prompt
+   - **a Task \`description\` set to a short hypothesis label** \u2014 the harness reads this field to label log lines so parallel runs can be told apart.
    - if the lens touches external contracts, instruct the subagent to verify load-bearing claims via web search and quote source URLs.
-   - ask the subagent to report findings with file paths and NEW line numbers from the full PR diff so you can anchor inline comments.
+   - ask the subagent to report findings with file paths and NEW line numbers from the full PR diff so you can validate and anchor them. you must still read the complete incremental and full diff scope yourself.
 
    delegation discipline:
-   - do NOT summarize the changes for them (biases toward validation frame)
+   - do NOT summarize the changes for them (a lossy summary biases toward a validation frame; the raw diff is the source)
    - do NOT hand them a curated reading list (let them discover scope)
    - do NOT pre-shape their output with a finding schema
    - do NOT mention the other lenses (independence is the point)
 
-8. **aggregate, draft, self-critique**: merge findings (yours + any subagent output if you went multi-lens); de-dup overlaps; trace each finding yourself. drop praise, style preferences, speculative/unverified claims, findings about pre-existing code unrelated to the new commits, anything not actionable, and anything that re-states prior review feedback (heuristic: if the finding's root cause lives in lines the *new commits* added or modified, it's in scope; otherwise drop). also drop **bloat-shaped findings** \u2014 proposed fixes that would add defensive checks for cases that can't happen, abstractions used once, comments restating obvious code, tests asserting tautologies, or "just-in-case" guards. subagents are fallible and bias toward recommending changes; the bar for an actionable inline comment is sound + correct + elegant. recommending a change that improves only one of the three (or degrades elegance to nominally improve correctness) makes the codebase worse, not better. To compute "lines the new commits added or modified": if \`incrementalDiffPath\` from step 2 is present, use it directly. Otherwise, take the prior Pullfrog review's \`commit_id\` (returned alongside each entry from \`${t2("list_pull_request_reviews")}\` in step 4) and run \`git diff <prior-review-sha>..HEAD\` to isolate the lines added since that review.
+8. **aggregate, draft, self-critique**: merge findings (yours + output from every specialist you dispatched); de-dup overlaps; trace each finding yourself. drop praise, style preferences, speculative/unverified claims, findings about pre-existing code unrelated to the new commits, anything not actionable, and anything that re-states prior review feedback (heuristic: if the finding's root cause lives in lines the *new commits* added or modified, it's in scope; otherwise drop). also drop **bloat-shaped findings** \u2014 proposed fixes that would add defensive checks for cases that can't happen, abstractions used once, comments restating obvious code, tests asserting tautologies, or "just-in-case" guards. subagents are fallible and bias toward recommending changes; the bar for an actionable inline comment is sound + correct + elegant. recommending a change that improves only one of the three (or degrades elegance to nominally improve correctness) makes the codebase worse, not better. To compute "lines the new commits added or modified": if \`incrementalDiffPath\` from step 2 is present, use it directly. Otherwise, take the prior Pullfrog review's \`commit_id\` (returned alongside each entry from \`${t2("list_pull_request_reviews")}\` in step 4) and run \`git diff <prior-review-sha>..HEAD\` to isolate the lines added since that review.
 
    **Hunt for non-anchored concerns before drafting.** After collecting your anchored findings, deliberately scan for concerns that have no specific line to point at \u2014 typically: deletion / cleanup plans for code the new commits replace or shadow; rollout sequencing (what happens to in-flight state during deploy / revert?); coverage gaps the new commits imply but don't add; scope questions that only the human can answer (e.g. is the legacy path going away or is this a long-term dual track?); architectural risks the new commits open up that aren't a single-line bug. On substantial incremental diffs (migrations, refactors, multi-file rewrites, version bumps that change runtime semantics), at least one such concern almost always exists; if you can't think of any, your bar is probably too high.
 
@@ -104250,7 +104244,7 @@ ${PR_SUMMARY_FORMAT}`
 
 1. **task list**: create your task list for this run as your first action.
 
-2. Analyze the task. For simple operations (labeling, commenting, answering questions, running a single command), handle directly \u2014 but your answer only reaches the user through \`${t2("report_progress")}\` (step 4); raw assistant text is discarded.
+2. Analyze the task. For simple operations (labeling, answering questions, running a single command), handle directly \u2014 but your answer only reaches the user through \`${t2("report_progress")}\` (step 4); raw assistant text is discarded. If a standalone comment on the current issue/PR is the task's sole requested deliverable, create that comment directly and skip \`${t2("report_progress")}\`.
 
 3. For substantial work \u2014 code changes across multiple files, multi-step investigations:
    - plan your approach before starting
@@ -104260,8 +104254,8 @@ ${PR_SUMMARY_FORMAT}`
 
 4. Finalize:
    - if code changes were made, get them onto a pull request (new or existing) using ${signedCommits ? `\`${t2("commit_changes")}\`` : `\`${t2("push_branch")}\``} and \`${t2("create_pull_request")}\` as needed. \`git status\` must be clean before you finish (see *SYSTEM* Git rules if this fails).
-   - call \`${t2("report_progress")}\` once with results \u2014 include exact tool errors if push or PR creation failed
-   - if the task involved labeling, commenting, or other GitHub operations, perform those directly`
+   - call \`${t2("report_progress")}\` once with results \u2014 include exact tool errors if push or PR creation failed. skip this only when a standalone comment on the current target was the task's sole requested deliverable
+   - if the task involved labeling or other GitHub operations, perform those directly`
     }
   ];
 }
@@ -104816,7 +104810,7 @@ async function runClaude2(params) {
           }
         } else if (block.type === "tool_use") {
           const toolName = block.name || "unknown";
-          if (params.onToolUse) {
+          if (params.onToolUse && label === ORCHESTRATOR_LABEL) {
             params.onToolUse({
               toolName,
               input: block.input
@@ -105208,7 +105202,7 @@ var claude = agent({
       const cliPath = await installClaudeCli();
       const specifier = ctx.payload.proxyModel ?? ctx.resolvedModel;
       const bedrockModelId = process.env[BEDROCK_MODEL_ID_ENV]?.trim();
-      const isBedrockRoute = specifier !== void 0 && bedrockModelId !== void 0 && bedrockModelId === specifier && isBedrockAnthropicId(specifier);
+      const isBedrockRoute = specifier !== void 0 && bedrockModelId !== void 0 && bedrockModelId === specifier;
       const vertexModelId = process.env[VERTEX_MODEL_ID_ENV]?.trim();
       const isVertexRoute2 = specifier !== void 0 && vertexModelId !== void 0 && vertexModelId === specifier && isVertexAnthropicId(specifier);
       const model = !specifier ? void 0 : isBedrockRoute ? specifier : isVertexRoute2 ? void 0 : stripProviderPrefix(specifier);
@@ -105256,6 +105250,7 @@ var claude = agent({
         ...homeEnv,
         PWD: repoDir
       };
+      env2.CLAUDE_CODE_AUTO_COMPACT_WINDOW ||= "500000";
       if (isBedrockRoute) {
         env2.CLAUDE_CODE_USE_BEDROCK = "1";
       }
@@ -144165,8 +144160,8 @@ function closeBrowserDaemon(toolState) {
 
 // mcp/checkout.ts
 import { createHash as createHash2 } from "node:crypto";
-import { statSync, unlinkSync as unlinkSync3, writeFileSync as writeFileSync8 } from "node:fs";
-import { join as join13 } from "node:path";
+import { statSync, unlinkSync as unlinkSync3, writeFileSync as writeFileSync9 } from "node:fs";
+import { join as join14 } from "node:path";
 
 // node_modules/.pnpm/@ark+schema@0.56.0/node_modules/@ark/schema/out/shared/errors.js
 var ArkError = class _ArkError extends CastableBase {
@@ -151635,6 +151630,367 @@ function ensureRepoState(toolState, init) {
   return created;
 }
 
+// utils/changeImpact.ts
+import { spawn as spawn4 } from "node:child_process";
+import { writeFileSync as writeFileSync7 } from "node:fs";
+import { join as join8 } from "node:path";
+var MAX_CANDIDATES = 24;
+var MAX_ATOM_LENGTH = 128;
+var MAX_ATOMS = 12;
+var MAX_REFERENCES = 6;
+var MAX_EXCERPT = 160;
+var MAX_BYTES = 16e3;
+function isSymbolShaped(atom) {
+  return atom.length >= 4 && atom.length <= MAX_ATOM_LENGTH && /[A-Z_]/.test(atom);
+}
+function getAtomConfidence(params) {
+  const before = params.text.slice(Math.max(0, params.index - 64), params.index);
+  const after = params.text.slice(
+    params.index + params.atom.length,
+    params.index + params.atom.length + 16
+  );
+  if (/\b(?:class|interface|type|enum|function|def|func|fn|struct|trait)\s+$/.test(before))
+    return 4;
+  if (/\b(?:const|let|var)\s+$/.test(before) || /^\s*\??\s*[:(]/.test(after)) return 3;
+  const quoted = /['"`]$/.test(before) && /^['"`]/.test(after);
+  if (quoted || before.endsWith(".") || after.startsWith(".") || params.atom.includes("_"))
+    return 2;
+  return 1;
+}
+function getChangedAtoms(text) {
+  const atoms = /* @__PURE__ */ new Map();
+  for (const match3 of text.matchAll(/[A-Za-z_][A-Za-z0-9_]*/g)) {
+    const atom = match3[0];
+    if (!isSymbolShaped(atom)) continue;
+    const confidence = getAtomConfidence({ text, atom, index: match3.index ?? 0 });
+    atoms.set(atom, Math.max(atoms.get(atom) ?? 0, confidence));
+  }
+  return atoms;
+}
+function recordChange(params) {
+  for (const [atom, confidence] of getChangedAtoms(params.text)) {
+    const change = params.changes.get(atom) ?? { atom, confidence, added: [], removed: [] };
+    change.confidence = Math.max(change.confidence, confidence);
+    change[params.location.kind].push(params.location);
+    params.changes.set(atom, change);
+  }
+}
+function locationKey(location) {
+  return `${location.path}\0${location.line}`;
+}
+function collectFileChanges(collection, file2) {
+  if (!file2.patch) return;
+  let oldLine = 0;
+  let newLine = 0;
+  for (const patchLine of file2.patch.split("\n")) {
+    const hunk = patchLine.match(/^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+    if (hunk) {
+      oldLine = Number.parseInt(hunk[1], 10);
+      newLine = Number.parseInt(hunk[2], 10);
+    } else if (patchLine.startsWith("+")) {
+      const location = { path: file2.filename, line: newLine++, kind: "added" };
+      collection.addedLines.add(locationKey(location));
+      recordChange({ changes: collection.changes, location, text: patchLine.slice(1) });
+    } else if (patchLine.startsWith("-")) {
+      const oldPath = file2.previous_filename ?? file2.filename;
+      recordChange({
+        changes: collection.changes,
+        location: { path: oldPath, line: oldLine++, kind: "removed" },
+        text: patchLine.slice(1)
+      });
+    } else if (!patchLine.startsWith("\\")) {
+      oldLine++;
+      newLine++;
+    }
+  }
+}
+function compareChanges(a, b) {
+  if (a.confidence !== b.confidence) return b.confidence - a.confidence;
+  const removedDelta = Number(b.removed.length > 0) - Number(a.removed.length > 0);
+  if (removedDelta !== 0) return removedDelta;
+  const aDelta = Math.abs(a.added.length - a.removed.length);
+  const bDelta = Math.abs(b.added.length - b.removed.length);
+  if (aDelta !== bDelta) return bDelta - aDelta;
+  if (a.atom.length !== b.atom.length) return b.atom.length - a.atom.length;
+  return a.atom < b.atom ? -1 : Number(a.atom > b.atom);
+}
+function getCandidates(files) {
+  const collection = {
+    changes: /* @__PURE__ */ new Map(),
+    addedLines: /* @__PURE__ */ new Set()
+  };
+  for (const file2 of files) collectFileChanges(collection, file2);
+  const candidates = [...collection.changes.values()].filter((change) => change.added.length !== change.removed.length).sort(compareChanges);
+  return {
+    selected: candidates.slice(0, MAX_CANDIDATES),
+    total: candidates.length,
+    addedLines: collection.addedLines
+  };
+}
+function emptyBuckets(candidates) {
+  return new Map(candidates.map((candidate) => [candidate.atom, { count: 0, samples: [] }]));
+}
+function createGrepRecordState() {
+  return {
+    phase: "path",
+    path: "",
+    line: "",
+    sample: "",
+    truncated: false,
+    searchTail: "",
+    searchStart: 0,
+    matches: /* @__PURE__ */ new Set()
+  };
+}
+function resetGrepRecord(state) {
+  state.phase = "path";
+  state.path = "";
+  state.line = "";
+  state.sample = "";
+  state.truncated = false;
+  state.searchTail = "";
+  state.searchStart = 0;
+  state.matches.clear();
+}
+function isWordCharacter(value2) {
+  return value2 !== void 0 && /[A-Za-z0-9_]/.test(value2);
+}
+function recordCandidateMatches(params) {
+  for (const candidate of params.candidates) {
+    if (params.matches.has(candidate.atom)) continue;
+    let index = params.text.indexOf(candidate.atom, params.minStart);
+    while (index >= 0 && index < params.maxStart) {
+      const before = params.text[index - 1];
+      const after = params.text[index + candidate.atom.length];
+      if (!isWordCharacter(before) && !isWordCharacter(after)) {
+        params.matches.add(candidate.atom);
+        break;
+      }
+      index = params.text.indexOf(candidate.atom, index + 1);
+    }
+  }
+}
+function consumeReferenceText(params) {
+  const remaining = MAX_EXCERPT - params.state.sample.length;
+  params.state.sample += params.text.slice(0, Math.max(remaining, 0));
+  if (params.text.length > remaining) params.state.truncated = true;
+  const searchable = params.state.searchTail + params.text;
+  const consumed = params.final ? searchable.length : Math.max(0, searchable.length - params.maxAtomLength - 2);
+  recordCandidateMatches({
+    text: searchable,
+    minStart: params.state.searchStart,
+    maxStart: consumed,
+    candidates: params.candidates,
+    matches: params.state.matches
+  });
+  if (params.final) {
+    params.state.searchTail = "";
+    params.state.searchStart = 0;
+    return;
+  }
+  const tailStart = Math.max(0, consumed - 1);
+  params.state.searchTail = searchable.slice(tailStart);
+  params.state.searchStart = consumed > 0 ? 1 : params.state.searchStart;
+}
+function recordGrepReference(params) {
+  const prefix = `${params.treeish}:`;
+  const path4 = params.state.path.startsWith(prefix) ? params.state.path.slice(prefix.length) : params.state.path;
+  const line = Number.parseInt(params.state.line, 10);
+  if (!Number.isFinite(line)) return;
+  const reference2 = {
+    path: path4,
+    line,
+    text: params.state.sample,
+    truncated: params.state.truncated
+  };
+  if (params.addedLines.has(locationKey(reference2))) return;
+  for (const atom of params.state.matches) {
+    const bucket = params.buckets.get(atom);
+    if (!bucket) continue;
+    bucket.count++;
+    if (bucket.samples.length < MAX_REFERENCES) bucket.samples.push(reference2);
+  }
+}
+function consumeGrepChunk(params) {
+  let offset = 0;
+  while (offset < params.chunk.length) {
+    if (params.state.phase !== "text") {
+      const end2 = params.chunk.indexOf("\0", offset);
+      const value2 = end2 < 0 ? params.chunk.slice(offset) : params.chunk.slice(offset, end2);
+      params.state[params.state.phase] += value2;
+      if (end2 < 0) return;
+      params.state.phase = params.state.phase === "path" ? "line" : "text";
+      offset = end2 + 1;
+      continue;
+    }
+    const end = params.chunk.indexOf("\n", offset);
+    const final = end >= 0;
+    const text = final ? params.chunk.slice(offset, end) : params.chunk.slice(offset);
+    consumeReferenceText({
+      state: params.state,
+      text,
+      candidates: params.candidates,
+      maxAtomLength: params.maxAtomLength,
+      final
+    });
+    if (!final) return;
+    recordGrepReference(params);
+    resetGrepRecord(params.state);
+    offset = end + 1;
+  }
+}
+async function lookupReferences(params) {
+  const buckets = emptyBuckets(params.candidates);
+  if (params.candidates.length === 0) return { buckets, error: void 0 };
+  const patterns = params.candidates.flatMap((candidate) => ["-e", candidate.atom]);
+  const child = spawn4(
+    "git",
+    [
+      "grep",
+      "--no-color",
+      "--full-name",
+      "-n",
+      "-z",
+      "-I",
+      "-w",
+      "-F",
+      ...patterns,
+      params.treeish,
+      "--",
+      ":(top)"
+    ],
+    { env: resolveEnv(void 0), stdio: ["ignore", "pipe", "pipe"] }
+  );
+  const state = createGrepRecordState();
+  const maxAtomLength = Math.max(...params.candidates.map((candidate) => candidate.atom.length));
+  let spawnError;
+  child.stdout.setEncoding("utf8");
+  child.stdout.on("data", (chunk) => {
+    consumeGrepChunk({
+      chunk,
+      state,
+      candidates: params.candidates,
+      maxAtomLength,
+      buckets,
+      addedLines: params.addedLines,
+      treeish: params.treeish
+    });
+  });
+  child.stderr.resume();
+  const status = await new Promise((resolve3) => {
+    child.once("error", (error49) => {
+      spawnError = error49.message;
+      resolve3(null);
+    });
+    child.once("close", resolve3);
+  });
+  if (spawnError || status !== 0 && status !== 1) {
+    const error49 = spawnError ?? `git grep exit ${status ?? "unknown"}`;
+    log.warning(`\xBB change impact lookup failed: ${error49}`);
+    return { buckets: emptyBuckets(params.candidates), error: error49 };
+  }
+  if (state.phase === "text") {
+    consumeReferenceText({
+      state,
+      text: "",
+      candidates: params.candidates,
+      maxAtomLength,
+      final: true
+    });
+    recordGrepReference({ state, buckets, addedLines: params.addedLines, treeish: params.treeish });
+  } else if (state.phase !== "path" || state.path) {
+    const error49 = "malformed git grep output";
+    log.warning(`\xBB change impact lookup failed: ${error49}`);
+    return { buckets: emptyBuckets(params.candidates), error: error49 };
+  }
+  return { buckets, error: void 0 };
+}
+function formatReference(reference2) {
+  const text = reference2.text.trim();
+  const excerpt = reference2.truncated ? `${text.slice(0, MAX_EXCERPT - 1)}\u2026` : text;
+  return `- ${JSON.stringify(reference2.path)}:${reference2.line} ${JSON.stringify(excerpt)}`;
+}
+function formatChangedLocations(change) {
+  const selected = [change.removed[0], change.added[0]].filter(
+    (location) => location !== void 0
+  );
+  const rendered = selected.map((location) => `${location.kind} ${JSON.stringify(location.path)}:${location.line}`).join(", ");
+  const omitted = change.removed.length + change.added.length - selected.length;
+  return omitted > 0 ? `${rendered}; ${omitted} more changed location(s) omitted` : rendered;
+}
+function formatEntry(entry) {
+  const count = entry.bucket.count;
+  const sampleNote = count > entry.bucket.samples.length ? `${count} matched line(s); first ${entry.bucket.samples.length} shown.` : `${count} matched line(s).`;
+  return [
+    `## \`${entry.change.atom}\``,
+    "",
+    `Changed at: ${formatChangedLocations(entry.change)}`,
+    `Tracked references: ${sampleNote}`,
+    "",
+    ...entry.bucket.samples.map(formatReference)
+  ].join("\n");
+}
+function formatArtifact(params) {
+  const lines = [
+    "# Change impact leads",
+    "",
+    "> Supplemental and explicitly incomplete. Read the authoritative `diffPath` TOC and raw lines first. Absence here is not evidence of no impact.",
+    "",
+    `Scope: base ${params.baseSha}, head ${params.headSha}; ${params.fileCount} changed file(s).`,
+    "Generated from changed symbol-shaped identifiers, then one exact-word lookup pinned to the checked-out head across Git-tracked text files. Changed added lines are excluded; snippets are capped at 160 characters.",
+    "",
+    `Candidate atoms searched: ${params.candidateCount}/${params.totalCandidateCount}.`
+  ];
+  if (params.lookupError) lines.push(`Tracked-file lookup unavailable: ${params.lookupError}.`);
+  let content = `${lines.join("\n")}
+`;
+  let renderedAtomCount = 0;
+  let referenceCount = 0;
+  for (const entry of params.entries.filter((candidate) => candidate.bucket.count > 0)) {
+    if (renderedAtomCount >= MAX_ATOMS) break;
+    const addition = `
+${formatEntry(entry)}
+`;
+    if (Buffer.byteLength(content + addition) > MAX_BYTES) break;
+    content += addition;
+    renderedAtomCount++;
+    referenceCount += entry.bucket.count;
+  }
+  if (renderedAtomCount === 0) {
+    const empty = "\nNo bounded tracked references found. This is not evidence of no wider impact.\n";
+    if (Buffer.byteLength(content + empty) <= MAX_BYTES) content += empty;
+  }
+  return { content, renderedAtomCount, referenceCount };
+}
+async function createChangeImpactArtifact(ctx, params) {
+  const candidates = getCandidates(params.files);
+  const lookup2 = await lookupReferences({
+    candidates: candidates.selected,
+    addedLines: candidates.addedLines,
+    treeish: params.headSha
+  });
+  const artifact = formatArtifact({
+    entries: candidates.selected.map((change) => {
+      return { change, bucket: lookup2.buckets.get(change.atom) ?? { count: 0, samples: [] } };
+    }),
+    candidateCount: candidates.selected.length,
+    totalCandidateCount: candidates.total,
+    fileCount: params.files.length,
+    baseSha: params.baseSha,
+    headSha: params.headSha,
+    lookupError: lookup2.error
+  });
+  const path4 = join8(ctx.tmpdir, `pr-${params.pullNumber}-${params.headSha.slice(0, 7)}-impact.md`);
+  writeFileSync7(path4, artifact.content);
+  return {
+    path: path4,
+    candidateCount: candidates.selected.length,
+    renderedAtomCount: artifact.renderedAtomCount,
+    referenceCount: artifact.referenceCount,
+    bytes: Buffer.byteLength(artifact.content)
+  };
+}
+
 // utils/diffCoverage.ts
 import { isAbsolute, normalize as normalize2, resolve } from "node:path";
 function countLines(params) {
@@ -151722,27 +152078,6 @@ function getDiffCoverageBreakdown(params) {
     files
   };
 }
-function renderDiffCoverageBreakdown(params) {
-  const breakdown = params.breakdown;
-  const lines = [];
-  lines.push(`diff coverage report for \`${params.diffPath}\``);
-  lines.push(
-    `overall: ${breakdown.coveredLines}/${breakdown.totalLines} lines read (${breakdown.coveragePercent}%), unread: ${breakdown.unreadLines}`
-  );
-  lines.push(`covered ranges: ${formatRanges({ ranges: breakdown.coveredRanges })}`);
-  lines.push(`unread ranges: ${formatRanges({ ranges: breakdown.unreadRanges })}`);
-  lines.push("");
-  lines.push("per-file TOC coverage:");
-  for (const file2 of breakdown.files) {
-    const filePercent = file2.totalLines ? Number((file2.coveredLines / file2.totalLines * 100).toFixed(2)) : 100;
-    lines.push(
-      `- ${file2.filename} (toc lines ${file2.startLine}-${file2.endLine}): ${file2.coveredLines}/${file2.totalLines} lines read (${filePercent}%)`
-    );
-    lines.push(`  read: ${formatRanges({ ranges: file2.coveredRanges })}`);
-    lines.push(`  unread: ${formatRanges({ ranges: file2.unreadRanges })}`);
-  }
-  return lines.join("\n");
-}
 function resolveOffsetBase(params) {
   const lower2 = params.toolName.toLowerCase();
   if (lower2 === "readfile" || lower2.endsWith(".readfile")) {
@@ -151873,10 +152208,6 @@ function countLinesInRanges(params) {
   }
   return total;
 }
-function formatRanges(params) {
-  if (params.ranges.length === 0) return "none";
-  return params.ranges.map((range2) => `${range2.startLine}-${range2.endLine}`).join(", ");
-}
 function clampLine(params) {
   if (params.value < 1) return 1;
   if (params.value > params.totalLines) return params.totalLines;
@@ -151903,7 +152234,7 @@ function readNumber(params) {
 import { execSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { readFileSync as readFileSync3, realpathSync, unlinkSync } from "node:fs";
-import { join as join8 } from "node:path";
+import { join as join9 } from "node:path";
 
 // utils/shell.ts
 import { spawnSync as spawnSync4 } from "node:child_process";
@@ -151981,7 +152312,7 @@ function resolveHooksDir(cwd, gitPath) {
     cwd,
     log: false
   }).trim();
-  const hooksDir = join8(commonDir, "hooks");
+  const hooksDir = join9(commonDir, "hooks");
   hooksDirCache.set(cwd, hooksDir);
   return hooksDir;
 }
@@ -153129,13 +153460,13 @@ function _op(fn2, options) {
 
 // mcp/git.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
-import { writeFileSync as writeFileSync7 } from "node:fs";
-import { join as join11 } from "node:path";
+import { writeFileSync as writeFileSync8 } from "node:fs";
+import { join as join12 } from "node:path";
 
 // utils/apiCommit.ts
 import { execFileSync as execFileSync7 } from "node:child_process";
 import { lstat, readlink } from "node:fs/promises";
-import { join as join9 } from "node:path";
+import { join as join10 } from "node:path";
 var GITHUB_API = "https://api.github.com";
 var MAX_BLOB_BYTES = 30 * 1024 * 1024;
 var BLOB_UPLOAD_CONCURRENCY = 8;
@@ -153200,7 +153531,7 @@ async function assertApiCommittable(files) {
   const root = getRepoRoot();
   const attrs = $2(
     "git",
-    ["check-attr", "filter", "-z", "--", ...present.map((p2) => join9(root, p2))],
+    ["check-attr", "filter", "-z", "--", ...present.map((p2) => join10(root, p2))],
     { log: false }
   );
   const parts = attrs.split("\0");
@@ -153212,7 +153543,7 @@ async function assertApiCommittable(files) {
     }
   }
   for (const path4 of present) {
-    const stat = await lstat(join9(root, path4));
+    const stat = await lstat(join10(root, path4));
     if (stat.isDirectory()) {
       throw new Error(
         `'${path4}' is a directory (nested repository or submodule?) \u2014 signed commits only support files and symlinks.`
@@ -153221,7 +153552,7 @@ async function assertApiCommittable(files) {
   }
 }
 async function createBlobEntry(params) {
-  const absPath = join9(params.repoRoot, params.path);
+  const absPath = join10(params.repoRoot, params.path);
   const stat = await lstat(absPath);
   if (stat.size > MAX_BLOB_BYTES) {
     throw new Error(
@@ -153401,7 +153732,7 @@ this usually means your local branch has commits that were never pushed \u2014 s
 var core3 = __toESM(require_core(), 1);
 import { createSign } from "node:crypto";
 import { rename, writeFile } from "node:fs/promises";
-import { dirname as dirname3, join as join10 } from "node:path";
+import { dirname as dirname3, join as join11 } from "node:path";
 
 // node_modules/.pnpm/@octokit+plugin-throttling@11.0.3_@octokit+core@7.0.5/node_modules/@octokit/plugin-throttling/dist-bundle/index.js
 var import_light = __toESM(require_light(), 1);
@@ -157345,7 +157676,7 @@ function getGitHubUsageSummary() {
 }
 async function writeGitHubUsageSummaryToFile(path4) {
   const summary2 = getGitHubUsageSummary();
-  const tmpPath = join10(dirname3(path4), `.usage-summary-${process.pid}.tmp`);
+  const tmpPath = join11(dirname3(path4), `.usage-summary-${process.pid}.tmp`);
   await writeFile(tmpPath, JSON.stringify(summary2));
   await rename(tmpPath, path4);
 }
@@ -158472,8 +158803,8 @@ function countAhead(head, base, cwd) {
 function spillGitOutput(params) {
   const tempDir = process.env.PULLFROG_TEMP_DIR;
   if (!tempDir) throw new Error("PULLFROG_TEMP_DIR not set");
-  const outputPath = join11(tempDir, `git-${params.command}-${randomUUID3().slice(0, 8)}.txt`);
-  writeFileSync7(outputPath, params.output);
+  const outputPath = join12(tempDir, `git-${params.command}-${randomUUID3().slice(0, 8)}.txt`);
+  writeFileSync8(outputPath, params.output);
   const previewByLines = params.output.split("\n").slice(0, OVERFLOW_PREVIEW_LINES).join("\n");
   const preview = previewByLines.length <= OVERFLOW_PREVIEW_MAX_CHARS ? previewByLines : `${previewByLines.slice(0, OVERFLOW_PREVIEW_MAX_CHARS)}\u2026`;
   log.info(
@@ -159105,13 +159436,15 @@ function addFooter(ctx, body) {
 var Comment = type({
   issueNumber: type.number.describe("the issue number to comment on"),
   body: type.string.describe("the comment body content"),
-  type: type.enumerated("Plan", "Comment").describe("Plan: record as the plan for this run. Comment: regular comment (default).").optional()
+  type: type.enumerated("Plan", "Comment").describe(
+    "Plan: standalone plan comment on another target. Comment: regular comment (default)."
+  ).optional()
 });
 function CreateCommentTool(ctx) {
   return tool({
     name: "create_issue_comment",
     mutates: true,
-    description: 'Create a comment on a GitHub issue or PR. Example: `create_issue_comment({ issueNumber: 1234, body: "Thanks for the report." })`. For progress/plan updates on the current run use report_progress instead \u2014 plan output (initial post AND revisions) is always posted via report_progress, never via this tool.',
+    description: "Create a comment on a GitHub issue or PR. Example: `create_issue_comment({ issueNumber: 1234, body: \"Thanks for the report.\" })`. For the current run's answer, progress, or plan use report_progress instead. Use this on the current target only when the task explicitly requests a standalone comment. Skip report_progress only when that current-target comment is the task's sole requested deliverable.",
     parameters: Comment,
     execute: execute(async ({ issueNumber, body, type: commentType }) => {
       const bodyWithFooter = addFooter(ctx, body);
@@ -159123,9 +159456,6 @@ function CreateCommentTool(ctx) {
       });
       ctx.toolState.wasUpdated = true;
       log.info(`\xBB created comment ${result.data.id}`);
-      if (commentType !== "Plan" && issueNumber === ctx.payload.event.issue_number) {
-        ctx.toolState.answerCommentPosted = true;
-      }
       if (commentType === "Plan") {
         if (result.data.node_id) {
           await patchWorkflowRunFields(ctx, { planCommentNodeId: result.data.node_id });
@@ -159931,10 +160261,6 @@ function runDiffCoveragePreflight(params) {
     unread.push({ path: file2.filename, ranges: rangesText, unreadLines: fileUnreadLines });
     unreadLines += fileUnreadLines;
   }
-  coverageState.lastBreakdown = renderDiffCoverageBreakdown({
-    diffPath: coverageState.diffPath,
-    breakdown
-  });
   log.debug(
     `diff coverage pre-flight breakdown: coveredLines=${breakdown.coveredLines}, unreadLines=${unreadLines}`
   );
@@ -159950,9 +160276,7 @@ function runDiffCoveragePreflight(params) {
     `diff coverage pre-flight: some TOC regions were not read before review submission. this is a one-time nudge \u2014 read the ranges below from ${coverageState.diffPath} on a best-effort basis, then call create_pull_request_review again. you are NOT obligated to read generated artifacts (lockfiles like pnpm-lock.yaml / package-lock.json / yarn.lock / Cargo.lock; codegen output like *.gen.*, *.pb.go, *.generated.*; snapshot/fixture dirs like __snapshots__/; migration metadata like drizzle/meta/, prisma migration SQL). if every unread region is generated, retry immediately without reading. this pre-flight will not block again in this review session.
 
 unread TOC regions:
-${unreadText}
-
-${coverageState.lastBreakdown}`
+${unreadText}`
   );
 }
 async function clearStrandedPendingReview(ctx, params) {
@@ -160074,9 +160398,9 @@ async function reportReviewNodeId(ctx, params) {
 import { execFileSync as execFileSync8, execSync as execSync2 } from "node:child_process";
 import { mkdtempSync as mkdtempSync2, readdirSync, realpathSync as realpathSync2, unlinkSync as unlinkSync2 } from "node:fs";
 import { tmpdir as tmpdir3 } from "node:os";
-import { join as join12 } from "node:path";
+import { join as join13 } from "node:path";
 function createTempDirectory() {
-  const sharedTempDir = mkdtempSync2(join12(tmpdir3(), "pullfrog-"));
+  const sharedTempDir = mkdtempSync2(join13(tmpdir3(), "pullfrog-"));
   process.env.PULLFROG_TEMP_DIR = sharedTempDir;
   log.info(`\xBB created temp dir at ${sharedTempDir}`);
   return sharedTempDir;
@@ -160121,13 +160445,13 @@ function wipeRunnerLeakSurface() {
       return [];
     }
   };
-  const fileCommandsDir = join12(runnerTemp, "_runner_file_commands");
+  const fileCommandsDir = join13(runnerTemp, "_runner_file_commands");
   for (const entry of listDir(fileCommandsDir)) {
-    tryUnlink(join12(fileCommandsDir, entry));
+    tryUnlink(join13(fileCommandsDir, entry));
   }
   for (const entry of listDir(runnerTemp)) {
     if (entry.endsWith(".sh") || /^git-credentials-.*\.config$/.test(entry)) {
-      tryUnlink(join12(runnerTemp, entry));
+      tryUnlink(join13(runnerTemp, entry));
     }
   }
   if (wiped.length > 0) {
@@ -160633,21 +160957,23 @@ function CheckoutPrTool(ctx) {
         "PULLFROG_TEMP_DIR not set - checkout_pr must run in pullfrog action context"
       );
     }
-    const headShort = primary.checkoutSha.slice(0, 7);
+    const checkoutSha = primary.checkoutSha;
+    if (!checkoutSha) throw new Error("checkout completed without a resolved HEAD SHA");
+    const headShort = checkoutSha.slice(0, 7);
     let incrementalDiffPath;
-    if (primary.beforeSha && primary.checkoutSha) {
+    if (primary.beforeSha) {
       const beforeShort = primary.beforeSha.slice(0, 7);
       const incremental = computeIncrementalDiff({
         baseBranch: pr.baseRef,
         beforeSha: primary.beforeSha,
-        headSha: primary.checkoutSha
+        headSha: checkoutSha
       });
       if (incremental) {
-        incrementalDiffPath = join13(
+        incrementalDiffPath = join14(
           tempDir,
           `pr-${pull_number}-${beforeShort}-${headShort}-incremental.diff`
         );
-        writeFileSync8(incrementalDiffPath, incremental);
+        writeFileSync9(incrementalDiffPath, incremental);
         log.info(
           `\xBB incremental diff computed (${incremental.length} bytes) \u2192 ${incrementalDiffPath}`
         );
@@ -160657,8 +160983,8 @@ function CheckoutPrTool(ctx) {
     const diffPreview = formatResult.content.split("\n").slice(0, 100).join("\n");
     log.debug(`formatted diff preview (first 100 lines):
 ${diffPreview}`);
-    const diffPath = join13(tempDir, `pr-${pull_number}-${headShort}.diff`);
-    writeFileSync8(diffPath, formatResult.content);
+    const diffPath = join14(tempDir, `pr-${pull_number}-${headShort}.diff`);
+    writeFileSync9(diffPath, formatResult.content);
     log.debug(`wrote diff to ${diffPath} (${formatResult.content.length} bytes)`);
     primary.diffCoverage = createDiffCoverageState({
       diffPath,
@@ -160669,14 +160995,56 @@ ${diffPreview}`);
     log.debug(
       `\xBB diff coverage initialized: diffPath=${diffPath}, totalLines=${primary.diffCoverage.totalLines}, tocEntries=${primary.diffCoverage.tocEntries.length}`
     );
+    let impactPath;
+    if (process.env.PULLFROG_DISABLE_CHANGE_IMPACT === "1") {
+      log.info("\xBB change impact disabled by PULLFROG_DISABLE_CHANGE_IMPACT");
+    } else {
+      let revisionVerified = false;
+      let revisionFailure;
+      try {
+        const latest = await ctx.octokit.rest.pulls.get({
+          owner: ctx.repo.owner,
+          repo: ctx.repo.name,
+          pull_number
+        });
+        revisionVerified = latest.data.head.sha === checkoutSha && latest.data.base.sha === prResponse.data.base.sha;
+      } catch (error49) {
+        revisionFailure = error49 instanceof Error ? error49.message : String(error49);
+      }
+      if (revisionFailure !== void 0) {
+        log.warning(
+          `\xBB change impact skipped: PR revision could not be verified (${revisionFailure})`
+        );
+      } else if (!revisionVerified) {
+        log.warning("\xBB change impact skipped: PR revision changed while the diff was fetched");
+      } else {
+        try {
+          const impact = await createChangeImpactArtifact(ctx, {
+            files: formatResult.files,
+            pullNumber: pull_number,
+            baseSha: prResponse.data.base.sha,
+            headSha: checkoutSha
+          });
+          impactPath = impact.path;
+          log.info(
+            `\xBB change impact: ${impact.candidateCount} candidate atom(s), ${impact.renderedAtomCount} detailed atom(s), ${impact.referenceCount} tracked reference(s), ${impact.bytes} bytes \u2192 ${impact.path}`
+          );
+        } catch (error49) {
+          log.warning(
+            `\xBB change impact skipped: generation failed (${error49 instanceof Error ? error49.message : String(error49)})`
+          );
+        }
+      }
+    }
     const cached4 = /* @__PURE__ */ new Map();
     for (const file2 of formatResult.files) {
       cached4.set(file2.filename, commentableLinesForFile(file2.patch));
     }
     primary.commentableLinesByFile = cached4;
     primary.commentableLinesPullNumber = pull_number;
-    primary.commentableLinesCheckoutSha = primary.checkoutSha;
-    const incrementalInstructions = incrementalDiffPath ? ` IMPORTANT: incrementalDiffPath contains ONLY the changes since the last reviewed version (computed via range-diff). you MUST read incrementalDiffPath FIRST to understand what changed, then use diffPath for full PR context. do NOT skip the incremental diff.` : "";
+    primary.commentableLinesCheckoutSha = checkoutSha;
+    const incrementalInstructions = incrementalDiffPath ? `IMPORTANT: incrementalDiffPath contains ONLY the changes since the last reviewed version (computed via range-diff). you MUST read incrementalDiffPath FIRST to understand what changed, then use diffPath for full PR context. do NOT skip the incremental diff. ` : "";
+    const impactInstructions = impactPath ? ` impactPath contains bounded, deterministic reference leads for semantic atoms changed by the PR. read the authoritative diff TOC and relevant raw diff lines FIRST; only then use impactPath as a supplemental, explicitly incomplete lead list. impactPath never establishes review coverage and an empty artifact is not evidence of no wider impact.` : "";
     const COMMIT_LOG_MAX = 200;
     const baseRange = `origin/${pr.baseRef}..HEAD`;
     let commitCount = 0;
@@ -160712,6 +161080,7 @@ ${diffPreview}`);
       url: prResponse.data.html_url,
       headRepo: pr.headRepoFullName,
       diffPath,
+      impactPath,
       incrementalDiffPath,
       toc: formatResult.toc,
       commitCount,
@@ -160719,7 +161088,7 @@ ${diffPreview}`);
       commitLogTruncated,
       commitLogUnavailable,
       hookWarning: checkoutResult.hookWarning,
-      instructions: `the diff file at diffPath contains a table of contents (TOC) at the top listing every changed file with its line range. use the TOC line ranges as your checklist and read specific files from the diff instead of reading the entire file. for example, if the TOC says "src/foo.ts \u2192 lines 5-42", read lines 5-42 from diffPath to see that file's changes. review files selectively based on relevance rather than reading everything sequentially. to inspect the PR's changed files, use diffPath \u2014 do NOT run \`git diff\` to re-derive what's already in diffPath. the formatted diff with line numbers is authoritative. if you ever do need a branch-vs-base diff via the git tool, use \`git diff --merge-base <base>\` (single call, includes uncommitted edits) or three-dot \`git diff <base>...HEAD\` (committed-only). bare \`<base>\` and two-dot \`<base>..HEAD\` are symmetric and pull in the inverse of every commit landed on \`<base>\` since the branch forked \u2014 the git tool will reject those forms when the divergence is detected. \`$(...)\` subshells are NOT expanded by the git tool. \`git log\` and \`git diff --stat\` are fine for commit-range overview, and \`git diff\` / \`git diff --cached\` are fine for inspecting *your own* uncommitted changes \u2014 but PR review content MUST come from diffPath. before your review is submitted, a one-time coverage pre-flight may error listing unread TOC regions. retry the same create_pull_request_review call to proceed \u2014 optionally after reading the listed ranges. the pre-flight will not block again this session. the local branch is 'localBranch' (pr-{number}), not the remote branch name. when pushing, omit branchName to use the current branch. do not use remoteBranch as a local branch name.` + incrementalInstructions + hookWarningInstructions + commitLogInstructions
+      instructions: incrementalInstructions + `the diff file at diffPath contains a table of contents (TOC) at the top listing every changed file with its line range. use the TOC line ranges as your checklist and read specific files from the diff instead of reading the entire file. for example, if the TOC says "src/foo.ts \u2192 lines 5-42", read lines 5-42 from diffPath to see that file's changes. review files selectively based on relevance rather than reading everything sequentially. to inspect the PR's changed files, use diffPath \u2014 do NOT run \`git diff\` to re-derive what's already in diffPath. the formatted diff with line numbers is authoritative. if you ever do need a branch-vs-base diff via the git tool, use \`git diff --merge-base <base>\` (single call, includes uncommitted edits) or three-dot \`git diff <base>...HEAD\` (committed-only). bare \`<base>\` and two-dot \`<base>..HEAD\` are symmetric and pull in the inverse of every commit landed on \`<base>\` since the branch forked \u2014 the git tool will reject those forms when the divergence is detected. \`$(...)\` subshells are NOT expanded by the git tool. \`git log\` and \`git diff --stat\` are fine for commit-range overview, and \`git diff\` / \`git diff --cached\` are fine for inspecting *your own* uncommitted changes \u2014 but PR review content MUST come from diffPath. before your review is submitted, a one-time coverage pre-flight may error listing unread TOC regions. retry the same create_pull_request_review call to proceed \u2014 optionally after reading the listed ranges. the pre-flight will not block again this session. the local branch is 'localBranch' (pr-{number}), not the remote branch name. when pushing, omit branchName to use the current branch. do not use remoteBranch as a local branch name.` + impactInstructions + hookWarningInstructions + commitLogInstructions
     };
   };
   return tool({
@@ -160766,8 +161135,8 @@ ${dirty}`
 }
 
 // mcp/checkSuite.ts
-import { mkdirSync as mkdirSync7, writeFileSync as writeFileSync9 } from "node:fs";
-import { join as join14 } from "node:path";
+import { mkdirSync as mkdirSync7, writeFileSync as writeFileSync10 } from "node:fs";
+import { join as join15 } from "node:path";
 var GetCheckSuiteLogs = type({
   check_suite_id: type.number.describe("the id from check_suite.id")
 });
@@ -160863,7 +161232,7 @@ function GetCheckSuiteLogsTool(ctx) {
       if (!tempDir) {
         throw new Error("PULLFROG_TEMP_DIR not set");
       }
-      const logsDir = join14(tempDir, "ci-logs");
+      const logsDir = join15(tempDir, "ci-logs");
       mkdirSync7(logsDir, { recursive: true });
       const jobResults = [];
       for (const run4 of failedRuns) {
@@ -160890,8 +161259,8 @@ function GetCheckSuiteLogsTool(ctx) {
               );
             }
             const logsText = await logsResult.text();
-            const logPath = join14(logsDir, `job-${job.id}.log`);
-            writeFileSync9(logPath, logsText);
+            const logPath = join15(logsDir, `job-${job.id}.log`);
+            writeFileSync10(logPath, logsText);
             const analysis = analyzeLog(logsText, 80);
             const failedSteps = job.steps?.filter((s) => s.conclusion === "failure").map((s) => `Step ${s.number}: ${s.name}`) ?? [];
             jobResults.push({
@@ -160939,8 +161308,8 @@ function GetCheckSuiteLogsTool(ctx) {
 }
 
 // mcp/commitInfo.ts
-import { writeFileSync as writeFileSync10 } from "node:fs";
-import { join as join15 } from "node:path";
+import { writeFileSync as writeFileSync11 } from "node:fs";
+import { join as join16 } from "node:path";
 var CommitInfo = type({
   sha: type.string.describe("the commit SHA (full or abbreviated) to fetch")
 });
@@ -160964,8 +161333,8 @@ function CommitInfoTool(ctx) {
           "PULLFROG_TEMP_DIR not set - get_commit_info must run in pullfrog action context"
         );
       }
-      const diffFile = join15(tempDir, `commit-${sha.slice(0, 7)}.diff`);
-      writeFileSync10(diffFile, formatResult.content);
+      const diffFile = join16(tempDir, `commit-${sha.slice(0, 7)}.diff`);
+      writeFileSync11(diffFile, formatResult.content);
       log.debug(`wrote commit diff to ${diffFile} (${formatResult.content.length} bytes)`);
       return {
         sha: data.sha,
@@ -160992,7 +161361,7 @@ import { performance as performance8 } from "node:perf_hooks";
 
 // prep/installNodeDependencies.ts
 import { existsSync as existsSync6 } from "node:fs";
-import { join as join17 } from "node:path";
+import { join as join18 } from "node:path";
 
 // node_modules/.pnpm/package-manager-detector@1.6.0/node_modules/package-manager-detector/dist/commands.mjs
 function dashDashArg(agent2, agentCommand) {
@@ -161291,7 +161660,7 @@ function isMetadataYarnClassic(metadataPath) {
 var import_semver3 = __toESM(require_semver2(), 1);
 import { existsSync as existsSync5 } from "node:fs";
 import { mkdir, readFile as readFile2 } from "node:fs/promises";
-import { delimiter, join as join16 } from "node:path";
+import { delimiter, join as join17 } from "node:path";
 var SUPPORTED_NAMES = ["npm", "pnpm", "yarn", "bun"];
 var COREPACK_MANAGED = ["pnpm", "yarn"];
 function isSupported(name) {
@@ -161329,7 +161698,7 @@ function parseDevEnginesField(field) {
   };
 }
 async function resolvePackageManagerSpec(cwd) {
-  const pkgPath = join16(cwd, "package.json");
+  const pkgPath = join17(cwd, "package.json");
   if (!existsSync5(pkgPath)) return null;
   let pkg;
   try {
@@ -161392,7 +161761,7 @@ async function currentVersion(name) {
   return result.stdout.trim();
 }
 function packageManagerBinDir(tmpdir4) {
-  return join16(tmpdir4, "pm-bin");
+  return join17(tmpdir4, "pm-bin");
 }
 async function ensurePackageManager(params) {
   const spec = params.spec;
@@ -161463,7 +161832,7 @@ async function installFallback(name, installSpec) {
     return result.stderr || `failed to install ${name}`;
   }
   if (name === "deno") {
-    const denoPath = join17(process.env.HOME || "", ".deno", "bin");
+    const denoPath = join18(process.env.HOME || "", ".deno", "bin");
     process.env.PATH = `${denoPath}:${process.env.PATH}`;
   }
   log.info(`\xBB installed ${name}`);
@@ -161472,7 +161841,7 @@ async function installFallback(name, installSpec) {
 var installNodeDependencies = {
   name: "installNodeDependencies",
   shouldRun: () => {
-    const packageJsonPath = join17(process.cwd(), "package.json");
+    const packageJsonPath = join18(process.cwd(), "package.json");
     return existsSync6(packageJsonPath);
   },
   run: async (options) => {
@@ -161571,12 +161940,12 @@ ${errorMessage}`]
 
 // prep/installPythonDependencies.ts
 import { existsSync as existsSync7, readFileSync as readFileSync5 } from "node:fs";
-import { join as join18 } from "node:path";
+import { join as join19 } from "node:path";
 function declaresBuildSystem(path4) {
   return /^\s*\[\s*build-system\s*\]/m.test(readFileSync5(path4, "utf8"));
 }
 function configApplies(config3, cwd) {
-  const path4 = join18(cwd, config3.file);
+  const path4 = join19(cwd, config3.file);
   return existsSync7(path4) && (config3.applies?.(path4) ?? true);
 }
 var PYTHON_CONFIGS = [
@@ -162712,8 +163081,8 @@ function PullRequestInfoTool(ctx) {
 }
 
 // mcp/reviewComments.ts
-import { writeFileSync as writeFileSync11 } from "node:fs";
-import { join as join19 } from "node:path";
+import { writeFileSync as writeFileSync12 } from "node:fs";
+import { join as join20 } from "node:path";
 var REVIEW_THREADS_QUERY = `
 query ($owner: String!, $name: String!, $prNumber: Int!) {
   repository(owner: $owner, name: $name) {
@@ -163129,8 +163498,8 @@ function GetReviewCommentsTool(ctx) {
         throw new Error("PULLFROG_TEMP_DIR not set");
       }
       const filename = `review-${params.review_id}-threads.md`;
-      const commentsPath = join19(tempDir, filename);
-      writeFileSync11(commentsPath, formatted.content);
+      const commentsPath = join20(tempDir, filename);
+      writeFileSync12(commentsPath, formatted.content);
       log.debug(`wrote ${threadBlocks.length} threads to ${commentsPath}`);
       return {
         review_id: params.review_id,
@@ -163365,11 +163734,11 @@ ${summaryAddendum}`,
 }
 
 // mcp/shell.ts
-import { spawn as spawn4, spawnSync as spawnSync5 } from "node:child_process";
+import { spawn as spawn5, spawnSync as spawnSync5 } from "node:child_process";
 import { randomUUID as randomUUID4 } from "node:crypto";
-import { closeSync, openSync, writeFileSync as writeFileSync12 } from "node:fs";
+import { closeSync, openSync, writeFileSync as writeFileSync13 } from "node:fs";
 import { userInfo as userInfo2 } from "node:os";
-import { join as join20 } from "node:path";
+import { join as join21 } from "node:path";
 import { setTimeout as sleep2 } from "node:timers/promises";
 var ShellParams = type({
   command: "string",
@@ -163467,7 +163836,7 @@ function spawnShell(params) {
   const repoRoot = resolveRepoRoot();
   const fsMounts = buildFsMounts(repoRoot);
   if (sandboxMethod === "unshare") {
-    return spawn4(
+    return spawn5(
       "unshare",
       [
         "--pid",
@@ -163491,7 +163860,7 @@ function spawnShell(params) {
     const pathRestore = 'export PATH="${SANDBOX_PATH:-$PATH}"; ';
     const escaped = (pathRestore + params.command).replace(/'/g, "'\\''");
     envArgs.push(`SANDBOX_PATH=${params.env.PATH ?? ""}`);
-    return spawn4(
+    return spawn5(
       "sudo",
       [
         "env",
@@ -163507,7 +163876,7 @@ function spawnShell(params) {
       { ...spawnOpts, env: {} }
     );
   }
-  return spawn4("bash", ["-c", params.command], spawnOpts);
+  return spawn5("bash", ["-c", params.command], spawnOpts);
 }
 async function killProcessGroup(proc) {
   if (!proc.pid) return;
@@ -163532,8 +163901,8 @@ function getTempDir() {
 var MAX_OUTPUT_CHARS = 5e3;
 function capOutput(output) {
   if (output.length <= MAX_OUTPUT_CHARS) return output;
-  const fullPath = join20(getTempDir(), `shell-${randomUUID4().slice(0, 8)}.log`);
-  writeFileSync12(fullPath, output);
+  const fullPath = join21(getTempDir(), `shell-${randomUUID4().slice(0, 8)}.log`);
+  writeFileSync13(fullPath, output);
   const elided = output.length - MAX_OUTPUT_CHARS;
   return `... [${elided} chars truncated; full output saved to ${fullPath}] ...
 ${output.slice(-MAX_OUTPUT_CHARS)}`;
@@ -163587,8 +163956,8 @@ Do NOT use this tool for git commands \u2014 use the dedicated git tools instead
       if (params.background) {
         const tempDir = getTempDir();
         const handle = `bg-${randomUUID4().slice(0, 8)}`;
-        const outputPath = join20(tempDir, `${handle}.log`);
-        const pidPath = join20(tempDir, `${handle}.pid`);
+        const outputPath = join21(tempDir, `${handle}.log`);
+        const pidPath = join21(tempDir, `${handle}.pid`);
         const logFd = openSync(outputPath, "a");
         let proc2;
         try {
@@ -163605,7 +163974,7 @@ Do NOT use this tool for git commands \u2014 use the dedicated git tools instead
           throw new Error("failed to start background process");
         }
         proc2.unref();
-        writeFileSync12(pidPath, `${proc2.pid}
+        writeFileSync13(pidPath, `${proc2.pid}
 `);
         ctx.toolState.backgroundProcesses.set(handle, { pid: proc2.pid, outputPath, pidPath });
         return {
@@ -163755,7 +164124,7 @@ function UploadFileTool(ctx) {
 
 // mcp/xrepo.ts
 import { mkdirSync as mkdirSync8, rmSync as rmSync3 } from "node:fs";
-import { join as join21 } from "node:path";
+import { join as join22 } from "node:path";
 function assertValidRepoName(name) {
   if (!/^[A-Za-z0-9._-]+$/.test(name) || name.startsWith("-") || name.includes("..")) {
     throw new Error(
@@ -163773,6 +164142,7 @@ var ListRepos = type({});
 function ListReposTool(ctx) {
   return tool({
     name: "list_repos",
+    annotations: { readOnlyHint: true },
     description: "List the repositories available for cross-repo (`--xrepo`) work in this run, with each repo's access tier (primary, write, or read) and whether it's already checked out. Use this before `checkout_repo` to discover what you can reference or edit. Returns an empty set on single-repo runs.",
     parameters: ListRepos,
     execute: execute(async () => {
@@ -163834,7 +164204,7 @@ function CheckoutRepoTool(ctx) {
         return { path: existing.dir, access: existing.access, note: "already checked out." };
       }
       const access = accessFor(ctx, repo);
-      const dir = join21(ctx.tmpdir, "xrepo", repo);
+      const dir = join22(ctx.tmpdir, "xrepo", repo);
       mkdirSync8(dir, { recursive: true });
       const state = ensureRepoState(ctx.toolState, { owner, name: repo, dir, access });
       const rc = resolveRepoCtx(ctx, repo);
@@ -164284,9 +164654,9 @@ function formatApiKeyErrorSummary(params) {
 
 // utils/gitAuthServer.ts
 import { randomUUID as randomUUID5 } from "node:crypto";
-import { writeFileSync as writeFileSync13 } from "node:fs";
+import { writeFileSync as writeFileSync14 } from "node:fs";
 import { createServer as createServer3 } from "node:http";
-import { join as join22 } from "node:path";
+import { join as join23 } from "node:path";
 var REVOKED_TRAP_MS = 6e4;
 function revokeGitHubToken(token) {
   fetch("https://api.github.com/installation/token", {
@@ -164355,7 +164725,7 @@ async function startGitAuthServer(tmpdir4) {
   function writeAskpassScript(code) {
     const scriptId = randomUUID5();
     const scriptName = `askpass-${scriptId}.js`;
-    const scriptPath = join22(tmpdir4, scriptName);
+    const scriptPath = join23(tmpdir4, scriptName);
     const content = [
       `#!/usr/bin/env node`,
       `var a=process.argv[2]||"";`,
@@ -164368,7 +164738,7 @@ async function startGitAuthServer(tmpdir4) {
       `r.on("end",function(){process.stdout.write(d+"\\n")})`,
       `}).on("error",function(){process.exit(1)})}`
     ].join("\n");
-    writeFileSync13(scriptPath, content, { mode: 448 });
+    writeFileSync14(scriptPath, content, { mode: 448 });
     return scriptPath;
   }
   async function close() {
@@ -164689,9 +165059,9 @@ When embedding images (e.g. uploaded screenshots) in comments or PR bodies, alwa
 
 **Your raw assistant messages are never delivered** \u2014 they exist only in the run logs. Anything the user is meant to see (an answer to a question, a mention reply, a result) MUST go through \`report_progress\` (or another ${pullfrogMcpName} write tool). Do not rely on returning the answer as plain text \u2014 the harness makes a best-effort attempt to recover it into the progress comment, but that is a safety net, not a substitute for calling \`report_progress\`.
 
-**\`report_progress\`**: call this exactly once at the end of every run with a brief final summary (1-3 sentences) unless the mode guidance instructs otherwise. Never call it for intermediate status updates (e.g., "Checking for changes...", "Starting review...") \u2014 the task list handles live progress automatically. Calling \`report_progress\` replaces the task list with your summary and preserves the current task list in a collapsible section. Keep the summary concise \u2014 do not repeat what the task list already shows. Focus on the outcome (what was accomplished, links to artifacts) rather than listing individual steps. If something failed, include the tool's error text even when that makes the summary longer.
+**\`report_progress\`**: call this exactly once at the end of every run with a brief final summary (1-3 sentences) unless the mode guidance instructs otherwise or a standalone comment on the current target is the task's sole requested deliverable. Never call it for intermediate status updates (e.g., "Checking for changes...", "Starting review...") \u2014 the task list handles live progress automatically. Calling \`report_progress\` replaces the task list with your summary and preserves the current task list in a collapsible section. Keep the summary concise \u2014 do not repeat what the task list already shows. Focus on the outcome (what was accomplished, links to artifacts) rather than listing individual steps. If something failed, include the tool's error text even when that makes the summary longer.
 
-Never use \`create_issue_comment\` for task progress \u2014 that creates duplicate comments and leaves the progress comment stuck in its initial state. \`create_issue_comment\` is only for standalone comments unrelated to your current task. Plan output (initial post AND revisions) goes through \`report_progress\` \u2014 see the Plan mode guidance for details.
+Never use \`create_issue_comment\` for task progress or for the answer that \`report_progress\` should deliver. Use it only when the task explicitly requests a separate standalone comment or a comment on a different target. Skip \`report_progress\` only when a standalone comment on the current target is the task's sole requested deliverable; successful-run cleanup then removes the progress chrome. Plan output (initial post AND revisions) goes through \`report_progress\` \u2014 see the Plan mode guidance for details.
 
 ### If you get stuck
 
@@ -164825,7 +165195,7 @@ function resolveInstructions(ctx) {
 
 // utils/learnings.ts
 import { mkdir as mkdir2, readFile as readFile3, writeFile as writeFile2 } from "node:fs/promises";
-import { dirname as dirname4, join as join23 } from "node:path";
+import { dirname as dirname4, join as join24 } from "node:path";
 
 // utils/learningsTruncate.ts
 var MAX_LEARNINGS_LENGTH = 1e5;
@@ -164843,10 +165213,10 @@ function truncateAtLineBoundary(body, cap) {
 var LEARNINGS_FILE_NAME = "pullfrog-learnings.md";
 var XREPO_LEARNINGS_FILE_NAME = "pullfrog-xrepo-learnings.md";
 function learningsFilePath(tmpdir4) {
-  return join23(tmpdir4, LEARNINGS_FILE_NAME);
+  return join24(tmpdir4, LEARNINGS_FILE_NAME);
 }
 function xrepoLearningsFilePath(tmpdir4) {
-  return join23(tmpdir4, XREPO_LEARNINGS_FILE_NAME);
+  return join24(tmpdir4, XREPO_LEARNINGS_FILE_NAME);
 }
 async function seedLearningsFile(params) {
   const path4 = learningsFilePath(params.tmpdir);
@@ -165586,7 +165956,7 @@ async function runProxyResolution(ctx) {
 
 // utils/prSummary.ts
 import { mkdir as mkdir3, readFile as readFile4, writeFile as writeFile3 } from "node:fs/promises";
-import { dirname as dirname5, join as join24 } from "node:path";
+import { dirname as dirname5, join as join25 } from "node:path";
 var SUMMARY_FILE_NAME = "pullfrog-summary.md";
 var SUMMARY_SCAFFOLD = `# PR summary
 
@@ -165596,7 +165966,7 @@ var SUMMARY_SCAFFOLD = `# PR summary
 var MIN_SNAPSHOT_LENGTH = 60;
 var MAX_SNAPSHOT_LENGTH = 32768;
 function summaryFilePath(tmpdir4) {
-  return join24(tmpdir4, SUMMARY_FILE_NAME);
+  return join25(tmpdir4, SUMMARY_FILE_NAME);
 }
 async function seedSummaryFile(params) {
   const path4 = summaryFilePath(params.tmpdir);
@@ -166313,7 +166683,7 @@ async function finalizeSuccessRun(input) {
       log.debug(`failure error report failed: ${error49}`);
     });
   }
-  if (input.result.success && input.toolState.progressComment && input.toolState.wasUpdated && (!input.toolState.finalSummaryWritten || input.toolState.answerCommentPosted)) {
+  if (input.result.success && input.toolState.progressComment && input.toolState.wasUpdated && !input.toolState.finalSummaryWritten) {
     await deleteProgressComment(input.toolContext).catch((error49) => {
       log.debug(`stranded progress comment cleanup failed: ${error49}`);
     });
@@ -166879,7 +167249,7 @@ ${instructions.user}` : null,
           log.info(instructions.full);
         });
         if (agentId === "opencode") {
-          const pluginDir = join25(process.cwd(), ".opencode", "plugin");
+          const pluginDir = join26(process.cwd(), ".opencode", "plugin");
           const hasPlugins = existsSync8(pluginDir) && readdirSync2(pluginDir).some((f) => /\.[jt]sx?$/.test(f));
           if (hasPlugins && toolState.dependencyInstallation?.promise) {
             log.info(
@@ -168053,7 +168423,7 @@ async function runCli4(input) {
 }
 
 // cli.ts
-var VERSION10 = "0.1.35";
+var VERSION10 = "0.1.36";
 var bin = basename2(process.argv[1] || "");
 var PROG = bin === "pf" || bin === "pullfrog" ? bin : "pullfrog";
 var rawArgs = process.argv.slice(2);