refactor delegation system, add PR summary comments, and improve code quality (#334)

* refactor delegation system and add PR summary comments

Delegation system:
- replace mode-based delegation with select_mode → delegate two-step flow
- orchestrator crafts self-contained subagent prompts (clean context — no system/repo/event instructions leak)
- add role-based tool filtering via FastMCP authenticate hook (?role=subagent hides orchestrator-only tools)
- add select_mode tool for orchestrator guidance per mode
- add ask_question tool for lightweight research subagents
- extract shared subagent lifecycle into subagent.ts (create, complete, stdout, instructions)
- route set_output to per-subagent state when activeSubagentId is set
- track per-subagent state (SubagentState Map) replacing boolean delegationActive flag
- capture and aggregate AgentUsage across all agents (claude, codex, gemini, opencode)
- write usage summary table to GitHub job summary
- block built-in subagent spawning (Task for Claude, Task(*) for Cursor)
- increase activity timeout from 60s to 300s (subagent thinking phases)
- fix gh CLI misguidance in system prompt — explicitly forbid usage

PR summary comments:
- add prSummaryComment trigger (DB schema + migrations + Zod + UI toggle)
- dispatch mini-effort summary job alongside PR review on pr.created
- add update_pull_request_body MCP tool
- add defaultEffort option to webhook dispatch

Hardening:
- rewrite delegate/selectMode tests with simulated state management
- add toolFiltering.test.ts for role extraction, canAccess, set_output routing
- remove non-null assertions for PULLFROG_TEMP_DIR (proper error throws)
- use fetchWithRetry for direct tarball downloads
- DRY fix for rate limit check in test runner

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: add type keyword to Effort import in handleWebhook.ts

Co-authored-by: Cursor <cursoragent@cursor.com>

* clean up delegation system, improve code quality across the codebase

- simplify delegate tool to instructions + effort params with subagent lifecycle in subagent.ts
- add select_mode and ask_question orchestrator-only tools with canAccess filtering
- replace delegate.test.ts/selectMode.test.ts with toolFiltering.test.ts (live MCP integration)
- add set_output routing for subagent context and AgentUsage tracking across all agents
- add PR summary comment trigger (schema, UI, webhook dispatch with silent flag)
- add update_pull_request_body MCP tool
- fix changed-agents.sh to always include claude canary for non-agent action changes
- fix cursor pagination bug in getSelectedInstallationReposPage
- remove destructuring patterns, inline type definitions, and unsafe type casts
- replace non-null assertions with explicit checks in install.ts
- convert multi-param functions to single param objects (postCleanup, runActionLocal, etc.)
- use isHttpError helper in API routes instead of catch-any patterns
- add adhoc test fixtures for delegation scenarios (context isolation, error handling, synthesis, etc.)

Co-authored-by: Cursor <cursoragent@cursor.com>

* no subagent mutation, one mcp per subagent

* address review feedback: parallel-safe usage tracking, subagent isolation, minor improvements

* fix subagent state isolation: replace Object.freeze with shallow copy

Object.freeze throws TypeErrors when subagent tools (checkout_pr,
report_progress) write scalar properties to toolState. A shallow copy
achieves the same isolation for scalar fields while allowing tools to
work normally. Shared references (subagents Map, usageEntries array)
remain shared for coordination.

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: pullfrog[bot] <226033991+pullfrog[bot]@users.noreply.github.com>

test/agnostic/delegate.ts

@@ -4,14 +4,14 @@ import { defineFixture, getAgentOutput, getStructuredOutput } from "../utils.ts"
 /**
  * delegate test - validates core end-to-end delegation flow.
  *
- * the orchestrator delegates to Plan mode with mini effort, passing instructions
- * that tell the subagent to call set_output with a specific value.
+ * the orchestrator selects Plan mode, then delegates with mini effort, passing
+ * instructions that tell the subagent to call set_output with a specific value.
  * validates that the subagent executed and the result flows back.
  */
 
 const fixture = defineFixture(
   {
-    prompt: `Delegate to the Plan mode with mini effort. Pass these instructions to the subagent:
+    prompt: `Select the Plan mode via select_mode, then delegate with mini effort. Your subagent instructions should be:
 "This is a delegation test. Your only task is to call set_output with the value 'DELEGATE_BASIC_PASSED'. Do not create plans, branches, or PRs. Just call set_output."`,
     effort: "mini",
     timeout: "5m",
@@ -25,8 +25,7 @@ function validator(result: AgentResult): ValidationCheck[] {
 
   const setOutputCalled = output !== null;
   const correctValue = setOutputCalled && /DELEGATE_BASIC_PASSED/i.test(output);
-  // check for the specific log line emitted by the delegate tool handler
-  const delegationOccurred = /» delegating to \w+ mode/i.test(agentOutput);
+  const delegationOccurred = /» delegating subagent=/i.test(agentOutput);
 
   return [
     { name: "set_output", passed: setOutputCalled },

test/agnostic/delegateEffort.ts

@@ -4,7 +4,7 @@ import { defineFixture, getAgentOutput, getStructuredOutput } from "../utils.ts"
 /**
  * delegateEffort test - validates effort selection for delegation.
  *
- * the orchestrator delegates to Plan mode with mini effort.
+ * the orchestrator selects Plan mode, then delegates with mini effort.
  * validates that the subagent runs at mini effort (visible in agent logs
  * as "effort=mini" or sonnet model selection for claude).
  */
@@ -14,8 +14,8 @@ import { defineFixture, getAgentOutput, getStructuredOutput } from "../utils.ts"
 // the model selection — if it were ignored, the subagent would also run at auto.
 const fixture = defineFixture(
   {
-    prompt: `This is a simple task. Delegate to the Plan mode with MINI effort (this is a trivial task).
-Pass these instructions to the subagent:
+    prompt: `This is a simple task. Select the Plan mode via select_mode, then delegate with MINI effort (this is a trivial task).
+Your subagent instructions should be:
 "Call set_output with the value 'EFFORT_TEST_PASSED'. Do not create plans or PRs. Just call set_output."`,
     effort: "auto",
     timeout: "5m",

test/agnostic/delegateMulti.ts

@@ -15,10 +15,10 @@ const fixture = defineFixture(
   {
     prompt: `This is a multi-delegation test. You must delegate exactly twice:
 
-Phase 1: Delegate to Plan mode with mini effort. Pass these instructions:
+Phase 1: Select Plan mode via select_mode, then delegate with mini effort. Your subagent instructions:
 "Your task is to call set_output with the value 'PHASE_1_MARKER'. Do not create plans or PRs."
 
-Phase 2: After Phase 1 completes, delegate to Plan mode again with mini effort. Pass these instructions (include the result from Phase 1 as context):
+Phase 2: After Phase 1 completes, select Plan mode again and delegate with mini effort. Include the result from Phase 1. Your subagent instructions:
 "Your task is to call set_output with the value 'MULTI_DELEGATE_PASSED'. Do not create plans or PRs."
 
 Both delegations must complete successfully.`,
@@ -36,8 +36,7 @@ function validator(result: AgentResult): ValidationCheck[] {
   // the last set_output call wins — should be from Phase 2
   const finalValue = setOutputCalled && /MULTI_DELEGATE_PASSED/i.test(output);
 
-  // count delegation evidence — match the exact log line format from the delegate handler
-  const delegationMatches = agentOutput.match(/» delegating to/g);
+  const delegationMatches = agentOutput.match(/» delegating subagent=/g);
   const twoDelegations = delegationMatches !== null && delegationMatches.length >= 2;
 
   return [

test/agnostic/timeout.ts

@@ -9,8 +9,7 @@ import { defineFixture } from "../utils.ts";
 
 const fixture = defineFixture(
   {
-    prompt: `Call the delegate tool with mode "Build" and effort "mini", then analyze the result.
-Then call delegate with mode "Review" and effort "mini".
+    prompt: `Select the Build mode via select_mode, then delegate with mini effort. After that completes, select Review mode and delegate again with mini effort.
 Finally call set_output with "TIMEOUT TEST COMPLETED".`,
     timeout: "5s",
     effort: "mini",