This page documents the delegate_task tool, which spawns child AIAgent instances with isolated context, restricted toolsets, and dedicated terminal sessions. The system supports both single-task and parallel batch delegation modes, with configurable progress reporting for CLI and messaging gateway environments.
The delegate_task tool allows an agent to spawn one or more child agents to work on tasks in completely isolated contexts. This is useful for:
Each child agent receives:
task_id which creates an isolated terminal session and file operations cache [tools/delegate_tool.py:12-12].delegate_task itself are always blocked to prevent recursive delegation) [tools/delegate_tool.py:13-13], [tools/delegate_tool.py:46-55].goal and context [tools/delegate_tool.py:14-14], [tools/delegate_tool.py:646-679].The parent's context only sees the delegation call and the final summary—never the child's intermediate reasoning or tool results [tools/delegate_tool.py:17-18].
Sources: [tools/delegate_tool.py:1-18]
The delegate_task tool is registered in the delegation toolset. Its schema is dynamically generated to reflect user-configured limits for concurrency and depth [tests/tools/test_delegate.py:91-104].
goal (+ optional context) [tools/delegate_tool.py:1012-1019].tasks array for parallel execution [tools/delegate_tool.py:1020-1025].worker (leaf node) or an orchestrator (can delegate further if depth permits) [tools/delegate_tool.py:1034-1037].Title: "Delegation Tool Architecture"
Blocked Tools Rationale:
| Tool | Reason for Blocking |
|---|---|
delegate_task | Prevents recursive delegation beyond MAX_DEPTH (default 1) unless orchestrator role is granted [tools/delegate_tool.py:48-48], [tools/delegate_tool.py:126-126]. |
clarify | Subagents cannot interact with the user; would deadlock parent TUI [tools/delegate_tool.py:49-49], [tools/delegate_tool.py:61-65]. |
memory | Prevents concurrent writes to shared MEMORY.md [tools/delegate_tool.py:50-50]. |
send_message | Prevents uncontrolled side effects on messaging platforms [tools/delegate_tool.py:51-51]. |
cronjob | Prevents subagents from scheduling more work in the parent's name [tools/delegate_tool.py:53-53]. |
Sources: [tools/delegate_tool.py:46-55], [tools/delegate_tool.py:1000-1110], [tests/tools/test_delegate.py:20-25], [tests/tools/test_delegate.py:173-178]
Each child agent is spawned with complete isolation from the parent's runtime state.
Title: "Subagent Isolation and Data Flow"
Isolation Mechanisms:
skip_context_files=True and skip_memory=True ensures children start with a clean slate [tools/delegate_tool.py:843-845].task_id, creating a separate terminal session and file operations cache [tools/delegate_tool.py:837-837]._strip_blocked_tools() removes the blocked tools from any inherited toolsets [tools/delegate_tool.py:718-724].Sources: [tools/delegate_tool.py:718-845], [tools/delegate_tool.py:646-679], [tests/tools/test_delegate.py:159-174]
The parent blocks until all children complete. This is the default mode for both single tasks and parallel batches [tools/delegate_tool.py:901-996].
ThreadPoolExecutor [tools/delegate_tool.py:28-31]._get_max_concurrent_children() [tools/delegate_tool.py:104-105]. Defaults to 3 [tools/delegate_tool.py:118-118].When background=true is passed to delegate_task, the subagent is dispatched to a background executor [tools/delegate_tool.py:864-889].
process_registry.completion_queue [tools/async_delegation.py:9-10]. The CLI or gateway then forges a fresh user turn from this event [tools/async_delegation.py:12-13].state.db in the async_delegations table before delivery to ensure they survive a process restart [tools/async_delegation.py:112-132], [website/docs/user-guide/features/delegation.md:128-132].Sources: [tools/delegate_tool.py:864-889], [tools/delegate_tool.py:901-996], [tools/async_delegation.py:9-132], [website/docs/user-guide/features/delegation.md:11-11], [website/docs/user-guide/features/delegation.md:128-142]
Progress reporting relays child events to the parent's display (CLI or Gateway).
When the parent agent has a _delegate_spinner (CLI context), child tool calls are printed above the spinner using KawaiiSpinner.print_above() [tools/delegate_tool.py:736-737]. Reasoning previews are shown via _thinking events [tools/delegate_tool.py:750-769].
When the parent agent has a tool_progress_callback (gateway context), tool names are batched and relayed to avoid platform flooding [tools/delegate_tool.py:747-748].
Sources: [tools/delegate_tool.py:726-788]
delegation.max_iterations). The default is 50 [website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/delegation.md:160-160].MAX_DEPTH (default 1). Grandchildren are rejected unless max_spawn_depth is raised in configuration [tools/delegate_tool.py:126-131].Subagents run in background threads where interactive input() would deadlock the parent TUI [tools/delegate_tool.py:61-65].
_subagent_auto_deny returns "deny" for dangerous commands [tools/delegate_tool.py:74-86].delegation.subagent_auto_approve: true [tools/delegate_tool.py:88-99].set_spawn_paused(true) [tools/delegate_tool.py:152-161]._active_subagents registry [tools/delegate_tool.py:147-150]. If the parent is interrupted, it triggers an immediate shutdown of all active children [tools/delegate_tool.py:932-937].Sources: [tools/delegate_tool.py:58-114], [tools/delegate_tool.py:126-165], [tools/delegate_tool.py:932-937], [website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/delegation.md:160-160]
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.