pullfrog 0.1.6 → 0.1.8

package/dist/index.js

@@ -107744,7 +107744,8 @@ var providers = {
         displayName: "Claude Opus",
         resolve: "anthropic/claude-opus-4-7",
         openRouterResolve: "openrouter/anthropic/claude-opus-4.7",
-        preferred: true
+        preferred: true,
+        subagentModel: "claude-sonnet"
       },
       "claude-sonnet": {
         displayName: "Claude Sonnet",
@@ -107766,12 +107767,23 @@ var providers = {
         displayName: "GPT",
         resolve: "openai/gpt-5.5",
         openRouterResolve: "openrouter/openai/gpt-5.5",
-        preferred: true
+        preferred: true,
+        subagentModel: "gpt-5.4"
       },
       "gpt-pro": {
         displayName: "GPT Pro",
         resolve: "openai/gpt-5.5-pro",
-        openRouterResolve: "openrouter/openai/gpt-5.5-pro"
+        openRouterResolve: "openrouter/openai/gpt-5.5-pro",
+        subagentModel: "gpt"
+      },
+      // hidden subagent target — `gpt` lenses run against this. surfacing
+      // it in the picker would just confuse users (it's the prior-flagship,
+      // and they already have `gpt` and `gpt-mini` to choose from).
+      "gpt-5.4": {
+        displayName: "GPT 5.4",
+        resolve: "openai/gpt-5.4",
+        openRouterResolve: "openrouter/openai/gpt-5.4",
+        hidden: true
       },
       "gpt-mini": {
         displayName: "GPT Mini",
@@ -107809,7 +107821,8 @@ var providers = {
         displayName: "Gemini Pro",
         resolve: "google/gemini-3.1-pro-preview",
         openRouterResolve: "openrouter/google/gemini-3.1-pro-preview",
-        preferred: true
+        preferred: true,
+        subagentModel: "gemini-flash"
       },
       "gemini-flash": {
         displayName: "Gemini Flash",
@@ -107897,7 +107910,8 @@ var providers = {
       "claude-opus": {
         displayName: "Claude Opus",
         resolve: "opencode/claude-opus-4-7",
-        openRouterResolve: "openrouter/anthropic/claude-opus-4.7"
+        openRouterResolve: "openrouter/anthropic/claude-opus-4.7",
+        subagentModel: "claude-sonnet"
       },
       "claude-sonnet": {
         displayName: "Claude Sonnet",
@@ -107912,12 +107926,21 @@ var providers = {
       gpt: {
         displayName: "GPT",
         resolve: "opencode/gpt-5.5",
-        openRouterResolve: "openrouter/openai/gpt-5.5"
+        openRouterResolve: "openrouter/openai/gpt-5.5",
+        subagentModel: "gpt-5.4"
       },
       "gpt-pro": {
         displayName: "GPT Pro",
         resolve: "opencode/gpt-5.5-pro",
-        openRouterResolve: "openrouter/openai/gpt-5.5-pro"
+        openRouterResolve: "openrouter/openai/gpt-5.5-pro",
+        subagentModel: "gpt"
+      },
+      // hidden subagent target — see openai provider above for context.
+      "gpt-5.4": {
+        displayName: "GPT 5.4",
+        resolve: "opencode/gpt-5.4",
+        openRouterResolve: "openrouter/openai/gpt-5.4",
+        hidden: true
       },
       "gpt-mini": {
         displayName: "GPT Mini",
@@ -107940,7 +107963,8 @@ var providers = {
       "gemini-pro": {
         displayName: "Gemini Pro",
         resolve: "opencode/gemini-3.1-pro",
-        openRouterResolve: "openrouter/google/gemini-3.1-pro-preview"
+        openRouterResolve: "openrouter/google/gemini-3.1-pro-preview",
+        subagentModel: "gemini-flash"
       },
       "gemini-flash": {
         displayName: "Gemini Flash",
@@ -107972,6 +107996,20 @@ var providers = {
       }
     }
   }),
+  bedrock: provider({
+    displayName: "Amazon Bedrock",
+    envVars: ["AWS_BEARER_TOKEN_BEDROCK", "AWS_REGION", "BEDROCK_MODEL_ID"],
+    models: {
+      // single routing entry — the actual Bedrock model ID is read from
+      // BEDROCK_MODEL_ID at run time. see ModelRouting docs for why we
+      // don't catalog individual Bedrock models.
+      byok: {
+        displayName: "Amazon Bedrock",
+        resolve: "bedrock",
+        routing: "bedrock"
+      }
+    }
+  }),
   openrouter: provider({
     displayName: "OpenRouter",
     envVars: ["OPENROUTER_API_KEY"],
@@ -107980,7 +108018,8 @@ var providers = {
         displayName: "Claude Opus",
         resolve: "openrouter/anthropic/claude-opus-4.7",
         openRouterResolve: "openrouter/anthropic/claude-opus-4.7",
-        preferred: true
+        preferred: true,
+        subagentModel: "claude-sonnet"
       },
       "claude-sonnet": {
         displayName: "Claude Sonnet",
@@ -107995,12 +108034,21 @@ var providers = {
       gpt: {
         displayName: "GPT",
         resolve: "openrouter/openai/gpt-5.5",
-        openRouterResolve: "openrouter/openai/gpt-5.5"
+        openRouterResolve: "openrouter/openai/gpt-5.5",
+        subagentModel: "gpt-5.4"
       },
       "gpt-pro": {
         displayName: "GPT Pro",
         resolve: "openrouter/openai/gpt-5.5-pro",
-        openRouterResolve: "openrouter/openai/gpt-5.5-pro"
+        openRouterResolve: "openrouter/openai/gpt-5.5-pro",
+        subagentModel: "gpt"
+      },
+      // hidden subagent target — see openai provider above for context.
+      "gpt-5.4": {
+        displayName: "GPT 5.4",
+        resolve: "openrouter/openai/gpt-5.4",
+        openRouterResolve: "openrouter/openai/gpt-5.4",
+        hidden: true
       },
       "gpt-mini": {
         displayName: "GPT Mini",
@@ -108028,7 +108076,8 @@ var providers = {
       "gemini-pro": {
         displayName: "Gemini Pro",
         resolve: "openrouter/google/gemini-3.1-pro-preview",
-        openRouterResolve: "openrouter/google/gemini-3.1-pro-preview"
+        openRouterResolve: "openrouter/google/gemini-3.1-pro-preview",
+        subagentModel: "gemini-flash"
       },
       "gemini-flash": {
         displayName: "Gemini Flash",
@@ -108097,7 +108146,13 @@ var modelAliases = Object.entries(providers).flatMap(
     openRouterResolve: def.openRouterResolve,
     preferred: def.preferred ?? false,
     isFree: def.isFree ?? false,
-    fallback: def.fallback
+    fallback: def.fallback,
+    routing: def.routing,
+    // subagentModel is stored as an alias key local to the provider; expand
+    // here to a fully-qualified slug so callers can look up the target alias
+    // directly without re-deriving the provider.
+    subagentModel: def.subagentModel ? `${providerKey}/${def.subagentModel}` : void 0,
+    hidden: def.hidden ?? false
   }))
 );
 var MAX_FALLBACK_DEPTH = 10;
@@ -108117,6 +108172,10 @@ function resolveDisplayAlias(slug2) {
 function resolveCliModel(slug2) {
   return resolveDisplayAlias(slug2)?.resolve;
 }
+var BEDROCK_MODEL_ID_ENV = "BEDROCK_MODEL_ID";
+function isBedrockAnthropicId(bedrockModelId) {
+  return bedrockModelId.toLowerCase().split(/[./:]/).includes("anthropic");
+}
 
 // utils/buildPullfrogFooter.ts
 var PULLFROG_DIVIDER = "<!-- PULLFROG_DIVIDER_DO_NOT_REMOVE_PLZ -->";
@@ -108964,7 +109023,7 @@ var Comment = type({
 function CreateCommentTool(ctx) {
   return tool({
     name: "create_issue_comment",
-    description: "Create a comment on a GitHub issue or PR. For progress/plan updates on the current run use report_progress instead. Use type: 'Plan' for plan comments.",
+    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. Use type: 'Plan' for plan comments.",
     parameters: Comment,
     execute: execute(async ({ issueNumber, body, type: commentType }) => {
       const bodyWithFooter = addFooter(ctx, body);
@@ -109132,7 +109191,7 @@ async function reportProgress(ctx, params) {
 function ReportProgressTool(ctx) {
   return tool({
     name: "report_progress",
-    description: "Share progress on the associated GitHub issue/PR. The first call creates a comment; subsequent calls update it in place. Call this at the end of every run with a brief final summary (1-3 sentences) unless the mode guidance instructs otherwise. The current task list is automatically appended in a collapsible section \u2014 do not restate individual steps.",
+    description: 'Share progress on the associated GitHub issue/PR. The first call creates a comment; subsequent calls update it in place. Example: `report_progress({ body: "Implemented the auth check and added tests." })`. Call this at the end of every run with a brief final summary (1-3 sentences) unless the mode guidance instructs otherwise. The current task list is automatically appended in a collapsible section \u2014 do not restate individual steps.',
     parameters: ReportProgress,
     execute: execute(async (params) => {
       let body = params.body;
@@ -109212,7 +109271,7 @@ function duplicateReplyDecision(params) {
 function ReplyToReviewCommentTool(ctx) {
   return tool({
     name: "reply_to_review_comment",
-    description: "Reply to a PR review comment thread (NOT issue comments \u2014 this only works for inline review comments on PR diffs). Call exactly ONCE per parent comment you address in AddressReviews mode \u2014 duplicate calls with the same body are a no-op. Keep replies extremely brief (1 sentence max).",
+    description: 'Reply to a PR review comment thread (NOT issue comments \u2014 this only works for inline review comments on PR diffs). Example: `reply_to_review_comment({ pull_number: 1234, comment_id: 567890, body: "Fixed by adding a null check." })`. Call exactly ONCE per parent comment you address in AddressReviews mode \u2014 duplicate calls with the same body are a no-op. Keep replies extremely brief (1 sentence max).',
     parameters: ReplyToReviewComment,
     execute: execute(async ({ pull_number, comment_id, body }) => {
       const bodyWithFooter = addFooter(ctx, body);
@@ -142355,7 +142414,7 @@ var import_semver = __toESM(require_semver2(), 1);
 // package.json
 var package_default = {
   name: "pullfrog",
-  version: "0.1.6",
+  version: "0.1.8",
   type: "module",
   bin: {
     pullfrog: "dist/cli.mjs",
@@ -142823,6 +142882,51 @@ function readNumber(params) {
 import { execSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { readFileSync as readFileSync2, realpathSync, unlinkSync } from "node:fs";
+
+// utils/shell.ts
+import { spawnSync as spawnSync2 } from "node:child_process";
+function $(cmd, args2, options) {
+  const encoding = options?.encoding ?? "utf-8";
+  const env2 = resolveEnv(options?.env);
+  const result = spawnSync2(cmd, args2, {
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding,
+    cwd: options?.cwd,
+    env: env2
+  });
+  const stdout = result.stdout ?? "";
+  const stderr = result.stderr ?? "";
+  if (options?.log !== false) {
+    const canWriteToStdout = process.stdout.isTTY === true;
+    if (stdout) {
+      if (canWriteToStdout) {
+        process.stdout.write(stdout);
+      } else {
+        process.stderr.write(stdout);
+      }
+    }
+    if (stderr) {
+      process.stderr.write(stderr);
+    }
+  }
+  if (result.status !== 0) {
+    const errorResult = {
+      status: result.status ?? -1,
+      stdout,
+      stderr
+    };
+    if (options?.onError) {
+      options.onError(errorResult);
+      return stdout.trim();
+    }
+    throw new Error(
+      `Command failed with exit code ${errorResult.status}: ${stderr || "Unknown error"}`
+    );
+  }
+  return stdout.trim();
+}
+
+// utils/gitAuth.ts
 var gitBinary;
 function hashFile(path3) {
   return createHash("sha256").update(readFileSync2(path3)).digest("hex");
@@ -142914,6 +143018,27 @@ ${stdout}` : stderr || stdout || "(no output)";
     }
   }
 }
+var SHALLOW_UNREACHABLE_PATTERNS = [
+  /Could not read [a-f0-9]{40,64}/,
+  /remote did not send all necessary objects/
+];
+var DEEPEN_RETRY_DEPTH = 1e3;
+async function $gitFetchWithDeepen(args2, options, label) {
+  try {
+    return await $git("fetch", args2, options);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const isShallowUnreachable = SHALLOW_UNREACHABLE_PATTERNS.some((p) => p.test(msg));
+    if (!isShallowUnreachable) throw err;
+    const isShallow = $("git", ["rev-parse", "--is-shallow-repository"], { log: false }).trim() === "true";
+    if (!isShallow) throw err;
+    log.info(
+      `\xBB ${label ?? "git fetch"} hit shallow-unreachable error, retrying with --deepen=${DEEPEN_RETRY_DEPTH}`
+    );
+    const retryArgs = args2.filter((a) => !a.startsWith("--depth="));
+    return await $git("fetch", [`--deepen=${DEEPEN_RETRY_DEPTH}`, ...retryArgs], options);
+  }
+}
 
 // lifecycle.ts
 var LIFECYCLE_HOOK_TIMEOUT_MS = 6e5;
@@ -142955,49 +143080,6 @@ async function executeLifecycleHook(params) {
   }
 }
 
-// utils/shell.ts
-import { spawnSync as spawnSync2 } from "node:child_process";
-function $(cmd, args2, options) {
-  const encoding = options?.encoding ?? "utf-8";
-  const env2 = resolveEnv(options?.env);
-  const result = spawnSync2(cmd, args2, {
-    stdio: ["ignore", "pipe", "pipe"],
-    encoding,
-    cwd: options?.cwd,
-    env: env2
-  });
-  const stdout = result.stdout ?? "";
-  const stderr = result.stderr ?? "";
-  if (options?.log !== false) {
-    const canWriteToStdout = process.stdout.isTTY === true;
-    if (stdout) {
-      if (canWriteToStdout) {
-        process.stdout.write(stdout);
-      } else {
-        process.stderr.write(stdout);
-      }
-    }
-    if (stderr) {
-      process.stderr.write(stderr);
-    }
-  }
-  if (result.status !== 0) {
-    const errorResult = {
-      status: result.status ?? -1,
-      stdout,
-      stderr
-    };
-    if (options?.onError) {
-      options.onError(errorResult);
-      return stdout.trim();
-    }
-    throw new Error(
-      `Command failed with exit code ${errorResult.status}: ${stderr || "Unknown error"}`
-    );
-  }
-  return stdout.trim();
-}
-
 // utils/rangeDiff.ts
 function computeIncrementalDiff(params) {
   try {
@@ -143211,7 +143293,7 @@ function PushBranchTool(ctx) {
   const pushPermission = ctx.payload.push;
   return tool({
     name: "push_branch",
-    description: "Push the current branch to the remote repository. Omit branchName to push the current branch (recommended). If specifying branchName, use the LOCAL branch name (e.g., 'pr-1'), not the remote branch name. The correct remote and remote branch are determined automatically from branch config set by checkout_pr. Requires a clean working tree. Runs the repository prepush hook (if configured) before the network push \u2014 hook failure means tests/lint or similar in that script failed, not necessarily a Pullfrog timeout. Never force push unless explicitly requested. Pushes to the default branch are blocked in restricted mode.",
+    description: "Push the current branch to the remote repository. Omit branchName to push the current branch (recommended). Example: `push_branch({})` to push the current branch. Example: `push_branch({ branchName: \"pr-1\" })` to push a specific local branch. If specifying branchName, use the LOCAL branch name (e.g., 'pr-1'), not the remote branch name. The correct remote and remote branch are determined automatically from branch config set by checkout_pr. Requires a clean working tree. Runs the repository prepush hook (if configured) before the network push \u2014 hook failure means tests/lint or similar in that script failed, not necessarily a Pullfrog timeout. Never force push unless explicitly requested. Pushes to the default branch are blocked in restricted mode. If the response reports a timeout, the underlying push may have actually succeeded \u2014 verify with `git log origin/<branch>` (or this tool with command 'log') before retrying, otherwise you'll push a duplicate.",
     parameters: PushBranch,
     execute: execute(async ({ branchName, force }) => {
       if (pushPermission === "disabled") {
@@ -143350,7 +143432,7 @@ var Git = type({
 function GitTool(ctx) {
   return tool({
     name: "git",
-    description: "Run git commands. For push/fetch, use the dedicated MCP tools (push_branch, git_fetch). git pull is not available \u2014 use git_fetch then this tool with command 'merge'.",
+    description: 'Run a git subcommand. `command` is a single subcommand; flags and positional args go in `args`. Example: `git({ command: "log", args: ["--oneline", "-n", "20"] })`. Example: `git({ command: "diff", args: ["origin/main..HEAD"] })`. For push/fetch, use the dedicated MCP tools (push_branch, git_fetch). git pull is not available \u2014 use git_fetch then this tool with command \'merge\'.',
     parameters: Git,
     execute: execute(async (params) => {
       const command = params.command;
@@ -143392,15 +143474,10 @@ var GitFetch = type({
   ref: type.string.describe("Ref to fetch: branch name, tag, or 'pull/N/head' for PRs"),
   depth: type.number.describe("Fetch depth (for shallow clones)").optional()
 });
-var SHALLOW_UNREACHABLE_PATTERNS = [
-  /Could not read [a-f0-9]{40,64}/,
-  /remote did not send all necessary objects/
-];
-var DEEPEN_RETRY_DEPTH = 1e3;
 function GitFetchTool(ctx) {
   return tool({
     name: "git_fetch",
-    description: "Fetch refs from remote repository. Use this instead of git fetch directly.",
+    description: 'Fetch refs from remote repository. Use this instead of git fetch directly. Example: `git_fetch({ ref: "main" })`. With depth: `git_fetch({ ref: "pull/1234/head", depth: 1 })`.',
     parameters: GitFetch,
     execute: execute(async (params) => {
       rejectIfLeadingDash(params.ref, "ref");
@@ -143408,20 +143485,7 @@ function GitFetchTool(ctx) {
       if (params.depth !== void 0) {
         fetchArgs.push(`--depth=${params.depth}`);
       }
-      try {
-        await $git("fetch", fetchArgs, { token: ctx.gitToken });
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        const isShallowUnreachable = SHALLOW_UNREACHABLE_PATTERNS.some((p) => p.test(msg));
-        const isShallow = isShallowUnreachable && $("git", ["rev-parse", "--is-shallow-repository"], { log: false }).trim() === "true";
-        if (!isShallow) throw err;
-        log.info(
-          `\xBB git_fetch hit shallow-unreachable error, retrying with --deepen=${DEEPEN_RETRY_DEPTH}`
-        );
-        await $git("fetch", [`--deepen=${DEEPEN_RETRY_DEPTH}`, "--no-tags", "origin", params.ref], {
-          token: ctx.gitToken
-        });
-      }
+      await $gitFetchWithDeepen(fetchArgs, { token: ctx.gitToken }, "git_fetch");
       return { success: true, ref: params.ref };
     })
   });
@@ -143634,13 +143698,15 @@ var CreatePullRequestReview = type({
   approved: type.boolean.describe(
     "Set to true to submit as an approval. Use for both 'no issues found' and informational `> [!NOTE]` reviews where the PR is mergeable as-is and nothing in the body warrants code changes \u2014 approving also suppresses the Fix-button footer affordance so users don't dispatch a fix run on non-actionable feedback. Reserve approved: false for `> [!IMPORTANT]` (recommended changes) and `> [!CAUTION]` (critical) reviews. Defaults to false (comment-only review). Rejections are not supported."
   ).optional(),
-  commit_id: type.string.describe("Optional SHA of the commit being reviewed. Defaults to latest.").optional(),
+  commit_id: type.string.describe(
+    "Optional SHA of the commit being reviewed. Defaults to latest. Must be the FULL 40-character SHA \u2014 abbreviated SHAs are rejected by GitHub with `422 Unprocessable Entity`. The PR-synchronize event payload's `head_sha` is already full-length."
+  ).optional(),
   comments: type({
     path: type.string.describe(
       "The file path to comment on (relative to repo root). Must be a file that appears in the PR diff."
     ),
     line: type.number.describe(
-      "Line number to comment on. For multi-line ranges, this is the end line. Use NEW column from diff format."
+      "Line number to comment on. For multi-line ranges, this is the end line. Use NEW column from diff format. Must sit inside a `@@` hunk in the PR diff \u2014 anchors on context-only or untouched lines are dropped silently (the rest of the review still posts; dropped entries are reported under `droppedComments` in the response)."
     ),
     side: type.enumerated("LEFT", "RIGHT").describe(
       "Side of the diff: LEFT (old code, lines starting with -) or RIGHT (new code, lines starting with + or unchanged). Defaults to RIGHT."
@@ -143650,7 +143716,7 @@ var CreatePullRequestReview = type({
       "Full replacement code for the line range [start_line, line]. MUST preserve the exact indentation of the original code."
     ).optional(),
     start_line: type.number.describe(
-      "Start line for multi-line comment ranges. Omit for single-line comments. The range [start_line, line] defines which lines a suggestion replaces."
+      "Start line for multi-line comment ranges. Omit for single-line comments. The range [start_line, line] defines which lines a suggestion replaces. Both `start_line` and `line` must sit inside the same `@@` hunk \u2014 a `start_line` outside the hunk causes the whole comment to be dropped even when `line` is valid. If you need to comment on context just above/below a hunk, shrink the range to a single line that is provably modified."
     ).optional()
   }).array().describe(
     "Inline comments on lines within diff hunks. Feedback about code outside the diff goes in 'body' instead."
@@ -143659,7 +143725,7 @@ var CreatePullRequestReview = type({
 function CreatePullRequestReviewTool(ctx) {
   return tool({
     name: "create_pull_request_review",
-    description: `Submit a review for an existing pull request. Each call creates a permanent, visible review on the PR \u2014 NEVER submit test or diagnostic reviews. Reviews with no body AND no comments are silently skipped (nothing to post). IMPORTANT: 95%+ of feedback should be in 'comments' array with file paths and line numbers. Only use 'body' for a 1-2 sentence summary with urgency and critical callouts. Use 'suggestion' to propose replacement code - MUST preserve exact indentation of original code. The first submission may error once with a one-time diff-coverage nudge listing unread TOC regions \u2014 retry with the same arguments and the pre-flight will not block again. Example replacing lines 42-44 (3 lines) with 5 lines: { path: 'src/api.ts', start_line: 42, line: 44, suggestion: '    const result = await fetch(url);\\n    if (!result.ok) {\\n      log.error(result.status);\\n      throw new Error("request failed");\\n    }' } CONSTRAINT: Inline comments can ONLY target files and lines that appear in the PR diff. Comments anchored outside a diff hunk are dropped automatically (with a note appended to the review body) \u2014 the rest of the review still posts.`,
+    description: `Submit a review for an existing pull request. Example: \`create_pull_request_review({ pull_number: 1234, body: "LGTM", approved: true, comments: [{ path: "src/api.ts", line: 42, body: "nit: rename" }] })\`. Each call creates a permanent, visible review on the PR \u2014 NEVER submit test or diagnostic reviews. Reviews with no body AND no comments are silently skipped (nothing to post). IMPORTANT: 95%+ of feedback should be in 'comments' array with file paths and line numbers. Only use 'body' for a 1-2 sentence summary with urgency and critical callouts. Use 'suggestion' to propose replacement code - MUST preserve exact indentation of original code. The first submission may error once with a one-time diff-coverage nudge listing unread TOC regions \u2014 retry with the same arguments and the pre-flight will not block again. Example replacing lines 42-44 (3 lines) with 5 lines: { path: 'src/api.ts', start_line: 42, line: 44, suggestion: '    const result = await fetch(url);\\n    if (!result.ok) {\\n      log.error(result.status);\\n      throw new Error("request failed");\\n    }' } CONSTRAINT: Inline comments can ONLY target files and lines that appear in the PR diff. Comments anchored outside a diff hunk are dropped automatically (with a note appended to the review body) \u2014 the rest of the review still posts.`,
     parameters: CreatePullRequestReview,
     execute: execute(async ({ pull_number, body, approved, commit_id, comments = [] }) => {
       if (body) body = fixDoubleEscapedString(body);
@@ -143888,7 +143954,7 @@ function runDiffCoveragePreflight(params) {
   );
   const unreadText = unread.map((entry) => `- ${entry.path} (${entry.unreadLines} lines, ${entry.ranges})`).join("\n");
   throw new Error(
-    `diff coverage pre-flight: some TOC regions were not read before review submission. this is a one-time nudge \u2014 optionally read the ranges below from ${coverageState.diffPath}, then call create_pull_request_review again with the same arguments. this pre-flight will not block again in this review session.
+    `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}
@@ -144143,10 +144209,10 @@ async function ensureBeforeShaReachable(params) {
         sha: params.sha,
         ref: tempBranch
       }), true);
-      await $git(
-        "fetch",
+      await $gitFetchWithDeepen(
         ["--no-tags", ...params.isShallow ? ["--depth=1"] : [], "origin", tempBranch],
-        { token: params.gitToken }
+        { token: params.gitToken },
+        `before_sha temp branch ${tempBranch}`
       );
       log.debug(`\xBB fetched before_sha via temp branch ${tempBranch}`);
       return true;
@@ -144222,16 +144288,22 @@ async function checkoutPrBranch(pr, params) {
   toolState.checkoutSha = $("git", ["rev-parse", "HEAD"], { log: false }).trim();
   const alreadyOnBranch = toolState.checkoutSha === pr.headSha;
   log.debug(`\xBB fetching base branch (${pr.baseRef})...`);
-  await $git("fetch", ["--no-tags", "origin", pr.baseRef], { token: gitToken });
+  await $gitFetchWithDeepen(
+    ["--no-tags", "origin", pr.baseRef],
+    { token: gitToken },
+    `base branch ${pr.baseRef}`
+  );
   if (!alreadyOnBranch) {
     $("git", ["checkout", "-B", pr.baseRef, `origin/${pr.baseRef}`], { log: false });
     log.debug(`\xBB fetching PR #${pr.number} (${localBranch})...`);
     await retry(
       async () => {
         try {
-          await $git("fetch", ["--no-tags", "origin", `+pull/${pr.number}/head:${localBranch}`], {
-            token: gitToken
-          });
+          await $gitFetchWithDeepen(
+            ["--no-tags", "origin", `+pull/${pr.number}/head:${localBranch}`],
+            { token: gitToken },
+            `PR #${pr.number}`
+          );
         } catch (e) {
           const msg = e instanceof Error ? e.message : String(e);
           if (PULL_REF_MISSING_PATTERN.test(msg)) {
@@ -144332,134 +144404,159 @@ async function checkoutPrBranch(pr, params) {
   });
   return { hookWarning: postCheckoutHook.warning };
 }
+var inFlightCheckouts = /* @__PURE__ */ new Map();
 function CheckoutPrTool(ctx) {
-  return tool({
-    name: "checkout_pr",
-    description: "Checkout a pull request branch locally. This fetches the PR branch and sets up push configuration for fork PRs. Returns diffPath pointing to the formatted diff file.",
-    parameters: CheckoutPr,
-    execute: execute(async ({ pull_number }) => {
-      const prResponse = await ctx.octokit.rest.pulls.get({
-        owner: ctx.repo.owner,
-        repo: ctx.repo.name,
-        pull_number
-      });
-      const headRepo = prResponse.data.head.repo;
-      if (!headRepo) {
-        throw new Error(`PR #${pull_number} source repository was deleted`);
-      }
-      const pr = {
-        number: pull_number,
-        headSha: prResponse.data.head.sha,
-        headRef: prResponse.data.head.ref,
-        headRepoFullName: headRepo.full_name,
-        baseRef: prResponse.data.base.ref,
-        baseRepoFullName: prResponse.data.base.repo.full_name,
-        maintainerCanModify: prResponse.data.maintainer_can_modify
-      };
-      const checkoutResult = await checkoutPrBranch(pr, {
-        octokit: ctx.octokit,
-        owner: ctx.repo.owner,
-        name: ctx.repo.name,
-        gitToken: ctx.gitToken,
-        toolState: ctx.toolState,
-        shell: ctx.payload.shell,
-        postCheckoutScript: ctx.postCheckoutScript,
-        beforeSha: ctx.toolState.beforeSha
+  const runCheckout = async (pull_number) => {
+    const prResponse = await ctx.octokit.rest.pulls.get({
+      owner: ctx.repo.owner,
+      repo: ctx.repo.name,
+      pull_number
+    });
+    const headRepo = prResponse.data.head.repo;
+    if (!headRepo) {
+      throw new Error(`PR #${pull_number} source repository was deleted`);
+    }
+    const pr = {
+      number: pull_number,
+      headSha: prResponse.data.head.sha,
+      headRef: prResponse.data.head.ref,
+      headRepoFullName: headRepo.full_name,
+      baseRef: prResponse.data.base.ref,
+      baseRepoFullName: prResponse.data.base.repo.full_name,
+      maintainerCanModify: prResponse.data.maintainer_can_modify
+    };
+    const checkoutResult = await checkoutPrBranch(pr, {
+      octokit: ctx.octokit,
+      owner: ctx.repo.owner,
+      name: ctx.repo.name,
+      gitToken: ctx.gitToken,
+      toolState: ctx.toolState,
+      shell: ctx.payload.shell,
+      postCheckoutScript: ctx.postCheckoutScript,
+      beforeSha: ctx.toolState.beforeSha
+    });
+    const tempDir = process.env.PULLFROG_TEMP_DIR;
+    if (!tempDir) {
+      throw new Error(
+        "PULLFROG_TEMP_DIR not set - checkout_pr must run in pullfrog action context"
+      );
+    }
+    const headShort = ctx.toolState.checkoutSha.slice(0, 7);
+    let incrementalDiffPath;
+    if (ctx.toolState.beforeSha && ctx.toolState.checkoutSha) {
+      const beforeShort = ctx.toolState.beforeSha.slice(0, 7);
+      const incremental = computeIncrementalDiff({
+        baseBranch: pr.baseRef,
+        beforeSha: ctx.toolState.beforeSha,
+        headSha: ctx.toolState.checkoutSha
       });
-      const tempDir = process.env.PULLFROG_TEMP_DIR;
-      if (!tempDir) {
-        throw new Error(
-          "PULLFROG_TEMP_DIR not set - checkout_pr must run in pullfrog action context"
+      if (incremental) {
+        incrementalDiffPath = join3(
+          tempDir,
+          `pr-${pull_number}-${beforeShort}-${headShort}-incremental.diff`
+        );
+        writeFileSync(incrementalDiffPath, incremental);
+        log.info(
+          `\xBB incremental diff computed (${incremental.length} bytes) \u2192 ${incrementalDiffPath}`
         );
       }
-      const headShort = ctx.toolState.checkoutSha.slice(0, 7);
-      let incrementalDiffPath;
-      if (ctx.toolState.beforeSha && ctx.toolState.checkoutSha) {
-        const beforeShort = ctx.toolState.beforeSha.slice(0, 7);
-        const incremental = computeIncrementalDiff({
-          baseBranch: pr.baseRef,
-          beforeSha: ctx.toolState.beforeSha,
-          headSha: ctx.toolState.checkoutSha
-        });
-        if (incremental) {
-          incrementalDiffPath = join3(
-            tempDir,
-            `pr-${pull_number}-${beforeShort}-${headShort}-incremental.diff`
-          );
-          writeFileSync(incrementalDiffPath, incremental);
-          log.info(
-            `\xBB incremental diff computed (${incremental.length} bytes) \u2192 ${incrementalDiffPath}`
-          );
-        }
-      }
-      const formatResult = await fetchAndFormatPrDiff(ctx, pull_number);
-      const diffPreview = formatResult.content.split("\n").slice(0, 100).join("\n");
-      log.debug(`formatted diff preview (first 100 lines):
+    }
+    const formatResult = await fetchAndFormatPrDiff(ctx, pull_number);
+    const diffPreview = formatResult.content.split("\n").slice(0, 100).join("\n");
+    log.debug(`formatted diff preview (first 100 lines):
 ${diffPreview}`);
-      const diffPath = join3(tempDir, `pr-${pull_number}-${headShort}.diff`);
-      writeFileSync(diffPath, formatResult.content);
-      log.debug(`wrote diff to ${diffPath} (${formatResult.content.length} bytes)`);
-      ctx.toolState.diffCoverage = createDiffCoverageState({
-        diffPath,
-        totalLines: countLines({ content: formatResult.content }),
-        toc: formatResult.toc,
-        previous: ctx.toolState.diffCoverage
+    const diffPath = join3(tempDir, `pr-${pull_number}-${headShort}.diff`);
+    writeFileSync(diffPath, formatResult.content);
+    log.debug(`wrote diff to ${diffPath} (${formatResult.content.length} bytes)`);
+    ctx.toolState.diffCoverage = createDiffCoverageState({
+      diffPath,
+      totalLines: countLines({ content: formatResult.content }),
+      toc: formatResult.toc,
+      previous: ctx.toolState.diffCoverage
+    });
+    log.debug(
+      `\xBB diff coverage initialized: diffPath=${diffPath}, totalLines=${ctx.toolState.diffCoverage.totalLines}, tocEntries=${ctx.toolState.diffCoverage.tocEntries.length}`
+    );
+    const cached4 = /* @__PURE__ */ new Map();
+    for (const file2 of formatResult.files) {
+      cached4.set(file2.filename, commentableLinesForFile(file2.patch));
+    }
+    ctx.toolState.commentableLinesByFile = cached4;
+    ctx.toolState.commentableLinesPullNumber = pull_number;
+    ctx.toolState.commentableLinesCheckoutSha = ctx.toolState.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 COMMIT_LOG_MAX = 200;
+    const baseRange = `origin/${pr.baseRef}..HEAD`;
+    let commitCount = 0;
+    let commitLog = "";
+    let commitLogUnavailable = false;
+    try {
+      commitCount = parseInt(
+        $("git", ["rev-list", "--count", baseRange], { log: false }).trim() || "0",
+        10
+      );
+      commitLog = $("git", ["log", "--oneline", `--max-count=${COMMIT_LOG_MAX}`, baseRange], {
+        log: false
       });
+    } catch (err) {
+      commitLogUnavailable = true;
       log.debug(
-        `\xBB diff coverage initialized: diffPath=${diffPath}, totalLines=${ctx.toolState.diffCoverage.totalLines}, tocEntries=${ctx.toolState.diffCoverage.tocEntries.length}`
+        `\xBB unable to compute commit metadata for ${baseRange}: ${err instanceof Error ? err.message : String(err)}`
       );
-      const cached4 = /* @__PURE__ */ new Map();
-      for (const file2 of formatResult.files) {
-        cached4.set(file2.filename, commentableLinesForFile(file2.patch));
-      }
-      ctx.toolState.commentableLinesByFile = cached4;
-      ctx.toolState.commentableLinesPullNumber = pull_number;
-      ctx.toolState.commentableLinesCheckoutSha = ctx.toolState.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 COMMIT_LOG_MAX = 200;
-      const baseRange = `origin/${pr.baseRef}..HEAD`;
-      let commitCount = 0;
-      let commitLog = "";
-      let commitLogUnavailable = false;
+    }
+    const commitLogTruncated = commitCount > COMMIT_LOG_MAX;
+    const hookWarningInstructions = checkoutResult.hookWarning ? ` HOOK WARNING: the post-checkout lifecycle hook reported a non-fatal failure (see hookWarning). decide whether to retry based on the guidance in that field before proceeding.` : "";
+    const commitLogInstructions = commitLogUnavailable ? ` NOTE: commit metadata is partial (base ref unreachable, likely a shallow fetch). commitCount/commitLog may be 0/empty or incomplete; treat them as "unknown" rather than "no commits", and use \`git log\` directly if you need the full history.` : commitLogTruncated ? ` NOTE: commitLog was capped at ${COMMIT_LOG_MAX} entries out of ${commitCount} commits; use \`git log\` directly if you need the full history.` : "";
+    return {
+      success: true,
+      number: prResponse.data.number,
+      title: prResponse.data.title,
+      body: prResponse.data.body,
+      base: pr.baseRef,
+      localBranch: `pr-${pull_number}`,
+      remoteBranch: `refs/heads/${pr.headRef}`,
+      isFork: pr.headRepoFullName !== pr.baseRepoFullName,
+      maintainerCanModify: pr.maintainerCanModify,
+      url: prResponse.data.html_url,
+      headRepo: pr.headRepoFullName,
+      diffPath,
+      incrementalDiffPath,
+      toc: formatResult.toc,
+      commitCount,
+      commitLog,
+      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 <base>..<head>\` to re-derive what's already in diffPath. the formatted diff with line numbers is authoritative. \`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
+    };
+  };
+  return tool({
+    name: "checkout_pr",
+    description: "Checkout a pull request branch locally. This fetches the PR branch and sets up push configuration for fork PRs. Returns diffPath pointing to the formatted diff file. Example: `checkout_pr({ pull_number: 1234 })`. Transient fetch timeouts are common \u2014 retry the same call up to a few times before treating the failure as terminal. If the error mentions `.git/shallow.lock: File exists` or `.git/index.lock: File exists`, that's a stale lock from a prior timed-out fetch \u2014 remove it via the shell tool (`rm -f .git/shallow.lock .git/index.lock`) and retry.",
+    parameters: CheckoutPr,
+    execute: execute(async ({ pull_number }) => {
+      const inFlight = inFlightCheckouts.get(pull_number);
+      if (inFlight) {
+        log.info(`\xBB checkout_pr({pull_number:${pull_number}}) already in flight \u2014 sharing result`);
+        return inFlight;
+      }
+      const current = ctx.toolState.issueNumber;
+      if (current !== void 0 && current !== pull_number) {
+        const dirty = $("git", ["status", "--porcelain"], { log: false }).trim();
+        if (dirty) {
+          throw new Error(
+            `cannot checkout PR #${pull_number} while the working tree has uncommitted changes. commit, push, or discard them before switching. dirty paths:
+${dirty}`
+          );
+        }
+      }
+      const promise2 = runCheckout(pull_number);
+      inFlightCheckouts.set(pull_number, promise2);
       try {
-        commitCount = parseInt(
-          $("git", ["rev-list", "--count", baseRange], { log: false }).trim() || "0",
-          10
-        );
-        commitLog = $("git", ["log", "--oneline", `--max-count=${COMMIT_LOG_MAX}`, baseRange], {
-          log: false
-        });
-      } catch (err) {
-        commitLogUnavailable = true;
-        log.debug(
-          `\xBB unable to compute commit metadata for ${baseRange}: ${err instanceof Error ? err.message : String(err)}`
-        );
+        return await promise2;
+      } finally {
+        inFlightCheckouts.delete(pull_number);
       }
-      const commitLogTruncated = commitCount > COMMIT_LOG_MAX;
-      const hookWarningInstructions = checkoutResult.hookWarning ? ` HOOK WARNING: the post-checkout lifecycle hook reported a non-fatal failure (see hookWarning). decide whether to retry based on the guidance in that field before proceeding.` : "";
-      const commitLogInstructions = commitLogUnavailable ? ` NOTE: commit metadata is partial (base ref unreachable, likely a shallow fetch). commitCount/commitLog may be 0/empty or incomplete; treat them as "unknown" rather than "no commits", and use \`git log\` directly if you need the full history.` : commitLogTruncated ? ` NOTE: commitLog was capped at ${COMMIT_LOG_MAX} entries out of ${commitCount} commits; use \`git log\` directly if you need the full history.` : "";
-      return {
-        success: true,
-        number: prResponse.data.number,
-        title: prResponse.data.title,
-        body: prResponse.data.body,
-        base: pr.baseRef,
-        localBranch: `pr-${pull_number}`,
-        remoteBranch: `refs/heads/${pr.headRef}`,
-        isFork: pr.headRepoFullName !== pr.baseRepoFullName,
-        maintainerCanModify: pr.maintainerCanModify,
-        url: prResponse.data.html_url,
-        headRepo: pr.headRepoFullName,
-        diffPath,
-        incrementalDiffPath,
-        toc: formatResult.toc,
-        commitCount,
-        commitLog,
-        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 <base>..<head>\` to re-derive what's already in diffPath. the formatted diff with line numbers is authoritative. \`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
-      };
     })
   });
 }
@@ -144646,7 +144743,7 @@ var CommitInfo = type({
 function CommitInfoTool(ctx) {
   return tool({
     name: "get_commit_info",
-    description: "Retrieve commit metadata and diff via GitHub API. Use this instead of git show for reviewing commits - it works with shallow clones and shows the actual changes in the commit. Returns diffPath pointing to formatted diff file.",
+    description: 'Retrieve commit metadata and diff via GitHub API. Use this instead of git show for reviewing commits - it works with shallow clones and shows the actual changes in the commit. Returns diffPath pointing to formatted diff file. Example: `get_commit_info({ sha: "2a6ab5d" })`.',
     parameters: CommitInfo,
     execute: execute(async ({ sha }) => {
       const response = await ctx.octokit.rest.repos.getCommit({
@@ -144737,7 +144834,7 @@ var GetIssueComments = type({
 function GetIssueCommentsTool(ctx) {
   return tool({
     name: "get_issue_comments",
-    description: "Get all comments for a GitHub issue. Returns all comments including the issue body and all subsequent discussion comments.",
+    description: "Get all comments for a GitHub issue. Returns all comments including the issue body and all subsequent discussion comments. Example: `get_issue_comments({ issue_number: 1234 })`.",
     parameters: GetIssueComments,
     execute: execute(async ({ issue_number }) => {
       ctx.toolState.issueNumber = issue_number;
@@ -144838,7 +144935,7 @@ var IssueInfo = type({
 function IssueInfoTool(ctx) {
   return tool({
     name: "get_issue",
-    description: "Retrieve GitHub issue information by issue number",
+    description: "Retrieve GitHub issue information by issue number. Example: `get_issue({ issue_number: 1234 })`.",
     parameters: IssueInfo,
     execute: execute(async ({ issue_number }) => {
       const issue3 = await ctx.octokit.rest.issues.get({
@@ -145080,7 +145177,7 @@ var PullRequestInfo = type({
 function PullRequestInfoTool(ctx) {
   return tool({
     name: "get_pull_request",
-    description: "Retrieve PR metadata (title, body, state, branches, author, labels, linked issues). To checkout a PR branch locally, use checkout_pr instead.",
+    description: "Retrieve PR metadata (title, body, state, branches, author, labels, linked issues). Example: `get_pull_request({ pull_number: 1234 })`. To checkout a PR branch locally, use checkout_pr instead.",
     parameters: PullRequestInfo,
     execute: execute(async ({ pull_number }) => {
       const [restResponse, graphqlResponse] = await Promise.all([
@@ -145484,7 +145581,7 @@ async function getReviewData(input) {
 function GetReviewCommentsTool(ctx) {
   return tool({
     name: "get_review_comments",
-    description: "Get review comments for a pull request review with full thread context. Automatically filters to approved comments when applicable. Returns a TOC and commentsPath pointing to a markdown file with full comment details.",
+    description: "Get review comments for a pull request review with full thread context. Example: `get_review_comments({ pull_number: 1234, review_id: 567890 })`. Automatically filters to approved comments when applicable. Returns a TOC and commentsPath pointing to a markdown file with full comment details.",
     parameters: GetReviewComments,
     execute: execute(async (params) => {
       const approvedBy = ctx.payload.event.trigger === "fix_review" && ctx.payload.event.approved_only ? ctx.payload.triggerer : void 0;
@@ -145534,7 +145631,7 @@ var ListPullRequestReviews = type({
 function ListPullRequestReviewsTool(ctx) {
   return tool({
     name: "list_pull_request_reviews",
-    description: "List all reviews for a pull request. Returns all reviews including approvals, request changes, and comments.",
+    description: "List all reviews for a pull request. Returns all reviews including approvals, request changes, and comments. Example: `list_pull_request_reviews({ pull_number: 1234 })`.",
     parameters: ListPullRequestReviews,
     execute: execute(async (params) => {
       const reviews = await ctx.octokit.paginate(ctx.octokit.rest.pulls.listReviews, {
@@ -145684,7 +145781,7 @@ function SelectModeTool(ctx) {
   const overrides = buildModeOverrides(t);
   return tool({
     name: "select_mode",
-    description: "Select a mode and receive step-by-step guidance on how to handle the task. Call this to understand the best workflow for the current mode.",
+    description: 'Select a mode and receive step-by-step guidance on how to handle the task. Call this to understand the best workflow for the current mode. Example: `select_mode({ mode: "Review" })` or `select_mode({ mode: "Plan", issue_number: 1234 })`.',
     parameters: SelectModeParams,
     execute: execute(async (params) => {
       if (ctx.toolState.selectedMode) {
@@ -145745,7 +145842,9 @@ import { setTimeout as sleep2 } from "node:timers/promises";
 var ShellParams = type({
   command: "string",
   description: "string",
-  "timeout?": "number",
+  "timeout?": type.number.describe(
+    "Timeout in MILLISECONDS (not seconds). Default 30000 (30s), max 120000 (2m). e.g. timeout: 180000 for 3 minutes; timeout: 180 means 180ms and will kill the process almost immediately."
+  ),
   "working_directory?": "string",
   "background?": "boolean"
 });
@@ -145853,6 +145952,15 @@ function getTempDir() {
   }
   return tempDir;
 }
+var MAX_OUTPUT_CHARS = 5e3;
+function capOutput(output) {
+  if (output.length <= MAX_OUTPUT_CHARS) return output;
+  const fullPath = join7(getTempDir(), `shell-${randomUUID2().slice(0, 8)}.log`);
+  writeFileSync5(fullPath, output);
+  const elided = output.length - MAX_OUTPUT_CHARS;
+  return `... [${elided} chars truncated; full output saved to ${fullPath}] ...
+${output.slice(-MAX_OUTPUT_CHARS)}`;
+}
 function isGitCommand(command) {
   const trimmed = command.trim();
   if (trimmed === "git" || trimmed.startsWith("git ")) return true;
@@ -145864,11 +145972,15 @@ function ShellTool(ctx) {
     name: "shell",
     description: `Execute shell commands securely. Environment is filtered to remove API keys and secrets.
 
+Example: \`shell({ command: "pnpm test", description: "run the test suite" })\`.
+
 Use this tool to:
 - Run shell commands (ls, cat, grep, find, etc.)
 - Execute build tools (npm, pnpm, cargo, make, etc.)
 - Run tests and linters
 
+Output is capped at ${MAX_OUTPUT_CHARS} chars: if exceeded, only the tail is returned and the full body is saved to a tempfile (path included in the response). Re-read the tempfile with cat/tail/grep when you need more.
+
 Do NOT use this tool for git commands \u2014 use the dedicated git tools instead.`,
     parameters: ShellParams,
     execute: execute(async (params) => {
@@ -145959,12 +146071,13 @@ ${stderr}` : stderr : stdout;
         output = output ? `${output}
 [timed out after ${timeout}ms]` : `[timed out after ${timeout}ms]`;
       const finalExitCode = exitCode ?? (timedOut ? 124 : -1);
+      const trimmed = output.trim();
       if (finalExitCode !== 0) {
         log.info(`shell command failed with exit code ${finalExitCode}: ${params.command}`);
-        if (output) log.info(`output: ${output.trim()}`);
+        if (trimmed) log.info(`output: ${trimmed}`);
       }
       return {
-        output: output.trim(),
+        output: capOutput(trimmed),
         exit_code: finalExitCode,
         timed_out: timedOut
       };
@@ -146381,18 +146494,24 @@ For simple, well-defined tasks, skip the plan phase and go straight to build.`
    - resolve addressed threads via \`${t("resolve_review_thread")}\`
    - call \`${t("report_progress")}\` with a brief summary (or the exact push error if push failed)`
     },
-    // Review and IncrementalReview use the multi-lens orchestrator pattern
-    // (canonical source: .claude/commands/anneal.md). The orchestrator does
-    // triage → parallel read-only subagent fan-out → aggregate → draft comments
-    // → submit. For someone else's PR, parallel lenses (correctness, security,
-    // research-validated claims, user-journey, etc.) provide breadth across
-    // angles that a single subagent can't carry coherently. Build mode keeps
-    // a single fresh-eyes subagent (different problem shape — orchestrator
-    // wrote the code and bias-mitigation comes from delegating to one
-    // subagent that doesn't share the implementation context).
-    // Deliberate omission vs canonical /anneal: severity categorization in the
-    // final message (the review body has its own CAUTION/IMPORTANT framing
-    // instead of a severity table).
+    // 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.
+    //
+    // 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.
+    //
+    // Deliberate omission vs canonical /anneal: severity categorization in
+    // the final message (the review body has its own CAUTION/IMPORTANT
+    // framing instead of a severity table).
     {
       name: "Review",
       description: "Review code, PRs, or implementations; provide feedback or suggestions; identify issues; or check code quality, style, and correctness",
@@ -146402,9 +146521,9 @@ For simple, well-defined tasks, skip the plan phase and go straight to build.`
 
 2. **checkout**: call \`${t("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.
 
-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). orientation only \u2014 defer specific defect-hunting to the subagents; pre-reviewing biases the lenses you pick. use \`${t("get_pull_request")}\` and other read-only GitHub tools for additional context if needed.
+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 steps 4\u20135 entirely and submit a \`No new issues found.\` review per step 6. there's no value in dispatching even one lens for a typo.
+   if the PR is **genuinely trivial**, skip the fan-out 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
@@ -146423,25 +146542,25 @@ 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
 
-   When unsure, treat as non-trivial. The cost of one extra subagent is cents; the cost of a missed billing/auth/data bug is much more.
+4. **lens decision \u2014 0 or 2+, NEVER 1**.
 
-   otherwise pick lenses by where the PR concentrates risk \u2014 **there's no fixed count**. lens count is judgment, not a formula. concrete shapes to anchor against:
+   The default is **0 lenses**: handle the review yourself end-to-end. Most PRs land here.
 
-   - **1 lens** \u2014 pure refactor / mechanical rename across many files (impact); new test file with no source change (test-integrity); small isolated bug fix (correctness); doc-only PR with non-trivial technical content (research-validated or holistic)
-   - **2\u20133 lenses (most PRs land here)** \u2014 new CRUD endpoint (correctness + security + test-integrity); new UI flow (user-journey + correctness); a single bug fix in a non-critical subsystem (correctness + test-integrity); design doc covering one domain (research-validated + correctness or holistic)
-   - **4\u20135 lenses (high-stakes subsystem touches)** \u2014 any billing/payments change (billing-subsystem + correctness + security + operational-readiness); new auth flow (auth-subsystem + correctness + security + test-integrity); schema migration (schema-migration-subsystem + correctness + operational-readiness + impact); cross-subsystem PR that touches billing AND auth AND schema (one subsystem lens per domain + correctness)
-   - **6+ lenses** \u2014 almost always a smell; you're either covering overlapping ground or this PR should have been split. push back via the review body rather than expanding lens count.
+   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
 
-   **lens-add discipline.** Each lens needs to clear a specific bar before you dispatch it: name the concrete failure mode this lens would catch *that the diff plausibly introduces*, in one sentence. "Could apply", "good to have", "for completeness" do not qualify. If you can't name what the lens is going to find, drop it. The "when unsure, treat as non-trivial" rule above is for the trivial-vs-non-trivial gate at step 3 \u2014 it does not license expanding lens count without articulated risk. Every extra lens adds wall-time, log noise, and pulls subagent attention onto speculative angles, which biases the final review toward bloat-shaped findings.
+   **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).
 
-   lenses come in two flavors, and you can mix them:
+   When you do go multi-lens, lens framings come in two flavors:
    - **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"). a subsystem lens is "review the PR specifically for what could go wrong in this subsystem" and naturally combines theme + scope. **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.
+   - **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):
    - **correctness & invariants** \u2014 bugs, races, error handling, edge cases, state-machine boundaries
-   - **impact** \u2014 when the PR removes features, deletes exports, renames identifiers, or changes architectural patterns: stale references in code, tests, docs (\`docs/\`, \`wiki/\`), comments, configs, UI
-   - **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. An idempotency key as a backstop, a timeout as a hint, a retry as belt-and-suspenders: not load-bearing, skip this lens. 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.
+   - **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.
    - **security** \u2014 new endpoints, authZ, input validation, secrets handling, replay/CSRF/injection, cross-tenant isolation
    - **user-journey** \u2014 UX-touching flows: walk through happy path and failure modes as a user
    - **operational readiness** \u2014 observability, alerting, migrations (forward + rollback), feature flags, on-call burden
@@ -146451,26 +146570,36 @@ For simple, well-defined tasks, skip the plan phase and go straight to build.`
    - **holistic** \u2014 does the PR make sense as a whole? symmetric flows (delete for every create, rollback for every migration)?
    - **subsystem lenses** (invent as the PR demands) \u2014 auth, billing, payments, schema migration, webhooks, secrets, RBAC, multi-tenant isolation, cron/scheduling, etc.
 
-4. **fan out**: dispatch one \`${REVIEWER_AGENT_NAME}\` subagent per lens \u2014 its baked-in system prompt enforces the non-mutative + non-recursive contract (read-only file/search/web tools and read-only MCP queries; no writes, shell side effects, state-changing MCP calls, or nested subagent dispatch). when picking 2+ lenses, dispatch them in a **single assistant turn with multiple parallel subagent calls**; issuing one and awaiting reply before the next collapses the fan-out into a serial review. 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 step 4 entirely on a single subagent failure. each subagent gets:
+   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.
+
+   \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.
+
+   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:
    - the diff path / target \u2014 reading the diff and the codebase is 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\`.
-   - the read-only contract restated in your dispatch instructions so the rule is present twice (the subagent's system prompt also enforces it). The test: would this call still be a no-op if reverted? If not (PR comments, branch pushes, issue updates, set_output, label changes, dependency installs, etc.), don't make it.
    - 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.
 
    delegation discipline:
-   - do NOT lens-review the diff yourself in parallel with the subagents (your job is dispatch + comment-drafting; doing the lens work yourself reintroduces the bias the fan-out avoids)
    - do NOT summarize the PR for them (biases toward a validation frame)
    - 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)
 
-5. **aggregate & draft**: 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 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.
 
    for surviving findings, draft inline comments with NEW line numbers from the diff. every comment must be actionable, 2-3 sentences max. use GitHub permalink format for code references. for impact-analysis findings (stale references after rename/remove), report them in the review body ordered by severity (runtime breakage > incorrect docs > stale comments) rather than as inline comments unless they're anchored to a specific line.
 
-6. **submit**: ALWAYS submit exactly one review via \`${t("create_pull_request_review")}\`. Do NOT call \`report_progress\` \u2014 the review is the final record and the progress comment will be cleaned up automatically.
+7. **submit**: ALWAYS submit exactly one review via \`${t("create_pull_request_review")}\`. Do NOT call \`report_progress\` \u2014 the review is the final record and the progress comment will be cleaned up automatically.
 
    note: the first create_pull_request_review submission may error with a one-time diff-coverage nudge listing unread TOC regions. retry the same call to proceed \u2014 optionally after reading the listed ranges. the pre-flight will not block again this session.
 
@@ -146498,10 +146627,10 @@ For simple, well-defined tasks, skip the plan phase and go straight to build.`
 
 ${PR_SUMMARY_FORMAT}`
     },
-    // IncrementalReview shares Review's multi-lens orchestrator pattern but
-    // scopes the target to the incremental diff. The "issues must be NEW
-    // since the last Pullfrog review" filter lives at aggregation time
-    // (step 6), NOT in the subagent prompt — pushing the filter into
+    // IncrementalReview shares Review's 0-or-2+ lens pattern but scopes the
+    // target to the incremental diff. The "issues must be NEW since the last
+    // Pullfrog review" filter lives at aggregation time (step 8), 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. The review body is just
@@ -146520,38 +146649,57 @@ ${PR_SUMMARY_FORMAT}`
 
 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.
 
-4. **prior feedback**: fetch previous reviews via \`${t("list_pull_request_reviews")}\`. for the most recent Pullfrog review, call \`${t("get_review_comments")}\` with the review ID to retrieve specific prior line-level feedback. you'll use this to filter your aggregation in step 6 \u2014 anything already flagged in a prior review and not changed by the new commits should not be re-raised. you do NOT need to render this in the review body; the rolling PR summary snapshot is the durable record of what's been addressed.
+4. **prior feedback**: fetch previous reviews via \`${t("list_pull_request_reviews")}\`. for the most recent Pullfrog review, call \`${t("get_review_comments")}\` with the review ID to retrieve specific prior line-level feedback. you'll use this to filter your aggregation in step 8 \u2014 anything already flagged in a prior review and not changed by the new commits should not be re-raised. you do NOT need to render this in the review body; the rolling PR summary snapshot is the durable record of what's been addressed.
 
-5. **triage & fan out**: orient on the *incremental* changes \u2014 domain, seams, external contracts, user-facing surfaces.
+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 8's non-substantive path (do NOT submit a review).
+   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).
 
    "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.
 
-   otherwise pick lenses by where the new commits concentrate risk \u2014 **there's no fixed count**, same calibration as Review mode (1 lens for pure refactor / isolated fix; 2\u20133 for typical features; 4\u20135 for high-stakes subsystem touches; 6+ is a smell). same **lens-add discipline** as Review mode applies: each lens needs to name the concrete failure mode it would catch *that the new commits plausibly introduce* \u2014 "could apply" doesn't qualify, drop it. **research-validated assumptions** specifically: only pick when the new commits' correctness depends on a third-party contract behaving a specific way; merely using an API doesn't qualify. lens framing follows Review mode: themed lenses (correctness & invariants, impact when new commits remove/rename/deprecate things, research-validated assumptions, security, user-journey, operational readiness, integration & cross-cutting, test integrity, performance, holistic) and subsystem lenses (auth, billing, schema migration, etc.) \u2014 for high-stakes domains lead with the subsystem lens rather than the generic themed equivalent.
+6. **lens decision \u2014 0 or 2+, NEVER 1**.
+
+   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."
+
+   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
+
+   **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.
 
-   dispatch one \`${REVIEWER_AGENT_NAME}\` subagent per lens \u2014 its baked-in system prompt enforces the non-mutative + non-recursive contract (read-only file/search/web tools and read-only MCP queries; no writes, shell side effects, state-changing MCP calls, or nested subagent dispatch). dispatch them in a **single assistant turn with multiple parallel subagent calls** (serial dispatch collapses the fan-out). 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 step 5 entirely on a single subagent failure. each subagent gets:
-   - the diff scope (incremental diff path if available, full diff otherwise). 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 6), not in the subagent prompt
+   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.
+
+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.**
+
+   \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.
+
+   \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.
+
+   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:
+   - the diff scope (incremental diff path if available, full diff otherwise). 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** (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\`.
-   - the read-only contract restated in your dispatch instructions so the rule is present twice (the subagent's system prompt also enforces it). The test: would this call still be a no-op if reverted? If not (PR comments, branch pushes, issue updates, set_output, label changes, dependency installs, etc.), don't make it.
-   - if the lens touches external contracts, instruct the subagent to verify load-bearing claims via web search and quote source URLs. action runs are non-interactive \u2014 there's no human to catch "I'm pretty sure Stripe does X."
+   - **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.
+   - 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.
 
    delegation discipline:
-   - do NOT lens-review the diff yourself in parallel with the subagents
    - do NOT summarize the changes for them (biases toward validation frame)
    - 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)
 
-6. **aggregate, draft, self-critique**: merge findings; 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 \`${t("list_pull_request_reviews")}\` in step 4) and run \`git diff <prior-review-sha>..HEAD\` to isolate the lines added since that review. draft inline comments with NEW line numbers from the full PR diff \u2014 every comment must be actionable, 2-3 sentences max.
+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 \`${t("list_pull_request_reviews")}\` in step 4) and run \`git diff <prior-review-sha>..HEAD\` to isolate the lines added since that review. draft inline comments with NEW line numbers from the full PR diff \u2014 every comment must be actionable, 2-3 sentences max.
 
-7. **build the review body** \u2014 a single "Reviewed changes" section: summarize at the logical-change level, not per-file. each bullet starts with a past-tense verb (e.g. \`- Extracted shared CLI runtime into a single module\`, \`- Renamed package to pullfrog\`). avoid file paths unless they add clarity. if the changes can be described in one sentence, use one sentence \u2014 no bullets needed. do NOT include a separate "Prior review feedback" checklist; that's tracked in the rolling PR summary snapshot for the next agent run, and surfacing it in the user-facing body is noise (changes that addressed prior feedback are already covered by the Reviewed-changes bullets). in some cases you may receive a complete diff for the whole pull request instead of an incremental one \u2014 when this happens, you will need to determine what changes have happened since Pullfrog's most recent review.
+9. **build the review body** \u2014 a single "Reviewed changes" section: summarize at the logical-change level, not per-file. each bullet starts with a past-tense verb (e.g. \`- Extracted shared CLI runtime into a single module\`, \`- Renamed package to pullfrog\`). avoid file paths unless they add clarity. if the changes can be described in one sentence, use one sentence \u2014 no bullets needed. do NOT include a separate "Prior review feedback" checklist; that's tracked in the rolling PR summary snapshot for the next agent run, and surfacing it in the user-facing body is noise (changes that addressed prior feedback are already covered by the Reviewed-changes bullets). in some cases you may receive a complete diff for the whole pull request instead of an incremental one \u2014 when this happens, you will need to determine what changes have happened since Pullfrog's most recent review.
 
-8. Submit \u2014 every run must end with EXACTLY ONE of \`${t("create_pull_request_review")}\` (substantive review) or \`${t("report_progress")}\` (no-review acknowledgement). do NOT call \`create_issue_comment\` for review output.
+10. Submit \u2014 every run must end with EXACTLY ONE of \`${t("create_pull_request_review")}\` (substantive review) or \`${t("report_progress")}\` (no-review acknowledgement). do NOT call \`create_issue_comment\` for review output.
 
    Same callout-intensity ladder as Review mode \u2014 \`[!CAUTION]\` (large red, "will break") \u2192 \`[!IMPORTANT]\` (large purple, "must address before merging") \u2192 \`[!NOTE]\` (small blue, "FYI") \u2192 no callout (plain text). And the same Fix-button lever: the footer renders a Fix button on every non-approving review, so \`approved: true\` suppresses it. Wrapping mergeable feedback in \`[!IMPORTANT]\` trains users to click Fix on reviews that don't need fixing \u2014 pick the tier the author's actual next action justifies.
 
@@ -146802,12 +146950,38 @@ var PROVIDER_ERROR_PATTERNS = [
   // around `limit` rejects keys like `time_limit` or `field_limit`.
   { regex: /["']?\blimit\b["']?\s*:\s*0\b/, label: "zero quota" }
 ];
-function detectProviderError(text) {
+var EXCERPT_MAX_BYTES = 600;
+var LINES_BEFORE = 1;
+var LINES_AFTER = 2;
+function findProviderErrorMatch(text) {
   for (const entry of PROVIDER_ERROR_PATTERNS) {
-    if (entry.regex.test(text)) return entry.label;
+    const m = entry.regex.exec(text);
+    if (!m) continue;
+    return { label: entry.label, excerpt: extractExcerpt(text, m.index) };
   }
   return null;
 }
+function extractExcerpt(text, matchIndex) {
+  const lineStart = text.lastIndexOf("\n", matchIndex - 1) + 1;
+  const lineEndRaw = text.indexOf("\n", matchIndex);
+  const lineEnd = lineEndRaw === -1 ? text.length : lineEndRaw;
+  let start = lineStart;
+  for (let i = 0; i < LINES_BEFORE && start > 0; i++) {
+    const prev = text.lastIndexOf("\n", start - 2);
+    start = prev < 0 ? 0 : prev + 1;
+  }
+  let end = lineEnd;
+  for (let i = 0; i < LINES_AFTER && end < text.length; i++) {
+    const next2 = text.indexOf("\n", end + 1);
+    end = next2 < 0 ? text.length : next2;
+  }
+  let excerpt = text.slice(start, end);
+  if (excerpt.length > EXCERPT_MAX_BYTES) {
+    excerpt = text.slice(lineStart, lineEnd);
+    if (excerpt.length > EXCERPT_MAX_BYTES) excerpt = excerpt.slice(0, EXCERPT_MAX_BYTES);
+  }
+  return excerpt.trim();
+}
 var ROUTER_KEYLIMIT_EXHAUSTED_PATTERN = /requires more credits.*?fewer max_tokens|requested up to \d+ tokens.*?can only afford/is;
 function isRouterKeylimitExhaustedError(text) {
   return ROUTER_KEYLIMIT_EXHAUSTED_PATTERN.test(text);
@@ -146931,45 +147105,12 @@ var ThinkingTimer = class {
 import { readFile } from "node:fs/promises";
 function getUnsubmittedReview(toolState) {
   const mode = toolState.selectedMode;
-  if (mode !== "Review" && mode !== "IncrementalReview") return null;
-  if (toolState.review || toolState.finalSummaryWritten) return null;
   if (!toolState.hadProgressComment) return null;
-  return mode;
-}
-var MAX_HOOK_OUTPUT_CHARS = 4096;
-function truncateHookOutput(raw2) {
-  if (raw2.length <= MAX_HOOK_OUTPUT_CHARS) return raw2;
-  return `...(truncated, showing last ${MAX_HOOK_OUTPUT_CHARS} chars)
-${raw2.slice(-MAX_HOOK_OUTPUT_CHARS)}`;
-}
-async function executeStopHook(script) {
-  log.info("\xBB executing stop hook...");
-  try {
-    const result = await spawn({
-      cmd: "bash",
-      args: ["-c", script],
-      env: process.env,
-      timeout: LIFECYCLE_HOOK_TIMEOUT_MS,
-      activityTimeout: 0,
-      onStdout: (chunk) => process.stdout.write(chunk),
-      onStderr: (chunk) => process.stderr.write(chunk)
-    });
-    if (result.exitCode === 0) {
-      log.info("\xBB stop hook passed");
-      return null;
-    }
-    const combined = [result.stderr.trim(), result.stdout.trim()].filter(Boolean).join("\n");
-    const output = truncateHookOutput(combined);
-    log.info(`\xBB stop hook failed with exit code ${result.exitCode}`);
-    return { exitCode: result.exitCode, output };
-  } catch (err) {
-    const isTimeout = err instanceof SpawnTimeoutError && (err.code === SPAWN_TIMEOUT_CODE || err.code === SPAWN_ACTIVITY_TIMEOUT_CODE);
-    const msg = err instanceof Error ? err.message : String(err);
-    log.warning(
-      `stop hook ${isTimeout ? "timed out" : "failed to spawn"}: ${msg} \u2014 skipping retry`
-    );
-    return null;
+  if (mode === "Review") return toolState.review ? null : "Review";
+  if (mode === "IncrementalReview") {
+    return toolState.review || toolState.finalSummaryWritten ? null : "IncrementalReview";
   }
+  return null;
 }
 function buildStopHookPrompt(failure) {
   return [
@@ -147019,10 +147160,6 @@ function buildUnsubmittedReviewPrompt(mode) {
 }
 async function collectPostRunIssues(ctx, options = {}) {
   const issues = {};
-  if (ctx.stopScript) {
-    const failure = await executeStopHook(ctx.stopScript);
-    if (failure) issues.stopHook = failure;
-  }
   const status = getGitStatus();
   const mode = ctx.toolState.selectedMode;
   if (status) {
@@ -147058,11 +147195,25 @@ function buildLearningsReflectionPrompt(filePath) {
     "",
     `the rolling learnings file is at \`${filePath}\`. read it first if you haven't already, then edit it in place using your native file tools. the server reads this file at end-of-run and persists any changes \u2014 there is no tool to call.`,
     "",
-    `keep the file healthy:`,
-    `- only add bullets when the finding is high-confidence AND broadly useful. skip speculative, one-off, or "maybe" findings.`,
-    `- prune bullets that are clearly wrong, no longer relevant, or low-signal (rarely useful). a focused, accurate file beats a long stale one.`,
-    `- format: flat bullet list, one fact per line starting with \`- \`. deduplicate against existing entries \u2014 if a bullet covers the same fact, update it in place instead of adding a duplicate.`,
-    `- leave the file alone if you have nothing substantively new to add and the existing entries still look healthy. silence is a valid outcome \u2014 just reply "done" and stop.`
+    `structure:`,
+    `- markdown hierarchy: \`## \` for top-level themes, \`### \` and deeper for sub-themes when a section grows. there is no fixed taxonomy \u2014 choose headings that fit THIS repo (e.g. for one repo \`## Migrations\` / \`## Local dev\` may make sense; for another, \`## API quirks\` / \`## Failure modes\`).`,
+    `- **no section over ~300 lines.** when a section is approaching that, split it: introduce \`### \` subsections grouping related bullets, or hoist a coherent group into a new top-level \`## \` section. granular sections mean future runs read targeted line ranges instead of slurping the whole file. this is the most important hygiene rule on long-lived repos.`,
+    `- if you find a flat unstructured list (legacy content from before this format), restructure it: read it, group related bullets, rewrite the file with \`## \` / \`### \` headings around them. don't preserve bad structure \u2014 fix it.`,
+    "",
+    `bullet hygiene:`,
+    `- one fact per line starting with \`- \`. each bullet is ONE specific durable fact, not a paragraph or essay.`,
+    `- aim for \u2264 240 chars per bullet. longer bullets are almost always mixing multiple facts that should be split, or burying the durable claim under PR-specific context that should be cut.`,
+    `- only add bullets when the finding is high-confidence AND broadly useful AND will still be true in 3+ months. skip speculative, one-off, or "maybe" findings.`,
+    `- prune bullets that are clearly wrong, no longer relevant, or low-signal. a focused, accurate file beats a long stale one. compressing two overlapping bullets into one tighter bullet counts as progress.`,
+    `- deduplicate against existing entries (in any section) \u2014 if a bullet covers the same fact, update it in place instead of adding a duplicate.`,
+    "",
+    `do NOT add bullets for:`,
+    `- pullfrog tool quirks (e.g. "\`shell\` timeout is in milliseconds", "\`git\` args must be a JSON array", "\`create_pull_request_review\` drops out-of-hunk comments", "\`push_branch\` may report timeout when push succeeded"). these are universal across repos and belong in the tool descriptions \u2014 flag the gap rather than hoarding the workaround per-repo.`,
+    `- references to specific PR numbers, review IDs, commit SHAs, branch names, or person handles ("PR #595 introduced X", "flagged in review 12345", "as of commit abc123"). repo state changes; these decay into noise within weeks.`,
+    `- dated assertions ("as of May 2026", "currently...", "for now..."). if a fact needs a date to be true, it isn't durable enough to belong here.`,
+    `- play-by-play of what THIS run did. learnings are for the NEXT run, not a retrospective.`,
+    "",
+    `if you have nothing substantively new to add AND the existing entries still look healthy and well-structured, leave the file alone \u2014 just reply "done" and stop. silence is a valid outcome.`
   ].join("\n");
 }
 async function runPostRunRetryLoop(params) {
@@ -147266,8 +147417,9 @@ function writeMcpConfig(ctx) {
 function buildAgentsJson() {
   const agents2 = {
     [REVIEWER_AGENT_NAME]: {
-      description: "Read-only review subagent for self-review and lens-based code review. Reads only \u2014 no writes, no state-changing shell or MCP calls, no nested subagent dispatch.",
-      prompt: REVIEWER_SYSTEM_PROMPT
+      description: "Read-only review subagent for lens-based code review (correctness, security, billing-subsystem, etc.). Reads only \u2014 no writes, no state-changing shell or MCP calls, no nested subagent dispatch.",
+      prompt: REVIEWER_SYSTEM_PROMPT,
+      model: "claude-sonnet-4-6"
     }
   };
   return JSON.stringify(agents2);
@@ -147463,6 +147615,7 @@ async function runClaude(params) {
     }
   };
   const recentStderr = [];
+  const recentNonJsonStdout = [];
   let lastProviderError = null;
   const output = new TailBuffer(DEFAULT_MAX_RETAINED_BYTES);
   let stdoutBuffer = "";
@@ -147501,6 +147654,8 @@ async function runClaude(params) {
             event = JSON.parse(trimmed);
           } catch {
             log.debug(`\xBB non-JSON stdout line: ${trimmed.substring(0, 200)}`);
+            recentNonJsonStdout.push(trimmed);
+            if (recentNonJsonStdout.length > MAX_STDERR_LINES) recentNonJsonStdout.shift();
             continue;
           }
           eventCount++;
@@ -147531,10 +147686,10 @@ async function runClaude(params) {
         if (!trimmed) return;
         recentStderr.push(trimmed);
         if (recentStderr.length > MAX_STDERR_LINES) recentStderr.shift();
-        const providerError = detectProviderError(trimmed);
-        if (providerError) {
-          lastProviderError = providerError;
-          log.info(`\xBB provider error detected (${providerError}): ${trimmed.substring(0, 500)}`);
+        const match3 = findProviderErrorMatch(trimmed);
+        if (match3) {
+          lastProviderError = match3.label;
+          log.info(`\xBB provider error detected (${match3.label}): ${match3.excerpt}`);
         } else {
           log.debug(trimmed);
         }
@@ -147566,7 +147721,8 @@ ${stderrContext}`);
       const stdoutSnapshot = output.toString();
       const stderrSnapshot = recentStderr.join("\n");
       const truncatedStdout = stdoutSnapshot ? tailLines(stdoutSnapshot, 2048) : "";
-      const errorMessage = lastResultError || stderrSnapshot || truncatedStdout || `unknown error - no output from Claude CLI${errorContext}`;
+      const nonJsonStdoutSnapshot = recentNonJsonStdout.join("\n");
+      const errorMessage = lastResultError || stderrSnapshot || nonJsonStdoutSnapshot || truncatedStdout || `unknown error - no output from Claude CLI${errorContext}`;
       log.error(
         `${params.label} exited with code ${result.exitCode}${errorContext}: ${errorMessage}`
       );
@@ -147667,7 +147823,9 @@ var claude = agent({
   run: async (ctx) => {
     const cliPath = await installClaudeCli();
     const specifier = ctx.payload.proxyModel ?? ctx.resolvedModel;
-    const model = specifier ? stripProviderPrefix(specifier) : void 0;
+    const bedrockModelId = process.env[BEDROCK_MODEL_ID_ENV]?.trim();
+    const isBedrockRoute = specifier !== void 0 && bedrockModelId !== void 0 && bedrockModelId === specifier && isBedrockAnthropicId(specifier);
+    const model = !specifier ? void 0 : isBedrockRoute ? specifier : stripProviderPrefix(specifier);
     const homeEnv = {
       HOME: ctx.tmpdir,
       XDG_CONFIG_HOME: join10(ctx.tmpdir, ".config")
@@ -147706,6 +147864,9 @@ var claude = agent({
       ...process.env,
       ...homeEnv
     };
+    if (isBedrockRoute) {
+      env2.CLAUDE_CODE_USE_BEDROCK = "1";
+    }
     const repoDir = process.cwd();
     log.info(`\xBB effort: ${effort}`);
     log.debug(`\xBB starting Pullfrog (Claude Code): node ${baseArgs.join(" ")}`);
@@ -147746,6 +147907,68 @@ import { mkdirSync as mkdirSync5, writeFileSync as writeFileSync8 } from "node:f
 import { join as join11 } from "node:path";
 import { performance as performance7 } from "node:perf_hooks";
 
+// utils/agentHangReport.ts
+var MAX_STDERR_BYTES = 3e3;
+function formatAgentHangBody(input) {
+  if (!input.diagnostic) return null;
+  const verb = input.isHang ? "stalled" : "failed";
+  const cause = input.diagnostic.lastProviderError ? ` \u2014 likely cause: \`${input.diagnostic.lastProviderError}\`` : "";
+  const headline = `**${input.diagnostic.label} ${verb}**${cause}`;
+  const explanation = formatExplanation({
+    isHang: input.isHang,
+    errorMessage: input.errorMessage
+  });
+  const parts = [headline, "", `${explanation} ${formatEventsPart(input.diagnostic)}`];
+  const tail = renderStderrTail(input.diagnostic.recentStderr);
+  if (tail) {
+    const fence = pickFence(tail);
+    parts.push(
+      "",
+      "<details><summary>Recent agent stderr</summary>",
+      "",
+      fence,
+      tail,
+      fence,
+      "",
+      "</details>"
+    );
+  }
+  return parts.join("\n");
+}
+function formatExplanation(input) {
+  if (!input.isHang) return `The agent exited unexpectedly: ${input.errorMessage}`;
+  const idleSec = parseIdleSec(input.errorMessage);
+  if (idleSec === void 0) {
+    return "The agent stopped emitting events and was killed by the activity-timeout watchdog.";
+  }
+  return `The agent stopped emitting events for ${idleSec}s and was killed by the activity-timeout watchdog.`;
+}
+function parseIdleSec(message) {
+  const match3 = /no output for (\d+)s/.exec(message);
+  return match3 ? Number(match3[1]) : void 0;
+}
+function formatEventsPart(diagnostic) {
+  if (diagnostic.eventCount > 0) {
+    return `${diagnostic.eventCount} events were processed before the failure.`;
+  }
+  if (diagnostic.lastProviderError) return "No events were emitted before the failure.";
+  return "No events were emitted \u2014 check whether the model provider is reachable.";
+}
+function renderStderrTail(lines) {
+  if (lines.length === 0) return "";
+  const joined = lines.join("\n");
+  if (joined.length <= MAX_STDERR_BYTES) return joined;
+  return `... (older lines truncated)
+${joined.slice(-MAX_STDERR_BYTES)}`;
+}
+function pickFence(content) {
+  let max = 0;
+  for (const match3 of content.matchAll(/`+/g)) {
+    if (match3[0].length > max) max = match3[0].length;
+  }
+  return "`".repeat(Math.max(3, max + 1));
+}
+
 // agents/opencodePlugin.ts
 var PULLFROG_BUS_EVENT_TYPE = "pullfrog_bus_event";
 var PULLFROG_OPENCODE_PLUGIN_FILENAME = "pullfrog-events.ts";
@@ -147827,6 +148050,22 @@ export default async function pullfrogEventsPlugin() {
 }
 `;
 
+// agents/subagentModels.ts
+function deriveSubagentModels(orchestratorSpec) {
+  if (!orchestratorSpec) return { reviewer: void 0 };
+  for (const source of modelAliases) {
+    const matchedDirect = source.resolve === orchestratorSpec;
+    const matchedOR = source.openRouterResolve === orchestratorSpec;
+    if (!matchedDirect && !matchedOR) continue;
+    if (!source.subagentModel) return { reviewer: void 0 };
+    const target = modelAliases.find((a) => a.slug === source.subagentModel);
+    if (!target) return { reviewer: void 0 };
+    const reviewer = matchedOR ? target.openRouterResolve : target.resolve;
+    return { reviewer };
+  }
+  return { reviewer: void 0 };
+}
+
 // agents/opencode.ts
 async function installOpencodeCli() {
   return await installFromNpmTarball({
@@ -147836,7 +148075,6 @@ async function installOpencodeCli() {
     installDependencies: true
   });
 }
-var PULLFROG_OPENCODE_OUTPUT_LIMIT = 5e3;
 var GEMINI_3_DIRECT_THINKING_LEVEL = "medium";
 var GEMINI_3_DIRECT_API_IDS = ["gemini-3.1-pro-preview", "gemini-3-flash-preview"];
 function buildSecurityConfig(ctx, model) {
@@ -147852,7 +148090,12 @@ function buildSecurityConfig(ctx, model) {
     mcp: {
       [pullfrogMcpName]: { type: "remote", url: ctx.mcpServerUrl }
     },
-    agent: buildReviewerAgentConfig(),
+    agent: (() => {
+      const cfg = buildReviewerAgentConfig(model);
+      const reviewerModel = cfg[REVIEWER_AGENT_NAME]?.model ?? "(inherit)";
+      log.info(`\xBB subagent models: reviewfrog=${reviewerModel}`);
+      return cfg;
+    })(),
     // opt into opencode's experimental `batch` tool (added in
     // anomalyco/opencode PR #2983, opt-in via `experimental.batch_tool`). it
     // exposes a single `batch` tool that runs 1-25 independent tool calls
@@ -147886,12 +148129,14 @@ function buildSecurityConfig(ctx, model) {
   }
   return JSON.stringify(config3);
 }
-function buildReviewerAgentConfig() {
+function buildReviewerAgentConfig(orchestratorModel) {
+  const overrides = deriveSubagentModels(orchestratorModel);
   return {
     [REVIEWER_AGENT_NAME]: {
-      description: "Read-only review subagent for self-review and lens-based code review. Reads only \u2014 no writes, no state-changing shell or MCP calls, no nested subagent dispatch.",
+      description: "Read-only review subagent for lens-based code review (correctness, security, billing-subsystem, etc.). Reads only \u2014 no writes, no state-changing shell or MCP calls, no nested subagent dispatch.",
       mode: "subagent",
-      prompt: REVIEWER_SYSTEM_PROMPT
+      prompt: REVIEWER_SYSTEM_PROMPT,
+      ...overrides.reviewer !== void 0 ? { model: overrides.reviewer } : {}
     }
   };
 }
@@ -147916,7 +148161,7 @@ function autoSelectModel(cliPath) {
   const availableSet = new Set(availableModels);
   if (availableSet.size > 0) {
     log.debug(`\xBB opencode models (${availableSet.size}): ${availableModels.join(", ")}`);
-    const match3 = modelAliases.find((a) => a.preferred && availableSet.has(a.resolve)) ?? modelAliases.find((a) => availableSet.has(a.resolve));
+    const match3 = modelAliases.find((a) => !a.hidden && a.preferred && availableSet.has(a.resolve)) ?? modelAliases.find((a) => !a.hidden && availableSet.has(a.resolve));
     if (match3) {
       log.info(
         `\xBB model: ${match3.resolve} (auto-selected${match3.preferred ? " \u2014 preferred" : ""} curated match)`
@@ -148116,8 +148361,7 @@ async function runOpenCode(params) {
         log.debug(withLabel(label, `  output: ${event.part.state.output}`));
       }
       if (event.part?.state?.status === "error") {
-        const errorMsg = event.part.state.output ?? "(no error message)";
-        log.info(withLabel(label, `\xBB tool call failed: ${errorMsg}`));
+        log.info(withLabel(label, `\xBB tool call failed: ${event.part.state.error}`));
       }
       if (toolName.includes("report_progress") && params.todoTracker) {
         log.debug("\xBB report_progress detected, disabling todo tracking");
@@ -148129,19 +148373,20 @@ async function runOpenCode(params) {
     },
     tool_result: (event) => {
       const toolId = event.part?.callID || event.tool_id;
-      const status = event.part?.state?.status || event.status || "unknown";
-      const output2 = event.part?.state?.output || event.output;
+      const state = event.part?.state;
+      const status = state?.status ?? event.status ?? "unknown";
+      const payload = state?.status === "completed" ? state.output : state?.status === "error" ? state.error : event.output;
       const label = eventLabel(event);
       timerFor(label).markToolResult();
       if (taskDispatchByCallID.size > 0 || pendingTaskDispatches.length > 0) {
         if (toolId && taskDispatchByCallID.has(toolId)) {
           const dispatch = taskDispatchByCallID.get(toolId);
-          if (dispatch) emitSubagentFinished(dispatch, status, output2, "exact");
+          if (dispatch) emitSubagentFinished(dispatch, status, payload, "exact");
         } else {
           const callIDIsKnownNonTask = toolId ? knownNonTaskCallIDs.has(toolId) : false;
           if (!callIDIsKnownNonTask && pendingTaskDispatches.length > 0) {
             const dispatch = pendingTaskDispatches[0];
-            emitSubagentFinished(dispatch, status, output2, "fifo");
+            emitSubagentFinished(dispatch, status, payload, "fifo");
           }
         }
       }
@@ -148157,13 +148402,8 @@ async function runOpenCode(params) {
               `\xBB ${params.label} tool_result${stepContext}: id=${toolId}, status=${status}, duration=${Math.round(toolDuration)}ms`
             )
           );
-          if (output2) {
-            log.debug(
-              withLabel(
-                label,
-                `  output: ${typeof output2 === "string" ? output2 : JSON.stringify(output2)}`
-              )
-            );
+          if (payload) {
+            log.debug(withLabel(label, `  output: ${payload}`));
           }
           if (toolDuration > 5e3) {
             log.info(
@@ -148176,11 +148416,9 @@ async function runOpenCode(params) {
         }
       }
       if (status === "error") {
-        const errorMsg = typeof output2 === "string" ? output2 : JSON.stringify(output2);
-        log.info(withLabel(label, `\xBB tool call failed: ${errorMsg}`));
-      } else if (output2) {
-        const outputStr = typeof output2 === "string" ? output2 : JSON.stringify(output2);
-        log.debug(withLabel(label, `tool output: ${outputStr}`));
+        log.info(withLabel(label, `\xBB tool call failed: ${payload ?? "(no error message)"}`));
+      } else if (payload) {
+        log.debug(withLabel(label, `tool output: ${payload}`));
       }
     },
     error: (event) => {
@@ -148257,6 +148495,13 @@ async function runOpenCode(params) {
   const recentStderr = [];
   let lastProviderError = null;
   let agentErrorEvent = null;
+  const diagnostic = {
+    label: params.label,
+    recentStderr,
+    lastProviderError: void 0,
+    eventCount: 0
+  };
+  params.toolState.agentDiagnostic = diagnostic;
   const output = new TailBuffer(DEFAULT_MAX_RETAINED_BYTES);
   let stdoutBuffer = "";
   try {
@@ -148305,6 +148550,7 @@ async function runOpenCode(params) {
             continue;
           }
           eventCount++;
+          diagnostic.eventCount = eventCount;
           log.debug(JSON.stringify(event, null, 2));
           const timeSinceLastActivity = getIdleMs();
           if (timeSinceLastActivity > 1e4) {
@@ -148336,10 +148582,11 @@ async function runOpenCode(params) {
         if (!trimmed) return;
         recentStderr.push(trimmed);
         if (recentStderr.length > MAX_STDERR_LINES) recentStderr.shift();
-        const providerError = detectProviderError(trimmed);
-        if (providerError) {
-          lastProviderError = providerError;
-          log.info(`\xBB provider error detected (${providerError}): ${trimmed.substring(0, 500)}`);
+        const match3 = findProviderErrorMatch(trimmed);
+        if (match3) {
+          lastProviderError = match3.label;
+          diagnostic.lastProviderError = match3.label;
+          log.info(`\xBB provider error detected (${match3.label}): ${match3.excerpt}`);
         } else {
           log.debug(trimmed);
         }
@@ -148429,10 +148676,11 @@ ${stderrContext}`);
         `\xBB recent stderr (last ${Math.min(recentStderr.length, 10)} lines):
 ${stderrContext}`
       );
+    const body = formatAgentHangBody({ diagnostic, isHang: isActivityTimeout, errorMessage });
     return {
       success: false,
       output: finalOutput || output.toString(),
-      error: `${errorMessage} [${diagnosis}]`,
+      error: body ?? `${errorMessage} [${diagnosis}]`,
       usage: buildUsage()
     };
   }
@@ -148442,7 +148690,10 @@ var opencode = agent({
   install: installOpencodeCli,
   run: async (ctx) => {
     const cliPath = await installOpencodeCli();
-    const model = ctx.payload.proxyModel ?? ctx.resolvedModel ?? autoSelectModel(cliPath);
+    const rawModel = ctx.payload.proxyModel ?? ctx.resolvedModel ?? autoSelectModel(cliPath);
+    const bedrockModelId = process.env[BEDROCK_MODEL_ID_ENV]?.trim();
+    const isBedrockRoute = rawModel !== void 0 && bedrockModelId !== void 0 && bedrockModelId === rawModel;
+    const model = isBedrockRoute ? `amazon-bedrock/${rawModel}` : rawModel;
     const homeEnv = {
       HOME: ctx.tmpdir,
       XDG_CONFIG_HOME: join11(ctx.tmpdir, ".config")
@@ -148471,7 +148722,6 @@ var opencode = agent({
       ...homeEnv,
       OPENCODE_CONFIG_CONTENT: buildSecurityConfig(ctx, model),
       OPENCODE_PERMISSION: permissionOverride,
-      OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX: PULLFROG_OPENCODE_OUTPUT_LIMIT.toString(),
       GOOGLE_GENERATIVE_AI_API_KEY: process.env.GOOGLE_GENERATIVE_AI_API_KEY || process.env.GEMINI_API_KEY
     };
     const repoDir = process.cwd();
@@ -148482,6 +148732,7 @@ var opencode = agent({
       cliPath,
       cwd: repoDir,
       env: env2,
+      toolState: ctx.toolState,
       todoTracker: ctx.todoTracker,
       onActivityTimeout: ctx.onActivityTimeout,
       onToolUse: ctx.onToolUse
@@ -148514,13 +148765,29 @@ function hasEnvVar(name) {
 function hasClaudeCodeAuth() {
   return hasEnvVar("CLAUDE_CODE_OAUTH_TOKEN") || hasEnvVar("ANTHROPIC_API_KEY");
 }
+function hasBedrockAuth() {
+  return hasEnvVar("AWS_BEARER_TOKEN_BEDROCK") || hasEnvVar("AWS_ACCESS_KEY_ID") && hasEnvVar("AWS_SECRET_ACCESS_KEY");
+}
+function resolveSlug(slug2) {
+  const alias = resolveDisplayAlias(slug2);
+  if (alias?.routing === "bedrock") {
+    const bedrockId = process.env[BEDROCK_MODEL_ID_ENV]?.trim();
+    if (!bedrockId) {
+      throw new Error(
+        `${BEDROCK_MODEL_ID_ENV} env var is required when the model is set to "${slug2}". set it to an AWS Bedrock model ID (e.g. "us.anthropic.claude-opus-4-7", "amazon.nova-pro-v1:0"). see https://docs.pullfrog.com/bedrock for setup.`
+      );
+    }
+    return bedrockId;
+  }
+  return resolveCliModel(slug2);
+}
 function resolveModel(ctx) {
   const envModel = process.env.PULLFROG_MODEL?.trim();
   if (envModel) {
-    return resolveCliModel(envModel) ?? envModel;
+    return resolveSlug(envModel) ?? envModel;
   }
   if (ctx.slug) {
-    const resolved = resolveCliModel(ctx.slug);
+    const resolved = resolveSlug(ctx.slug);
     if (resolved) {
       return resolved;
     }
@@ -148536,6 +148803,9 @@ function resolveAgent(ctx) {
     }
     log.warning(`\xBB unknown PULLFROG_AGENT="${envAgent}" \u2014 falling through to auto-select`);
   }
+  if (ctx.model && hasBedrockAuth() && process.env[BEDROCK_MODEL_ID_ENV]?.trim() === ctx.model) {
+    return isBedrockAnthropicId(ctx.model) ? agents.claude : agents.opencode;
+  }
   if (ctx.model) {
     try {
       const provider2 = getModelProvider(ctx.model);
@@ -148550,31 +148820,56 @@ function resolveAgent(ctx) {
 
 // utils/apiKeys.ts
 var knownApiKeys = new Set(Object.values(providers).flatMap((p) => [...p.envVars]));
+var MISSING_KEY_MARKER = "no API key found";
 function buildMissingApiKeyError(params) {
-  const apiUrl = getApiUrl();
-  const settingsUrl = `${apiUrl}/console/${params.owner}/${params.name}`;
-  const githubRepoUrl = `https://github.com/${params.owner}/${params.name}`;
-  const githubSecretsUrl = `${githubRepoUrl}/settings/secrets/actions`;
-  return `no API key found. Pullfrog requires at least one LLM provider API key.
+  const githubSecretsUrl = `https://github.com/${params.owner}/${params.name}/settings/secrets/actions`;
+  const settingsUrl = `${getApiUrl()}/console/${params.owner}/${params.name}`;
+  return [
+    `**${MISSING_KEY_MARKER}** \u2014 Pullfrog needs at least one LLM provider API key (e.g. \`ANTHROPIC_API_KEY\`, \`OPENAI_API_KEY\`, \`GEMINI_API_KEY\`) configured as a GitHub Actions secret.`,
+    "",
+    `[Open repo secrets \u2192](${githubSecretsUrl}) \xB7 [Configure model \u2192](${settingsUrl}) \xB7 [Setup docs \u2192](https://docs.pullfrog.com/keys) \xB7 [Ask in Discord \u2192](https://discord.gg/8y96raFg8e)`
+  ].join("\n");
+}
+function buildBedrockSetupError(params) {
+  const githubSecretsUrl = `https://github.com/${params.owner}/${params.name}/settings/secrets/actions`;
+  return `Bedrock model selected but required configuration is missing: ${params.missing.join(", ")}.
 
-to fix this, add the required secret to your GitHub repository:
+add the missing secret(s) to your GitHub repository at ${githubSecretsUrl}, then reference them in your workflow's \`env:\` block:
 
-1. go to: ${githubSecretsUrl}
-2. click "New repository secret"
-3. set the name to your provider's key (e.g., \`ANTHROPIC_API_KEY\`, \`OPENAI_API_KEY\`, \`GEMINI_API_KEY\`)
-4. set the value to your API key
-5. click "Add secret"
+  AWS_BEARER_TOKEN_BEDROCK: \${{ secrets.AWS_BEARER_TOKEN_BEDROCK }}
+  AWS_REGION: \${{ secrets.AWS_REGION }}
+  ${BEDROCK_MODEL_ID_ENV}: \${{ secrets.${BEDROCK_MODEL_ID_ENV} }}
 
-configure your model at ${settingsUrl}
+\`AWS_BEARER_TOKEN_BEDROCK\` may be substituted with \`AWS_ACCESS_KEY_ID\` + \`AWS_SECRET_ACCESS_KEY\` (and optional \`AWS_SESSION_TOKEN\`) if you prefer access keys.
 
-for full setup instructions, see https://docs.pullfrog.com/keys`;
+for full setup instructions, see https://docs.pullfrog.com/bedrock`;
 }
 function hasEnvVar2(name) {
   const value2 = process.env[name];
   return typeof value2 === "string" && value2.length > 0;
 }
+function validateBedrockSetup(params) {
+  const hasAuth = hasEnvVar2("AWS_BEARER_TOKEN_BEDROCK") || hasEnvVar2("AWS_ACCESS_KEY_ID") && hasEnvVar2("AWS_SECRET_ACCESS_KEY");
+  const missing = [];
+  if (!hasAuth)
+    missing.push("AWS_BEARER_TOKEN_BEDROCK (or AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)");
+  if (!hasEnvVar2("AWS_REGION")) missing.push("AWS_REGION");
+  if (!hasEnvVar2(BEDROCK_MODEL_ID_ENV)) missing.push(BEDROCK_MODEL_ID_ENV);
+  if (missing.length > 0) {
+    throw new Error(buildBedrockSetupError({ owner: params.owner, name: params.name, missing }));
+  }
+}
 function validateAgentApiKey(params) {
   if (params.model) {
+    const alias = resolveDisplayAlias(params.model);
+    if (alias?.routing === "bedrock") {
+      validateBedrockSetup({ owner: params.owner, name: params.name });
+      return;
+    }
+    if (!params.model.includes("/")) {
+      validateBedrockSetup({ owner: params.owner, name: params.name });
+      return;
+    }
     const requiredVars = getModelEnvVars(params.model);
     if (requiredVars.length === 0) return;
     if (requiredVars.some((v) => hasEnvVar2(v))) return;
@@ -148585,6 +148880,22 @@ function validateAgentApiKey(params) {
     throw new Error(buildMissingApiKeyError({ owner: params.owner, name: params.name }));
   }
 }
+function isApiKeyAuthError(text) {
+  if (!text) return false;
+  return text.includes(MISSING_KEY_MARKER) || /Invalid API key/i.test(text) || /\bUser not found\b/i.test(text) || /\bInvalid authentication\b/i.test(text);
+}
+function formatApiKeyErrorSummary(params) {
+  if (params.raw.includes(MISSING_KEY_MARKER)) {
+    return buildMissingApiKeyError({ owner: params.owner, name: params.name });
+  }
+  const githubSecretsUrl = `https://github.com/${params.owner}/${params.name}/settings/secrets/actions`;
+  const settingsUrl = `${getApiUrl()}/console/${params.owner}/${params.name}`;
+  return [
+    `**Your LLM provider API key was rejected (401).** Rotate the key in your provider dashboard, then update the matching GitHub Actions secret.`,
+    "",
+    `[Update repo secret \u2192](${githubSecretsUrl}) \xB7 [Model settings \u2192](${settingsUrl}) \xB7 [Setup docs \u2192](https://docs.pullfrog.com/keys) \xB7 [Ask in Discord \u2192](https://discord.gg/8y96raFg8e)`
+  ].join("\n");
+}
 
 // utils/body.ts
 var import_turndown = __toESM(require_turndown_cjs(), 1);
@@ -153109,10 +153420,31 @@ function buildPromptContext(ctx) {
     userQuoted: user ? user.split("\n").map((line) => `> ${line}`).join("\n") : ""
   };
 }
-function assembleFullPrompt(ctx) {
-  const learningsSection = ctx.learningsFilePath ? `************* LEARNINGS *************
+function renderLearningsToc(headings) {
+  if (headings.length === 0) return "";
+  const rootDepth = Math.min(...headings.map((h) => h.depth));
+  return headings.map((h) => {
+    const indent2 = " ".repeat((h.depth - rootDepth) * 2);
+    return `${indent2}- ${h.title} (L${h.startLine}-L${h.endLine})`;
+  }).join("\n");
+}
+function buildLearningsSection(ctx) {
+  if (!ctx.filePath) return "";
+  const intro = `Repo-level learnings accumulated by previous agent runs live at \`${ctx.filePath}\`. Use this file as durable context (test commands, conventions, gotchas, architecture notes).`;
+  const tocBody = ctx.headings.length === 0 ? "(no headings yet \u2014 file is empty or a flat list. read the whole file. during the post-run reflection turn, structure it with `## ` / `### ` headings so future runs can read targeted ranges.)" : `Read targeted line ranges via your native file tool \u2014 do NOT slurp the whole file. Each range starts at the section heading line, so reading the range gives you heading + body together.
+
+${renderLearningsToc(ctx.headings)}`;
+  return `************* LEARNINGS *************
+
+${intro}
 
-Repo-level learnings accumulated by previous agent runs live at \`${ctx.learningsFilePath}\`. Read this file early and let the entries inform your approach (test commands, conventions, gotchas, etc.). The file may be empty if no learnings have been collected yet.` : "";
+${tocBody}`;
+}
+function assembleFullPrompt(ctx) {
+  const learningsSection = buildLearningsSection({
+    filePath: ctx.learningsFilePath,
+    headings: ctx.learningsHeadings
+  });
   const runtimeSection = `************* RUNTIME *************
 
 ${ctx.runtime}`;
@@ -153140,7 +153472,10 @@ function resolveInstructions(ctx) {
     tocEntries.push({ label: "EVENT CONTEXT", description: "related PR/issue data" });
   tocEntries.push({ label: "SYSTEM", description: "persona, security, tools, workflow rules" });
   if (pctx.learningsFilePath)
-    tocEntries.push({ label: "LEARNINGS", description: "repo-specific knowledge file path" });
+    tocEntries.push({
+      label: "LEARNINGS",
+      description: "repo-specific knowledge file path + heading TOC"
+    });
   tocEntries.push({ label: "RUNTIME", description: "environment metadata" });
   const toc = buildToc(tocEntries);
   const full = assembleFullPrompt({
@@ -153150,6 +153485,7 @@ function resolveInstructions(ctx) {
     eventContext,
     system,
     learningsFilePath: pctx.learningsFilePath,
+    learningsHeadings: pctx.learningsHeadings,
     runtime: pctx.runtime
   });
   const event = [pctx.eventTitle, pctx.eventMetadata].filter(Boolean).join("\n\n---\n\n");
@@ -153167,7 +153503,7 @@ function resolveInstructions(ctx) {
 import { mkdir, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
 import { dirname as dirname4, join as join14 } from "node:path";
 var LEARNINGS_FILE_NAME = "pullfrog-learnings.md";
-var MAX_LEARNINGS_LENGTH = 1e4;
+var MAX_LEARNINGS_LENGTH = 1e5;
 function learningsFilePath(tmpdir3) {
   return join14(tmpdir3, LEARNINGS_FILE_NAME);
 }
@@ -153177,6 +153513,15 @@ async function seedLearningsFile(params) {
   await writeFile2(path3, params.current ?? "", "utf8");
   return path3;
 }
+var TRUNCATION_LINE_BOUNDARY_TOLERANCE = 4096;
+function truncateAtLineBoundary(body, cap) {
+  if (body.length <= cap) return body;
+  const head = body.slice(0, cap);
+  const lastNewline = head.lastIndexOf("\n");
+  if (lastNewline <= 0) return head;
+  if (cap - lastNewline > TRUNCATION_LINE_BOUNDARY_TOLERANCE) return head;
+  return head.slice(0, lastNewline);
+}
 async function readLearningsFile(path3) {
   let raw2;
   try {
@@ -153184,9 +153529,7 @@ async function readLearningsFile(path3) {
   } catch {
     return null;
   }
-  const trimmed = raw2.trim();
-  if (trimmed.length > MAX_LEARNINGS_LENGTH) return trimmed.slice(0, MAX_LEARNINGS_LENGTH);
-  return trimmed;
+  return truncateAtLineBoundary(raw2.trim(), MAX_LEARNINGS_LENGTH);
 }
 
 // utils/normalizeEnv.ts
@@ -153533,6 +153876,7 @@ var defaultSettings = {
   prApproveEnabled: false,
   modeInstructions: {},
   learnings: null,
+  learningsHeadings: [],
   envAllowlist: null
 };
 var defaultRunContext = {
@@ -153573,7 +153917,8 @@ async function fetchRunContext(params) {
         setupScript: data.settings?.setupScript ?? null,
         postCheckoutScript: data.settings?.postCheckoutScript ?? null,
         prepushScript: data.settings?.prepushScript ?? null,
-        stopScript: data.settings?.stopScript ?? null
+        stopScript: data.settings?.stopScript ?? null,
+        learningsHeadings: data.settings?.learningsHeadings ?? []
       },
       apiToken: data.apiToken,
       oss: data.oss ?? false,
@@ -154339,10 +154684,7 @@ async function main() {
             current: runContext.repoSettings.learnings
           });
           toolState.learningsFilePath = learningsPath;
-          try {
-            toolState.learningsSeed = await readFile4(learningsPath, "utf8");
-          } catch {
-          }
+          toolState.learningsSeed = (runContext.repoSettings.learnings ?? "").trim();
           log.info(
             `\xBB learnings seeded at ${learningsPath} (existing=${runContext.repoSettings.learnings ? "yes" : "no"})`
           );
@@ -154382,7 +154724,8 @@ async function main() {
           modes: modes2,
           agentId,
           outputSchema,
-          learningsFilePath: toolState.learningsFilePath ?? null
+          learningsFilePath: toolState.learningsFilePath ?? null,
+          learningsHeadings: runContext.repoSettings.learningsHeadings
         });
         const logParts = [
           instructions.eventInstructions ? `EVENT-LEVEL INSTRUCTIONS:
@@ -154519,10 +154862,13 @@ ${instructions.user}` : null,
           await persistLearnings(toolContext);
         }
         if (!result.success && toolContext && toolState.progressComment) {
-          await reportErrorToComment({
-            toolState,
-            error: result.error || "agent run failed"
-          }).catch((error49) => {
+          const rawError = result.error || "agent run failed";
+          const errorBody = isApiKeyAuthError(rawError) ? formatApiKeyErrorSummary({
+            owner: runContext.repo.owner,
+            name: runContext.repo.name,
+            raw: rawError
+          }) : rawError;
+          await reportErrorToComment({ toolState, error: errorBody }).catch((error49) => {
             log.debug(`failure error report failed: ${error49}`);
           });
         }
@@ -154558,19 +154904,29 @@ ${instructions.user}` : null,
       killTrackedChildren();
       log.error(errorMessage);
       const billingError = isRouterKeylimitExhaustedError(errorMessage) ? new BillingError(errorMessage, { code: "router_keylimit_exhausted" }) : null;
+      const isHang = errorMessage.startsWith("activity timeout") || errorMessage.startsWith("agent still pending");
+      const hangBody = isHang ? formatAgentHangBody({ diagnostic: toolState.agentDiagnostic, isHang: true, errorMessage }) : null;
+      const apiKeySource = hangBody ?? errorMessage;
+      const apiKeyErrorSummary = !billingError && isApiKeyAuthError(apiKeySource) ? formatApiKeyErrorSummary({
+        owner: runContext.repo.owner,
+        name: runContext.repo.name,
+        raw: apiKeySource
+      }) : null;
       try {
-        const errorSummary = billingError ? formatBillingErrorSummary(billingError, runContext.repo.owner) : `### \u274C Pullfrog failed
+        const errorSummary = billingError ? formatBillingErrorSummary(billingError, runContext.repo.owner) : apiKeyErrorSummary ?? (hangBody ? `### \u274C Pullfrog failed
+
+${hangBody}` : `### \u274C Pullfrog failed
 
 \`\`\`
 ${errorMessage}
-\`\`\``;
+\`\`\``);
         const usageSummary = formatUsageSummary(toolState.usageEntries);
         const parts = [errorSummary, toolState.lastProgressBody, usageSummary].filter(Boolean);
         await writeSummary(parts.join("\n\n"));
       } catch {
       }
       try {
-        const commentBody = billingError ? formatBillingErrorSummary(billingError, runContext.repo.owner) : errorMessage;
+        const commentBody = billingError ? formatBillingErrorSummary(billingError, runContext.repo.owner) : apiKeyErrorSummary ?? hangBody ?? errorMessage;
         await reportErrorToComment({ toolState, error: commentBody });
       } catch {
       }