# Choosing an orchestration pattern

Course: Claude Code: Pro Level — https://zero2vibecode.com/learn/claude-code-pro
Canonical URL: https://zero2vibecode.com/learn/claude-code-pro/4-2-choosing-a-pattern
Verified against: Claude Code v2.1.292 (2026-10-15)
Last updated: 2026-10-15

Subagents, workflows and agent teams split work between workers. The difference is who holds the plan. Every pattern more complex than one conversation adds cost, so pick the cheapest one the task actually needs.

You already know how to delegate to subagents. But Claude Code has two more ways to split work between workers — workflows and agent teams. How do you choose?

## Who holds the plan

All three patterns hand parts of the work to workers. The difference is **who holds the plan**:

| Pattern | Who holds the plan | How results come back |
|---|---|---|
| Main conversation | you and Claude, in one context | right in the conversation |
| Subagents | Claude, deciding turn by turn | each result returns to your conversation |
| Workflow | a script Claude wrote | the script keeps intermediate results; only the final one reaches the conversation |
| Agent team | a lead; teammates message each other directly | through the lead and the messages between teammates |

Agent teams are an experimental feature, off by default. They get the last lesson of this level.

## Three questions, in order

Every pattern more complex than one conversation adds cost: each subagent and each workflow agent sends its own requests, and a team uses noticeably more tokens than a single session. So ask the questions in order and stop at the first answer:

1. **Can one conversation handle it without filling the context?** Yes — the main conversation.
2. **Do the workers need to talk to each other?** Yes — an agent team.
3. **Do you need many agents, cross-checking of findings, or reruns?** Yes — a workflow. No — subagents.

## Example: subagents

The task: give a newcomer a short description of the `src`, `test` and `docs` folders. One conversation would clog up with files it will never need again. The descriptions do not need to talk to each other. Three tasks, once. So, subagents:

```text
Explore the src, test and docs folders in parallel, with separate subagents, and give me two sentences about each.
```

In an interactive session, subagents run **in the background** by default, and the input stays free. While they work:

- `/tasks` — the list of subagents with their state and model; `Enter` on a row opens that subagent's transcript;
- `/usage` — afterwards: on Pro, Max, Team and Enterprise plans, the breakdown shows how much went to skills, subagents, plugins and MCP servers. It is an estimate, not a bill.

## A delegation log

To see who Claude actually started, attach a `SubagentStart` hook. It fires when each subagent starts and receives JSON with the fields `agent_id` and `agent_type`:

```json
{
  "hooks": {
    "SubagentStart": [
      { "hooks": [ { "type": "command", "command": "jq -r '[.agent_id, .agent_type] | @tsv' >> \"$CLAUDE_PROJECT_DIR/.claude/agents.log\"" } ] }
    ]
  }
}
```

Save it in a separate file and start a session with it: `claude --settings .claude/agent-log.json`. The file's keys are layered over your settings for that session only.

**Careful.** 
Permission requests from a background subagent appear in your main session. An answer that lasts longer than one call, such as "for the rest of the session", applies to the whole session, including your main conversation. Approve such requests for one call only, and ask reviewers to only read. And ask subagents for short results: every detailed report comes back into your context.

**Practice in the terminal.** Create .claude/agent-log.json with a SubagentStart hook that writes agent_id and agent_type to .claude/agents.log, and run claude --settings .claude/agent-log.json. In a real project, after you ask for parallel subagents, the log gets one line per subagent.