D3 · Claude Code › Cluster 7 · Subagents

7.4 · Invoking Subagents

Automatic vs explicit

CONCEPT Automatic delegation, driven by the description

Most of the time you don't invoke a subagent at all — Claude delegates automatically. It decides based on the task description in your request, the description field in the subagent's configuration, and the current context. When a task matches a subagent's description, Claude hands it off. This is why a clear, detailed description matters so much: it's the signal Claude uses to route work.

To encourage proactive delegation, put phrases like "use proactively" in the subagent's description field — e.g. "Expert code reviewer. Use proactively after code changes."

CONCEPT Explicit invocation, when automatic isn't enough

When you want to control which subagent runs, three patterns escalate from a hint to a session-wide default:

PatternHowGuarantee
Natural languageName the subagent in your prompt: "Use the test-runner subagent to fix failing tests."Claude still decides whether to delegate
@-mentionType @ and pick it from the typeahead (or @agent-<name>)Guarantees that specific subagent runs for the task
Session-wideclaude --agent <name>, or set "agent" in .claude/settings.jsonThe whole session runs as that subagent (its prompt, tools, model)

With an @-mention, your full message still goes to Claude, which writes the subagent's task prompt from what you asked — the mention controls which subagent is invoked, not the exact prompt it receives. With --agent, the subagent's system prompt replaces the default Claude Code system prompt for the whole session.

🔑 Automatic = Claude matches the description. Explicit escalates: natural language (a suggestion) → @-mention (guaranteed for one task) → --agent (the whole session).

DIAGRAM How a subagent gets picked

flowchart TD REQ["Your request"] --> EXPL{"Did you name /
@-mention a subagent?"} EXPL -->|"@-mention"| GUAR["🟢 That subagent runs
(guaranteed)"] EXPL -->|"natural language name"| SUG["Claude usually delegates
to the named one"] EXPL -->|"no"| AUTO{"Task matches a
subagent description?"} AUTO -->|"yes"| DEL["🟢 Auto-delegate"] AUTO -->|"no"| SELF["Handled in main conversation"] SESS["claude --agent NAME /
agent setting"] -.->|"whole session"| GUAR classDef ok fill:#d4edda,stroke:#28a745,color:#155724; class GUAR ok; class DEL ok;

CODE The three explicit patterns

Same subagent, three levels of control.

# 1. Natural language — Claude decides whether to delegate
Use the code-reviewer subagent to look at my recent changes

# 2. @-mention — guarantees THIS subagent runs for the task
@"code-reviewer (agent)" look at the auth changes

# 3. Session-wide — the whole session runs as this subagent
$ claude --agent code-reviewer
// or make it the default for every session in a project:
// .claude/settings.json
{
  "agent": "code-reviewer"
}
⚠️ The --agent CLI flag overrides the agent setting if both are present.

TRADE-OFFS Let Claude choose vs. force a subagent

✅ Automatic delegation

  • Zero friction — no special syntax to remember
  • Claude routes based on the best-matching description
  • "use proactively" nudges it toward eager delegation

⚠️ Explicit invocation

  • Deterministic: @-mention guarantees the exact agent
  • --agent reshapes the whole session — powerful but broad
  • More to type / configure; you own the routing decision

EXAM TRAPS

Trap: "You must always invoke a subagent explicitly." → No. Claude automatically delegates when the task matches a subagent's description. Explicit invocation is for when automatic isn't enough.
Trap: "The system prompt / body decides when Claude delegates." → It's the description field that drives automatic delegation. The body is the agent's system prompt, used once it's running.
Trap: "Naming the subagent in plain text guarantees it runs." → Natural-language naming is a strong hint but Claude still decides. Use an @-mention to guarantee a specific subagent for the task.
Trap: "--agent just adds a subagent you can call." → It runs the entire session as that agent, replacing the default system prompt with the agent's and applying its tools and model.

PRACTICE

Q1 · What does Claude use to decide whether to auto-delegate to a subagent?

The task in your request, the subagent's description field, and the current context. A clear description is what makes automatic delegation work — add "use proactively" to encourage it.

Q2 · You want to guarantee a specific subagent handles one task. How?

@-mention it (pick from the typeahead, or type @agent-<name>). That forces that subagent to run rather than leaving the choice to Claude.

Q3 · What's the difference between naming a subagent in text and claude --agent name?

Naming it in text is a per-task suggestion Claude may act on. --agent runs the whole session as that subagent — its system prompt replaces the default one, and its tool restrictions and model apply for the session.