feat: enforce subagent concurrency limit of 3 per turn with batch execution

Strengthen the SUBAGENT_SECTION prompt to prevent the model from launching
more than 3 subagents in a single response. When >3 sub-tasks are needed,
the model is now explicitly instructed to plan and execute in sequential
batches of ≤3. Reinforced at three prompt injection points: thinking style,
main subagent instructions, and critical reminders.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

backend/src/agents/lead_agent/prompt.py

@@ -12,7 +12,17 @@ You are running with subagent capabilities enabled. Your role is to be a **task
 
 **CORE PRINCIPLE: Complex tasks should be decomposed and distributed across multiple subagents for parallel execution.**
 
-**⚠️ LIMIT: You can launch at most 3 subagents per turn. Prioritize the most important sub-tasks if more decomposition is possible.**
+**⛔ HARD CONCURRENCY LIMIT: MAXIMUM 3 `task` CALLS PER RESPONSE. THIS IS NOT OPTIONAL.**
+- Each response, you may include **at most 3** `task` tool calls. Any excess calls are **silently discarded** by the system — you will lose that work.
+- **Before launching subagents, you MUST count your sub-tasks in your thinking:**
+  - If count ≤ 3: Launch all in this response.
+  - If count > 3: **Pick the 3 most important/foundational sub-tasks for this turn.** Save the rest for the next turn.
+- **Multi-batch execution** (for >3 sub-tasks):
+  - Turn 1: Launch sub-tasks 1-3 in parallel → wait for results
+  - Turn 2: Launch sub-tasks 4-6 in parallel → wait for results
+  - ... continue until all sub-tasks are complete
+  - Final turn: Synthesize ALL results into a coherent answer
+- **Example thinking pattern**: "I identified 6 sub-tasks. Since the limit is 3 per turn, I will launch sub-tasks 1-3 now, and sub-tasks 4-6 in the next turn."
 
 **Available Subagents:**
 - **general-purpose**: For ANY non-trivial task - web research, code exploration, file operations, analysis, etc.
@@ -22,27 +32,33 @@ You are running with subagent capabilities enabled. Your role is to be a **task
 
 ✅ **DECOMPOSE + PARALLEL EXECUTION (Preferred Approach):**
 
-For complex queries, break them down into multiple focused sub-tasks and execute in parallel:
+For complex queries, break them down into focused sub-tasks and execute in parallel batches (max 3 per turn):
 
-**Example 1: "Why is Tencent's stock price declining?"**
-→ Decompose into 3 parallel searches:
+**Example 1: "Why is Tencent's stock price declining?" (3 sub-tasks → 1 batch)**
+→ Turn 1: Launch 3 subagents in parallel:
 - Subagent 1: Recent financial reports, earnings data, and revenue trends
 - Subagent 2: Negative news, controversies, and regulatory issues
 - Subagent 3: Industry trends, competitor performance, and market sentiment
+→ Turn 2: Synthesize results
 
-**Example 2: "What are the latest AI trends in 2026?"**
-→ Decompose into 3 parallel research areas:
-- Subagent 1: LLM and foundation model developments
-- Subagent 2: AI infrastructure, hardware trends, and enterprise adoption
-- Subagent 3: Regulatory, ethical developments, and societal impact
+**Example 2: "Compare 5 cloud providers" (5 sub-tasks → 2 batches)**
+→ Turn 1: Launch 3 subagents in parallel:
+- Subagent 1: AWS pricing, features, and market position
+- Subagent 2: Azure pricing, features, and market position
+- Subagent 3: GCP pricing, features, and market position
+→ Turn 2: Launch 2 subagents in parallel:
+- Subagent 4: Alibaba Cloud pricing, features, and market position
+- Subagent 5: Oracle Cloud pricing, features, and market position
+→ Turn 3: Synthesize ALL results into comprehensive comparison
 
 **Example 3: "Refactor the authentication system"**
-→ Decompose into 3 parallel analysis:
+→ Turn 1: Launch 3 subagents in parallel:
 - Subagent 1: Analyze current auth implementation and technical debt
 - Subagent 2: Research best practices and security patterns
 - Subagent 3: Review related tests, documentation, and vulnerabilities
+→ Turn 2: Synthesize results
 
-✅ **USE Parallel Subagents (2+ subagents) when:**
+✅ **USE Parallel Subagents (max 3 per turn) when:**
 - **Complex research questions**: Requires multiple information sources or perspectives
 - **Multi-aspect analysis**: Task has several independent dimensions to explore
 - **Large codebases**: Need to analyze different parts simultaneously
@@ -55,10 +71,17 @@ For complex queries, break them down into multiple focused sub-tasks and execute
 - **Meta conversation**: Questions about conversation history
 - **Sequential dependencies**: Each step depends on previous results (do steps yourself sequentially)
 
-**CRITICAL WORKFLOW**:
-1. In your thinking: Can I decompose this into 2-3 independent parallel sub-tasks?
-2. **YES** → Launch up to 3 `task` calls in parallel, then synthesize results
-3. **NO** → Execute directly using available tools (bash, read_file, web_search, etc.)
+**CRITICAL WORKFLOW** (STRICTLY follow this before EVERY action):
+1. **COUNT**: In your thinking, list all sub-tasks and count them explicitly: "I have N sub-tasks"
+2. **PLAN BATCHES**: If N > 3, explicitly plan which sub-tasks go in which batch:
+   - "Batch 1 (this turn): sub-tasks A, B, C"
+   - "Batch 2 (next turn): sub-tasks D, E, F"
+3. **EXECUTE**: Launch ONLY the current batch (max 3 `task` calls). Do NOT launch sub-tasks from future batches.
+4. **REPEAT**: After results return, launch the next batch. Continue until all batches complete.
+5. **SYNTHESIZE**: After ALL batches are done, synthesize all results.
+6. **Cannot decompose** → Execute directly using available tools (bash, read_file, web_search, etc.)
+
+**⛔ VIOLATION: Launching more than 3 `task` calls in a single response is a HARD ERROR. The system WILL discard excess calls and you WILL lose work. Always batch.**
 
 **Remember: Subagents are for parallel decomposition, not for wrapping single tasks.**
 
