Advanced10 min
Subagent Invocation Patterns
Claude Code provides four distinct ways to invoke subagents — from automatic selection to explicit CLI flags. Knowing which pattern to use determines whether your agents fire reliably or silently miss.
Quick Reference
- →Natural language: Claude picks the agent if the task matches the description
- →@agent-name: explicit typeahead invocation — bypasses Claude's judgment entirely
- →--agent agentName: CLI flag for scripted or programmatic session startup
- →Agent tool call: invoke via the Agent tool inside multi-agent workflows
- →Foreground blocks until done; background runs in parallel and returns a summary
- →Subagents do NOT inherit parent conversation history — only CLAUDE.md and MCPs
- →Results always return as a summary — design agents to produce structured output
- →@ typeahead was added in April 2026 — upgrade Claude Code if you do not see it
The Four Invocation Patterns
There is no single right way to invoke a subagent — each pattern exists because a different situation calls for different levels of control. Natural language is the most ergonomic. @-mention is the most reliable. The CLI flag is for automation. The Agent tool is for programmatic composition.
| Pattern | Syntax | When to Use |
|---|---|---|
| Natural language | "review this PR for security issues" | When Claude should decide whether a subagent is appropriate |
| @-mention | @security-reviewer | When you want a specific agent and do not want Claude guessing |
| CLI flag | claude --agent code-reviewer | When scripting or launching sessions programmatically |
| Agent tool | Agent({ subagent_type: "code-reviewer" }) | Inside multi-agent orchestration workflows |