> ## Content Index > Fetch the complete content index at: https://wuu73.org/aiguide-ghost/llms.txt > Use this file to discover other available public pages before exploring further. # Subagents & Delegation: How Agents Split Work - URL: https://wuu73.org/aiguide-ghost/coding-agents-subagents/ - Published: 2026-05-29T00:14:00.000Z - Updated: 2026-05-29T00:14:00.000Z - Description: Part of Agent Harness Field Guide. - Author: WUU73 - Tags: Deep Dives, Agent Harness Field Guide, #Deep Dive Child, #Import 2026-09-12 06:38 Delegation • Parallel Execution • Isolation • Concurrency The most powerful agents don't just reason — they delegate. This page compares how agents spawn sub-agents, isolate their capabilities, enforce concurrency limits, and collect results. Shameless Plug[While we're deep-diving into complex CLI tools... let's be honest. Are you tired of feeling like nerds are trying to gatekeep the terminal life by having you memorize 30 key combos just to do basic stuff? Do you lie awake at night dreading the moment you have to edit a cryptic dotfile just to change a font size? Same. It's the AI age, we can have a crazy UI on top of the terminal with shameless amounts of AI built in to do things for you. We can even have AI nudge stalled coding agents for you when they stop for no reason.**ButtonsCLI**: The terminal for](https://buttonscli.com/?ref=wuu73.org) (Alright, ad over. Back to the serious technical analysis.) ## The delegation spectrum Not all agents support sub-agent delegation. Among those that do, the approaches range from simple task spawning to sophisticated coordinator patterns with parallel worker execution. | Agent | Subagent Support | Max Parallel | Isolation | Tool Control | Result Collection | | --------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------- | -------------------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------- | | **Claude Code** | AgentTool + TeamCreateTool/TeamDeleteTool | Configurable (agent swarms) | Git worktrees, isolated sessions | Inherits parent permissions | Streaming results, parent sees summary | | **Hermes** | delegate\_tool (ThreadPoolExecutor) | 3 concurrent | Fresh conversation, no parent history | 5 tools stripped from children | Summary result only | | **DeerFlow** | task\_tool (subagent registry) | 3 concurrent (configurable) | Isolated thread, own sandbox | Tool allowlists/denylists per subagent type | Real-time streaming + summary | | **Neovate** | task tool (4 built-in agents) | Configurable | Isolated session, filtered tools | Per-agent tool allowlists with wildcards | Result returned to parent | | **Qwen Code** | task tool (agent types) | Configurable | Isolated session | Per-agent tool filtering | Result returned to parent | | **Mux** | 9 built-in agents (Markdown + YAML frontmatter) | Per-workspace | Workspace isolation | Regex tool allow/deny per agent | agent\_report protocol enforcement | | **Codex** | spawn\_agent / wait\_agent / send\_message / close\_agent (dual API: multi\_agents + multi\_agents\_v2) | Configurable per agent | Isolated child sessions | Fine-grained SpawnAgentToolOptions (v2) | Streaming + summary via wait\_agent | | **OpenCode** | Built-in build/plan modes plus @general and ACP-backed forked sessions | Runtime-managed | Forked sessions, optional worktrees, read-only plan mode | Permission inheritance plus wildcard allow/deny/ask rules | Session summaries, usage events, and permission-aware delegation | | **Oh My Pi** | task tool + swarm extension | Configurable (up to 100 jobs) | Git worktrees, fuse-overlay, Windows ProjFS | Custom agent defs, per-agent model overrides | Streaming previews, agent:// artifacts, poll | | **Pi Mono** | Not built-in | N/A | N/A | N/A (extensions could implement) | N/A | | **Dirac** | SubagentToolHandler (SubagentRunner, SubagentBuilder) | Configurable | Isolated child sessions | Tool scopes per subagent config | Streaming results to parent | ## Hermes — The most restrictive child isolation Hermes has the most explicit security model for child agents. Five tools are **always stripped** from child agents: | Stripped Tool | Reason | | -------------- | ---------------------------------------------------------------------------------------- | | delegate\_task | No recursive delegation (max depth ≤ 2) | | clarify | No user interaction from subagents — children shouldn't ask questions | | memory | No writes to shared MEMORY.md — children shouldn't modify persistent memory | | send\_message | No cross-platform side effects — children shouldn't send messages to Slack/Telegram/etc. | | execute\_code | Children should reason step-by-step, not execute — the parent executes, children think | Each child gets: - A fresh conversation with **no parent history** - Its own `task_id` for tracking - A focused system prompt built from the delegated goal - A restricted toolset (stripped as above) Up to 3 children run concurrently via `ThreadPoolExecutor`. The parent sees only the delegation call and the child's summary result — **never the intermediate tool calls**. This is a clean information-hiding boundary. ## DeerFlow — Middleware-enforced limits with real-time streaming DeerFlow's sub-agent system is enforced by the `SubagentLimitMiddleware` (position 11 in the 14-layer middleware stack): ### Concurrency limits Default `max_concurrent=3`, configurable per-thread. The middleware tracks active sub-agents and rejects new spawns when the limit is reached. ### Timeout and turn limits Default `timeout_seconds=900` (15 minutes). Each sub-agent also has a configurable `max_turns` limit. Whichever fires first terminates the child. ### Cooperative cancellation Cancellation uses `threading.Event` checked at `astream()` iteration boundaries. Deferred cleanup uses `asyncio.create_task()` to avoid race conditions. ### Real-time streaming Unlike Hermes (summary-only), DeerFlow streams sub-agent messages in real-time via the `StreamBridge` abstraction. The user sees sub-agent progress live in the SSE feed. Sub-agent tool control is via `SubagentConfig` with tool allowlists/denylists, model inheritance, and timeout overrides. Different sub-agent types (general-purpose, bash) can have different tool permissions. ## Claude Code — Agent swarms and coordinator mode Claude Code has the most sophisticated multi-agent architecture in this set, gated by feature flags: | Feature | Gate | Description | | -------------------- | ---------------------------------------- | --------------------------------------------------------------------- | | **AgentTool** | Always available | Spawn sub-agent for isolated work | | **TeamCreateTool** | AGENT\_SWARMS / coordinator\_mode | Team-level parallel work — spawn multiple agents | | **Coordinator Mode** | COORDINATOR\_MODE | Research → Implementation → Verification phases with parallel workers | | **Background tasks** | CLAUDE\_CODE\_DISABLE\_BACKGROUND\_TASKS | Auto-background long-running agents | The coordinator system prompt includes detailed instructions for phased execution: 1. **Research phase:** Parallel workers gather information 2. **Implementation phase:** Workers implement changes 3. **Verification phase:** Workers verify correctness Sub-agents inherit parent permissions via the `swarmWorkerHandler` in the permission system. This is different from Hermes (which strips tools) — Claude trusts children more but isolates them in git worktrees. ## Codex — Dual API with explicit lifecycle management Codex takes a unique approach: sub-agents are managed through a dedicated API surface rather than a single "task" tool. Two parallel versions ship side by side in `codex-core/src/tools/handlers/`: | Tool | v1 (multi\_agents) | v2 (multi\_agents\_v2) | | ------------------ | ---------------------------------------- | -------------------------------------------------------------------------- | | **spawn\_agent** | Create isolated child agent | Same, plus SpawnAgentToolOptions for fine-grained control over tool access | | **wait\_agent** | Block until child completes or times out | Same, plus WaitAgentTimeoutOptions for configurable timeout behavior | | **send\_input** | Send messages to a running agent | Replaced by send\_message (v2) | | **close\_agent** | Terminate a child agent | Same | | **resume\_agent** | — | Resume a paused child agent | | **list\_agents** | Enumerate active child agents | Same | | **followup\_task** | — | v2-exclusive: assign follow-up work to an existing child | The v2 API adds three notable capabilities not present in v1: - **SpawnAgentToolOptions** — parents can specify exactly which tools each child gets, rather than inheriting the full parent toolset - **WaitAgentTimeoutOptions** — configurable timeout behavior per wait call - **followup\_task** — assign additional work to a child without respawning it ### Batch CSV-driven workflows Codex supports `spawn_agents_on_csv_tool` and `create_report_agent_job_result_tool` for batch multi-agent workflows driven by CSV input. Each row can spawn an independent agent job, with results collected into structured reports. ### Collaboration mode The `collaboration-mode-templates` crate provides pre-built templates for multi-user scenarios, enabling multiple humans to interact with the same Codex session or coordinate across agents. ### Explicit lifecycle Unlike task-style tools that handle spawn-and-collect in one call, Codex exposes the full lifecycle: spawn, send input, wait, resume, close. This gives parents fine-grained control over child timing and interaction patterns. This API-first approach is unusual among coding agents. Where Hermes, DeerFlow, and Claude Code treat sub-agents as an internal abstraction (a single tool call that handles everything), Codex exposes the machinery explicitly — more like an orchestrator framework than a convenience wrapper. ## OpenCode — runtime-backed delegation via ACP OpenCode sits between the task-tool style of Qwen or Neovate and the API-heavy lifecycle of Codex. The README exposes **build**, **plan**, and an internal **@general** helper, while the ACP layer handles session initialization, prompt submission, permission requests, usage updates, and forking. ### Read-only planning mode The dedicated plan prompt is explicit: read, search, ask questions, and build a plan, but do not edit. That gives OpenCode a genuine planning persona rather than a vague "be more careful" flag. ### Delegation as runtime state OpenCode's ACP implementation treats delegation as part of the session runtime. Permissions, prompts, usage, and session forks are all first-class protocol events. ### Permissions carry through Because delegation runs through the same permission service, child work inherits the same allow/deny/ask model instead of bypassing the approval surface. ## Neovate — 4 built-in agents with per-agent model config Neovate ships with 4 built-in sub-agents, each with a dedicated purpose: | Agent | Purpose | Model Override | | ---------------------- | ------------------------------------- | -------------------------------- | | **Explore** | Codebase exploration and analysis | Can use smaller/cheaper model | | **Plan** | Planning and decomposition | Can use stronger reasoning model | | **GeneralPurpose** | General task execution | Inherits parent model | | **neovate-code-guide** | Answer questions about Neovate itself | Inherits parent model | Per-agent model configuration via `config.agent.{type}.model` means you can route Explore to a cheap model and Plan to a strong reasoning model, all within the same session. Tool filtering uses allowlists/denylists with wildcard support: `allow: ["read", "ls", "glob"]` or `deny: ["bash", "write"]`. ## Oh My Pi — built-in tasking with real isolation backends Oh My Pi is the clearest example here of a fork changing its stance on delegation. Pi Mono explicitly omitted sub-agents. Oh My Pi's README now treats task execution as a first-class capability, complete with a task tool, bundled agents, background jobs, and an agent control center. The swarm extension shows the concrete mechanism: child agents are run as real OMP subprocesses in the swarm workspace. The README goes further by advertising isolation backends such as git worktrees, Unix fuse-overlay filesystems, and Windows ProjFS, plus `agent://` resources for full outputs when previews are truncated. ### Bundled agents The task tool ships an actual starter roster instead of requiring extensions to invent delegation from scratch. ### Real isolation Worktrees, fuse-overlay, and ProjFS make the delegation story much more concrete than simple child-session spawning. ### Result visibility Streaming previews plus poll and `agent://` artifact access keep long-running child work inspectable. ## ADK-Rust — workflow agents instead of productized subagents ADK-Rust approaches delegation as a framework concern, not a branded product feature. The core crates expose `SequentialAgent`, `ParallelAgent`, and `LoopAgent`, while `adk-graph` adds `GraphAgent` checkpoints, routing, durable resume, and human-in-the-loop interrupts. That means ADK-Rust is less like Codex's explicit child-process API or OpenCode's ACP-backed collaboration modes, and more like a reusable orchestration toolkit. You assemble the delegation model you want. ### Deterministic building blocks Sequential, parallel, and loop agents are part of the ordinary core surface, not bolted on as a premium feature. ### SharedState coordination Parallel branches can share structured state through context instead of relying on hidden globals or ad hoc side channels. ### Graph-level interrupts Graph workflows add checkpoints and HITL pauses, which is a richer control surface than a simple fire-and-forget subagent call. ## Mux — 9 agents defined as Markdown files Mux defines its 9 built-in agents as Markdown files with YAML frontmatter in `src/node/builtinAgents/`. Each agent is a text file with a system prompt, tool list, and configuration. Tool lists use **regex allow/deny patterns**: - `- .*` — adds every available tool - `- file_edit_.*` — removes all file-edit tools - `- mux_agents_.*` — blocks config tools from sub-agents The `exec.md` agent has a hard protocol rule: *"Before your stream ends, you MUST call `agent_report` exactly once."* The `orchestrator.md` agent has an explicit prohibition: *"Do NOT create pull requests, push to remote branches, or run any `gh pr` / `git push` commands."* This Markdown-as-configuration approach is unusual and elegant: agents are just text files with frontmatter. No code changes needed to add or modify agents. ## Delegation patterns compared | Pattern | Agent | Description | | ---------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Coordinator/Workers** | Claude Code | Coordinator phases: research → implement → verify. Parallel workers per phase. | | **Thread Pool** | Hermes | Up to 3 children via ThreadPoolExecutor. Strict tool stripping. Summary-only results. | | **Middleware-Enforced** | DeerFlow | SubagentLimitMiddleware enforces limits. Real-time streaming via StreamBridge. | | **Specialized Agents** | Neovate | 4 built-in agents with per-agent model config and tool filtering. | | **Markdown-Defined** | Mux | 9 agents as Markdown + YAML frontmatter. Regex tool allow/deny. | | **Task Tool** | Qwen Code | Generic task tool with agent types and per-agent tool filtering. | | **Protocol-Backed Sessions** | OpenCode | Build, plan, and @general all sit on top of the same ACP-aware session runtime. | | **Extension-Based (Not Built-in)** | Pi Mono | No native sub-agent support. README suggests: spawn separate pi instances via tmux, build your own with extensions, or install a Pi Package. | | **Dual API (v1 + v2)** | Codex | multi\_agents and multi\_agents\_v2 with spawn/wait/send/close/resume/list. v2 adds SpawnAgentToolOptions, WaitAgentTimeoutOptions, followup\_task, and batch CSV-driven multi-agent jobs. | ## What children can't do — compared The most important security question is: what capabilities do you *remove* from children compared to the parent? ### Hermes — Most restrictive - ❌ No delegation (no recursive spawning) - ❌ No user interaction - ❌ No memory writes - ❌ No cross-platform messages - ❌ No code execution (reason only) ### Mux — Protocol-enforced - ❌ No PR creation or pushing - ❌ No agent\_report from sub-agents (only exec) - ❌ Regex-gated tool access - ✅ Can execute code ### DeerFlow — Config-driven - ❌ Tool allowlists/denylists per type - ❌ Timeout and turn limits - ❌ Concurrency cap (default 3) - ✅ Can execute code in sandbox ### Claude Code — Permission-inherited - ❌ Git worktree isolation - ❌ Inherits parent permissions (not stripped) - ❌ Coordinator-gated phases - ✅ Full tool access, just isolated filesystem ### Codex — API-controlled - ❌ Isolated child sessions - ❌ Explicit lifecycle: spawn, wait, send, close, resume - ❌ v2 adds fine-grained options (SpawnAgentToolOptions, WaitAgentTimeoutOptions) - ✅ Parent controls child via API contract ## Bottom line Sub-agent delegation is where agents transition from reasoning engines to **orchestration systems**. The agents that do it well share common traits: - **Explicit isolation** — fresh conversations, no inherited history - **Tool control** — allowlists, denylists, or stripping - **Concurrency limits** — caps on parallel children - **Timeout safety** — hard limits on execution time - **Clean result collection** — parent sees summaries, not intermediate noise Hermes is the most security-conscious, stripping 5 tools from children and enforcing strict isolation. Claude Code is the most sophisticated, with coordinator-mode phased execution. DeerFlow is the most middleware-enforced, with real-time streaming. Mux is the most elegant, defining agents as Markdown files with regex tool patterns. **OpenCode** is the most runtime-shaped middle ground: built-in build and plan personas, a general helper, and ACP-backed forked sessions rather than a one-shot task wrapper. **Codex** is the most API-explicit, exposing the full sub-agent lifecycle (spawn, wait, send, close, resume, list) with dual v1/v2 APIs and batch CSV-driven job orchestration. **Pi Mono** explicitly omits sub-agents, following its minimalist philosophy — the README offers three alternatives: tmux-based multi-instance, custom extension implementation, or installing a Pi Package.