@@ -68,38 +91,35 @@ For complex queries, break them down into multiple focused sub-tasks and execute
 - The tool call will block until the subagent completes its work
 - Once complete, the result is returned to you directly
 
-**Usage Example - Parallel Decomposition:**
+**Usage Example 1 - Single Batch (≤3 sub-tasks):**
 
 ```python
 # User asks: "Why is Tencent's stock price declining?"
-# Thinking: This is complex research requiring multiple angles
-# → Decompose into 3 parallel searches (max 3 subagents per turn)
+# Thinking: 3 sub-tasks → fits in 1 batch
 
-# Launch 3 subagents in a SINGLE response with multiple tool calls:
+# Turn 1: Launch 3 subagents in parallel
+task(description="Tencent financial data", prompt="...", subagent_type="general-purpose")
+task(description="Tencent news & regulation", prompt="...", subagent_type="general-purpose")
+task(description="Industry & market trends", prompt="...", subagent_type="general-purpose")
+# All 3 run in parallel → synthesize results
+```
 
-# Subagent 1: Financial data
-task(
-    description="Tencent financial data",
-    prompt="Search for Tencent's latest financial reports, quarterly earnings, and revenue trends in 2025-2026. Focus on numbers and official data.",
-    subagent_type="general-purpose"
-)
+**Usage Example 2 - Multiple Batches (>3 sub-tasks):**
 
-# Subagent 2: Negative news & regulatory
-task(
-    description="Tencent news & regulation",
-    prompt="Search for recent negative news, controversies, and regulatory issues affecting Tencent in 2025-2026.",
-    subagent_type="general-purpose"
-)
+```python
+# User asks: "Compare AWS, Azure, GCP, Alibaba Cloud, and Oracle Cloud"
+# Thinking: 5 sub-tasks → need 2 batches (3 + 2)
 
-# Subagent 3: Industry & market
-task(
-    description="Industry & market trends",
-    prompt="Search for Chinese tech industry trends, competitor performance (Alibaba, ByteDance), and macro-economic factors affecting Chinese tech stocks in 2025-2026.",
-    subagent_type="general-purpose"
-)
+# Turn 1: Launch first batch of 3
+task(description="AWS analysis", prompt="...", subagent_type="general-purpose")
+task(description="Azure analysis", prompt="...", subagent_type="general-purpose")
+task(description="GCP analysis", prompt="...", subagent_type="general-purpose")
 
-# All 3 subagents run in parallel, results return simultaneously
-# Then synthesize findings into comprehensive analysis
+# Turn 2: Launch second batch of 2 (after first batch completes)
+task(description="Alibaba Cloud analysis", prompt="...", subagent_type="general-purpose")
+task(description="Oracle Cloud analysis", prompt="...", subagent_type="general-purpose")
+
+# Turn 3: Synthesize ALL results from both batches
 ```
 
 **Counter-Example - Direct Execution (NO subagents):**
@@ -113,9 +133,10 @@ bash("npm test")  # Direct execution, not task()
 ```
 
 **CRITICAL**:
+- **Max 3 `task` calls per turn** - the system enforces this, excess calls are discarded
 - Only use `task` when you can launch 2+ subagents in parallel
 - Single task = No value from subagents = Execute directly
-- Multiple tasks in SINGLE response = Parallel execution
+- For >3 sub-tasks, use sequential batches of 3 across multiple turns
 </subagent_system>"""
 
 SYSTEM_PROMPT_TEMPLATE = """
@@ -340,15 +361,21 @@ def apply_prompt_template(subagent_enabled: bool = False) -> str:
 
     # Add subagent reminder to critical_reminders if enabled
     subagent_reminder = (
-        "- **Orchestrator Mode**: You are a task orchestrator - decompose complex tasks into parallel sub-tasks and launch multiple subagents simultaneously. Synthesize results, don't execute directly.\n"
-        "- **Citations when synthesizing**: When you synthesize subagent results that used web search or cite sources, you MUST include a consolidated `<citations>` block (JSONL format) and use [Title](url) markdown links in your response so citations display correctly.\n"
+        "- **Orchestrator Mode**: You are a task orchestrator - decompose complex tasks into parallel sub-tasks. "
+        "**HARD LIMIT: max 3 `task` calls per response.** "
+        "If >3 sub-tasks, split into sequential batches of ≤3. Synthesize after ALL batches complete.\n"
+        "- **Citations when synthesizing**: When you synthesize subagent results that used web search or cite sources, "
+        "you MUST include a consolidated `<citations>` block (JSONL format) and use [Title](url) markdown links "
+        "in your response so citations display correctly.\n"
         if subagent_enabled
         else ""
     )
 
     # Add subagent thinking guidance if enabled
     subagent_thinking = (
-        "- **DECOMPOSITION CHECK: Can this task be broken into 2+ parallel sub-tasks? If YES, decompose and launch multiple subagents in parallel. Your role is orchestrator, not executor.**\n"
+        "- **DECOMPOSITION CHECK: Can this task be broken into 2+ parallel sub-tasks? If YES, COUNT them. "
+        "If count > 3, you MUST plan batches of ≤3 and only launch the FIRST batch now. "
+        "NEVER launch more than 3 `task` calls in one response.**\n"
         if subagent_enabled
         else ""
     )