@@ -146,6 +146,22 @@ Otherwise, follow debugging best practices:
2. When selecting which version of an API or package to use, choose one that is compatible with the user's dependency management file(s). If no such file exists or if the package is not present, use the latest version that is in your training data.
3. If an external API requires an API Key, be sure to point this out to the user. Adhere to best security practices (e.g. DO NOT hardcode an API key in a place where it can be exposed)
+{{#if (contains available_tools 'spawn_agent') }}
+## Multi-agent delegation
+Sub-agents can help you move faster on large tasks when you use them thoughtfully. This is most useful for:
+* Very large tasks with multiple well-defined scopes
+* Plans with multiple independent steps that can be executed in parallel
+* Independent information-gathering tasks that can be done in parallel
+* Requesting a review from another agent on your work or another agent's work
+* Getting a fresh perspective on a difficult design or debugging question
+* Running tests or config commands that can output a large amount of logs when you want a concise summary. Because you only receive the subagent's final message, ask it to include the relevant failing lines or diagnostics in its response.
+
+When you delegate work, focus on coordinating and synthesizing results instead of duplicating the same work yourself. If multiple agents might edit files, assign them disjoint write scopes.
+
+This feature must be used wisely. For simple or straightforward tasks, prefer doing the work directly instead of spawning a new agent.
+
+{{/if}}
+
## System Information
Operating System: {{os}}
@@ -10,21 +10,30 @@ use std::sync::Arc;
use crate::{AgentTool, ThreadEnvironment, ToolCallEventStream, ToolInput};
-/// Spawns an agent to perform a delegated task.
+/// Spawn a sub-agent for a well-scoped task.
///
-/// Use this tool when you want to:
-/// - Run multiple tasks in parallel.
-/// - Delegate a self-contained task where you only need the final outcome.
+/// ### Designing delegated subtasks
+/// - An agent does not see your conversation history. Include all relevant context (file paths, requirements, constraints) in the message.
+/// - Subtasks must be concrete, well-defined, and self-contained.
+/// - Delegated subtasks must materially advance the main task.
+/// - Do not duplicate work between your work and delegated subtasks.
+/// - Do not use this tool for tasks you could accomplish directly with one or two tool calls.
+/// - When you delegate work, focus on coordinating and synthesizing results instead of duplicating the same work yourself.
+/// - Avoid issuing multiple delegate calls for the same unresolved subproblem unless the new delegated task is genuinely different and necessary.
+/// - Narrow the delegated ask to the concrete output you need next.
+/// - For code-edit subtasks, decompose work so each delegated task has a disjoint write set.
+/// - When sending a follow-up using an existing agent session_id, the agent already has the context from the previous turn. Send only a short, direct message. Do NOT repeat the original task or context.
///
-/// Do NOT use this tool for tasks you could accomplish directly with one or two tool calls (e.g. reading a file, running a single command).
+/// ### Parallel delegation patterns
+/// - Run multiple independent information-seeking subtasks in parallel when you have distinct questions that can be answered independently.
+/// - Split implementation into disjoint codebase slices and spawn multiple agents for them in parallel when the write scopes do not overlap.
+/// - When a plan has multiple independent steps, prefer delegating those steps in parallel rather than serializing them unnecessarily.
+/// - Reuse the returned session_id when you want to follow up on the same delegated subproblem instead of creating a duplicate session.
///
-/// You will receive only the agent's final message as output.
-///
-/// **New session** (no session_id): Creates a new agent that does NOT see your conversation history. Include all relevant context (file paths, requirements, constraints) in the message.
-///
-/// **Follow-up** (with session_id): Sends a follow-up to an existing agent session. The agent already has full context, so send only a short, direct message — do NOT repeat the original task or context. Examples: "Also update the tests", "Fix the compile error in foo.rs", "Retry".
-///
-/// - If spawning multiple agents that might write to the filesystem, provide guidance on how to avoid conflicts (e.g. assign each to different directories).
+/// ### Output
+/// - You will receive only the agent's final message as output.
+/// - Successful calls return a session_id that you can use for follow-up messages.
+/// - Error results may also include a session_id if a session was already created.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub struct SpawnAgentToolInput {