diff --git a/tools/delegate_tool.py b/tools/delegate_tool.py index ff1306f0d05..3fe0026efed 100644 --- a/tools/delegate_tool.py +++ b/tools/delegate_tool.py @@ -2367,7 +2367,14 @@ DELEGATE_TASK_SCHEMA = { "WHEN NOT TO USE (use these instead):\n" "- Mechanical multi-step work with no reasoning needed -> use execute_code\n" "- Single tool call -> just call the tool directly\n" - "- Tasks needing user interaction -> subagents cannot use clarify\n\n" + "- Tasks needing user interaction -> subagents cannot use clarify\n" + "- Durable long-running work that must outlive the current turn -> " + "use cronjob (action='create') or terminal(background=True, " + "notify_on_complete=True) instead. delegate_task runs SYNCHRONOUSLY " + "inside the parent turn: if the parent is interrupted (user sends a " + "new message, /stop, /new) the child is cancelled with status=" + "'interrupted' and its work is discarded. Children cannot continue " + "in the background.\n\n" "IMPORTANT:\n" "- Subagents have NO memory of your conversation. Pass all relevant " "info (file paths, error messages, constraints) via the 'context' field.\n" diff --git a/website/docs/guides/delegation-patterns.md b/website/docs/guides/delegation-patterns.md index b5d54faa40f..0564690bc33 100644 --- a/website/docs/guides/delegation-patterns.md +++ b/website/docs/guides/delegation-patterns.md @@ -25,6 +25,7 @@ For the full feature reference, see [Subagent Delegation](/docs/user-guide/featu - Mechanical multi-step work with logic between steps → `execute_code` - Tasks needing user interaction → subagents can't use `clarify` - Quick file edits → do them directly +- Durable long-running work that must outlive the current turn → `cronjob` or `terminal(background=True, notify_on_complete=True)`. `delegate_task` is **synchronous**: if the parent turn is interrupted, active children are cancelled and their work is discarded. --- @@ -237,6 +238,7 @@ delegation: - **Separate terminals** — each subagent gets its own terminal session with separate working directory and state - **No conversation history** — subagents see only the `goal` and `context` the parent agent passes when calling `delegate_task` - **Default 50 iterations** — set `max_iterations` lower for simple tasks to save cost +- **Not durable** — `delegate_task` is synchronous and runs inside the parent turn. If the parent is interrupted (new user message, `/stop`, `/new`), all active children are cancelled (`status="interrupted"`) and their work is discarded. For work that must outlive the current turn, use `cronjob` or `terminal(background=True, notify_on_complete=True)`. --- diff --git a/website/docs/user-guide/features/delegation.md b/website/docs/user-guide/features/delegation.md index 1ab8f8cbd54..f3c832bff0f 100644 --- a/website/docs/user-guide/features/delegation.md +++ b/website/docs/user-guide/features/delegation.md @@ -193,6 +193,21 @@ delegate_task( **Cost warning:** With `max_spawn_depth: 3` and `max_concurrent_children: 3`, the tree can reach 3×3×3 = 27 concurrent leaf agents. Each extra level multiplies spend — raise `max_spawn_depth` intentionally. +## Lifetime and Durability + +:::warning delegate_task is synchronous — not durable +`delegate_task` runs **inside the parent's current turn**. It blocks the parent until every child finishes (or is cancelled). It is **not** a background job queue: + +- If the parent is interrupted (user sends a new message, `/stop`, `/new`), all active children are cancelled and return `status="interrupted"`. Their in-progress work is discarded. +- Children do **not** continue running after the parent turn ends. +- Cancelled children return a structured result (`status="interrupted"`, `exit_reason="interrupted"`), but because the parent was interrupted too, that result often never makes it into a user-visible reply. + +For **durable long-running work** that must survive interrupts or outlive the current turn, use: + +- `cronjob` (action=`create`) — schedules a separate agent run; immune to parent-turn interrupts. +- `terminal(background=True, notify_on_complete=True)` — long-running shell commands that keep running while the agent does other things. +::: + ## Key Properties - Each subagent gets its **own terminal session** (separate from the parent)