fix(agents): prevent orchestrator from rushing ahead of background agents

src/agents/dynamic-agent-prompt-builder.ts

@@ -116,7 +116,7 @@ export function buildExploreSection(agents: AvailableAgent[]): string {
 
   return `### Explore Agent = Contextual Grep
 
-Use it as a **peer tool**, not a fallback. Fire liberally.
+Use it as a **peer tool**, not a fallback. Fire liberally for discovery, not for files you already know.
 
 **Use Direct Tools when:**
 ${avoidWhen.map((w) => `- ${w}`).join("\n")}

src/agents/sisyphus.ts

@@ -225,18 +225,17 @@ task(subagent_type="explore", run_in_background=true, load_skills=[], descriptio
 // Reference Grep (external)
 task(subagent_type="librarian", run_in_background=true, load_skills=[], description="Find JWT security docs", prompt="I'm implementing JWT auth and need current security best practices to choose token storage (httpOnly cookies vs localStorage) and set expiration policy. Find: OWASP auth guidelines, recommended token lifetimes, refresh token rotation strategies, common JWT vulnerabilities. Skip 'what is JWT' tutorials — production security guidance only.")
 task(subagent_type="librarian", run_in_background=true, load_skills=[], description="Find Express auth patterns", prompt="I'm building Express auth middleware and need production-quality patterns to structure my middleware chain. Find how established Express apps (1000+ stars) handle: middleware ordering, token refresh, role-based access control, auth error propagation. Skip basic tutorials — I need battle-tested patterns with proper error handling.")
-// Continue working immediately. System notifies on completion — collect with background_output then.
-
 // WRONG: Sequential or blocking
 result = task(..., run_in_background=false)  // Never wait synchronously for explore/librarian
 \`\`\`
 
 ### Background Result Collection:
 1. Launch parallel agents \u2192 receive task_ids
-2. Continue immediate work
-3. System sends \`<system-reminder>\` on each task completion — then call \`background_output(task_id="...")\`
-4. Need results not yet ready? **End your response.** The notification will trigger your next turn.
-5. Cleanup: Cancel disposable tasks individually via \`background_cancel(taskId="...")\`
+2. If you have DIFFERENT independent work \u2192 do it now
+3. Otherwise \u2192 **END YOUR RESPONSE.**
+4. System sends \`<system-reminder>\` on completion \u2192 triggers your next turn
+5. Collect via \`background_output(task_id="...")\`
+6. Cleanup: Cancel disposable tasks individually via \`background_cancel(taskId="...")\`
 
 ### Search Stop Conditions
 

src/agents/sisyphus/default.ts

@@ -327,10 +327,11 @@ result = task(..., run_in_background=false)  // Never wait synchronously for exp
 
 ### Background Result Collection:
 1. Launch parallel agents → receive task_ids
-2. Continue immediate work
-3. System sends \`<system-reminder>\` on each task completion — then call \`background_output(task_id="...")\`
-4. Need results not yet ready? **End your response.** The notification will trigger your next turn.
-5. Cleanup: Cancel disposable tasks individually via \`background_cancel(taskId="...")\`
+2. If you have DIFFERENT independent work → do it now
+3. Otherwise → **END YOUR RESPONSE.**
+4. System sends \`<system-reminder>\` on completion → triggers your next turn
+5. Collect via \`background_output(task_id="...")\`
+6. Cleanup: Cancel disposable tasks individually via \`background_cancel(taskId="...")\`
 
 ### Search Stop Conditions
 

src/agents/sisyphus/gpt-5-4.ts

@@ -246,10 +246,11 @@ Each agent prompt should include:
 
 Background result collection:
 1. Launch parallel agents → receive task_ids
-2. Continue immediate work
-3. System sends \`<system-reminder>\` on completion → call \`background_output(task_id="...")\`
-4. If results aren't ready: end your response. The notification triggers your next turn.
-5. Cancel disposable tasks individually via \`background_cancel(taskId="...")\`
+2. If you have DIFFERENT independent work → do it now
+3. Otherwise → **END YOUR RESPONSE.**
+4. System sends \`<system-reminder>\` on completion → triggers your next turn
+5. Collect via \`background_output(task_id="...")\`
+6. Cancel disposable tasks individually via \`background_cancel(taskId="...")\`
 
 Stop searching when: you have enough context, same info repeating, 2 iterations with no new data, or direct answer found.
 </explore>`;