Dynamic Multi-Agent Orchestration#

Dynamic multi-agent orchestration in Claude Code refers to the ability of a parent Claude instance to spawn, coordinate, and (to varying degrees) monitor sub-agents ("teammates") at runtime. The feature spans two overlapping tracks: the experimental Agent Teams feature (platform-level multi-agent collaboration), and the broader plugin-based orchestration patterns that compose multiple agents using hooks and shared state.

The two tracks differ in capability: Agent Teams uses native spawning with lifecycle hooks but sub-agents are still black boxes during execution; plugin-based patterns work around this via file-based state and shell hooks but require no feature flag.

Current State: Agent Teams (Research Preview)#

Agent Teams shipped in v2.1.32 as a research preview behind a feature flag:

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Enabling this flag unlocks multi-agent collaboration where a parent agent can spawn typed sub-agents (teammates) that run concurrently 1. The feature is explicitly token-intensive.

Agent Definition Format#

Each agent is a Markdown file with YAML frontmatter. The full format is documented in plugins/plugin-dev/skills/agent-development/SKILL.md:

• name — lowercase, hyphens only identifier 2
• description — triggering conditions + <example> blocks that determine when Claude dispatches this agent 3
• model — inherit (default), sonnet, opus, or haiku 4
• tools — optional array to restrict the agent to a subset of tools; omit for full access 5
• memory — persistent memory scope: user, project, or local 6
• isolation: worktree — run the agent in an isolated git worktree 7

Spawning is controlled via Task(agent_type) syntax in the parent agent's tools frontmatter, restricting which child agent types it can dispatch 6.

Lifecycle Hooks#

v2.1.33 added two hook events for reacting to teammate lifecycle 8:

Both hooks support {"continue": false, "stopReason": "..."} to halt a teammate, matching the behavior of the Stop hook 8.

Observability#

Parent-child relationships are tracked via:

• OTEL spans: agent_id and parent_agent_id attributes on claude_code.tool spans; background subagent spans nest under the dispatching Agent tool span 9
• HTTP headers: x-claude-code-agent-id / x-claude-code-parent-agent-id on all sub-agent API requests 10
• CLAUDE_CODE_SUBAGENT_MODEL controls the model for teammate processes 11

Known issues fixed: a memory leak where completed teammate tasks accumulated in session state 12, and teammates with non-ASCII names failing API calls due to invalid header encoding — fixed in v2.1.145 13.

Plugin-Based Orchestration Patterns#

Before (and alongside) Agent Teams, community and plugin authors coordinate agents using shared state files and hooks — no feature flag required.

Settings File Pattern#

Each agent in a swarm reads a .claude/<plugin>.local.md file that stores coordination state (task assignment, coordinator session ID, PR number, dependencies). A real-world reference implementation (multi-agent-swarm) stores this in .claude/multi-agent-swarm.local.md:

agent_name: auth-implementation
task_number: 3.5
coordinator_session: team-leader
enabled: true
dependencies: ["Task 3.4"]

Stop Hook Notification#

Agents signal completion to the coordinator via a Stop hook shell script that parses the settings file and sends a tmux message to the coordinator session 14. This lets the coordinator re-dispatch work or halt agents based on results.

swarm-dev Plugin (PR #32094)#

The swarm-dev plugin is a community-contributed plugin that packages this pattern as a five-agent pipeline: pain-researcher, architecture-researcher, task-breakdown-researcher, builder, and verifier. The verifier returns a strict PASS/FAIL; after two consecutive FAIL results, the loop pauses and asks the user whether to continue 15. Note: this plugin was proposed via PR and may not be merged into the main repo.

Community Feature Request: Real-Time Parent-Child Communication#

The core gap articulated in issue #1770 is that the parent currently has no visibility into sub-agent activity until completion — sub-agents are black boxes. The requested capability includes:

• Streaming tool-call events from sub-agents to the parent
• Bidirectional messaging: parent sends redirect/pause/halt instructions mid-execution
• Bulk control: pause/redirect/halt all agents simultaneously

Specific failure modes cited include sub-agents silently switching strategies (e.g., creating fake simulation scripts instead of executing real searches) and the parent being unable to intervene 16.

The existing parent_tool_use_id infrastructure in -p (non-interactive) mode demonstrates that the parent-child tracking plumbing already exists; the request is to expose that event stream programmatically to the parent Claude instance 16.

As of v2.1.145, observability is telemetry-only (OTEL + headers). Native two-way runtime communication between a parent and its spawned sub-agents — streaming events, bidirectional messaging, runtime halt — remains an open feature request 16 9.

Key Source Files#