In Claude Code, how do automatic delegation, an @-mention and `claude --agent` differ in deciding which subagent does the work?
answer
- who chooses: Claude or you
- the description is the routing signal
- typeahead pick guarantees one task
- whole session becomes the agent
- flag beats the agent setting
basics
~20 sAutomatic delegation lets Claude pick a subagent by matching your request to its description; an @-mention guarantees that subagent runs for one task; claude --agent <name> makes the whole session run as that agent, with its prompt, tools and model.
solid answer
~40 sWith **automatic delegation**, Claude reads each subagent's `description` and decides; naming one in plain language ("use the bug-hunter subagent") only nudges that decision. An **@-mention**, picked from the `@` typeahead or typed as `@agent-<name>`, guarantees that subagent runs for this task, but your whole message still goes to Claude, which writes the subagent's task prompt. `claude --agent <name>` is not delegation at all: the **main thread** takes on that agent's tool restrictions and model, and a custom agent's prompt replaces the default Claude Code system prompt, while CLAUDE.md still loads. Setting `agent` in `.claude/settings.json` makes it the project default; the CLI flag overrides the setting, and the choice persists when you resume.
go deeper
Recall the three ways: let Claude choose by description, @-mention to force one agent for a task, and --agent to run the whole session as that agent.
Explain that an @-mention picks the agent but Claude still writes its prompt, and that --agent replaces the system prompt while CLAUDE.md keeps loading.
Diagnose delegation that never fires or picks the wrong agent: description wording, the 15,000-token description warning, and when a forced mention or a session-wide agent is the cleaner fix.
Decide what a team standardises: shared descriptions that route reliably, a project agent setting for constrained roles, and when a session-wide agent is safer than trusting delegation.
## Three levels of control Claude Code gives you three ways to put a particular subagent to work, and they escalate from a hint to a session-wide default. The question each answers is **who chooses** the agent and **for how long**. | Way | Who chooses | Scope | What the agent receives | | --- | --- | --- | --- | | Automatic or natural language | Claude | One task, if Claude delegates | A task prompt Claude writes | | @-mention | You | One task, guaranteed | A task prompt Claude writes from your message | | `claude --agent <name>` or the `agent` setting | You | The whole session | Your prompts directly, as the main thread | ## Automatic delegation Claude decides on its own when a request matches a subagent, using three signals: the task in your request, the **`description`** of each available subagent, and the current context. A description that says when the agent applies, such as "use proactively when hunting the cause of a failing test", makes delegation more likely. Writing the description well is part of authoring the definition file; for delegation the point is that it is the routing signal. Descriptions cost context in the main window, because Claude has to see them to choose. When the combined descriptions of your non-built-in subagents pass **15,000 tokens**, Claude Code shows a startup warning and still loads every subagent. Naming a subagent in plain language ("have the bug-hunter subagent look at the timeout") needs no syntax and usually works, but **Claude still decides** whether to delegate. ## @-mention: guaranteed for one task Type `@` and pick the subagent from the typeahead, the same way you mention a file. The inserted mention looks like `@"bug-hunter (agent)"`. You can also type `@agent-bug-hunter`, or a scoped name such as `@agent-my-plugin:code-reviewer` for a plugin's agent; while you type that form the typeahead shows files, but the mention still resolves on submit. Two details trip people up: - The mention controls **which** subagent runs, not **what it is told**. Your full message still goes to Claude, which writes the delegation prompt. - Named background subagents already running in the session also appear in the typeahead, with their status. ## `--agent`: the session becomes the agent `claude --agent bug-hunter` starts a session in which the **main thread itself** takes on that agent's tool restrictions and model. For a custom agent with a non-empty prompt, its system prompt **replaces** the default Claude Code system prompt, the way `--system-prompt` does. CLAUDE.md files and project memory still load through the normal message flow. The startup header shows `@bug-hunter` so you can confirm it is active. Further behaviour worth knowing: 1. It works for built-in and custom agents, and for plugin agents by bare name, or by scoped name such as `my-plugin:security-reviewer` when two plugins clash. 2. The choice **persists on resume**: Claude Code restores the agent's tool restrictions and model. If the agent file has since been removed, the session continues with default tools and shows a warning naming the missing agent. 3. Setting `"agent": "bug-hunter"` in `.claude/settings.json` makes it the default for every session in the project, and the **CLI flag overrides the setting** when both are present. 4. An agent running as the main thread can itself delegate with the `Agent` tool, and its `tools` list can narrow which types it may spawn with `Agent(worker, researcher)` syntax, which applies only in this main-thread case. ## Choosing between them - Let automatic delegation handle routine side work such as a broad search, and write descriptions that make the right choice obvious. - Reach for an @-mention when delegation is not happening, or when the wrong agent keeps being picked for a task you care about. - Use `--agent` when the whole session should behave as that role, for example a read-only triage session in which the main thread itself must not have edit tools. - When delegation seems to ignore you, open the subagent's transcript from `/tasks` to see which agent actually ran and the task prompt Claude wrote for it, before rewriting any description. A common mistake is to use `--agent` expecting a one-off delegation: the main conversation itself becomes the agent, and its tool restrictions apply to everything you do in that session.
- You @-mention a subagent and add detailed instructions. Does the subagent receive your text word for word?No. The @-mention fixes which subagent Claude invokes; your full message still goes to Claude, which writes the subagent's task prompt from it. Anything critical, such as a directory to skip or the report format, should be stated plainly so Claude carries it into the delegation, and you can open the subagent's transcript to check what it was actually asked.
- A session started with `claude --agent triage` is resumed a week later after the triage file was deleted. What happens?Resuming normally restores the agent's tool restrictions and model with the conversation. If the agent no longer exists, the session continues with the default tools and Claude Code shows a warning naming the missing agent, so check the header before relying on the old restrictions.
- Claude only delegates when you name a subagent explicitly
- An @-mention sends your message verbatim as the subagent's prompt
- --agent delegates one task and then returns to normal Claude
- The agent setting in settings.json overrides the --agent flag
- Under --agent, CLAUDE.md stops loading because the prompt is replaced