Claude Code Subagents: When to Use Them and How to Limit Them

Claude Code Subagents: When to Use Them and How to Limit Them

Claude Code subagents are specialized assistants that the main agent calls for well-defined tasks. Each one has its own context, its own instructions and a defined set of tools. They help when a task can be separated, when it produces a lot of intermediate material that would clutter the main conversation, or when it needs different permissions. The safest way to limit them is to list, for each subagent, only the tools its role actually needs.

Key takeaways

• A subagent works in a separate context and hands only the result back to the main agent, which keeps the main conversation free for decisions.
• Splitting pays off for independent tasks, read-heavy tasks and tasks with different permission profiles. Small, sequential tasks usually work better in a single conversation.
• Tool restriction is the most important control: the reviewer reads and does not write, the researcher looks things up and does not run commands.
• Each subagent's description decides when it gets called, so it must be specific and tested on real cases.
• Start with one or two subagents on a real workflow, with a record of what they did and a success criterion agreed in advance.

What a subagent is and what it changes in practice

In this article we separate three kinds of statements: what comes from the official documentation, what is an implementation practice recommendation, and what is a hypothesis to validate. On the mechanics, the Claude Code documentation describes subagents as text files with a configuration header (name, description, allowed tools and, optionally, model) followed by instructions in plain language. They can live in the project folder, versioned alongside the code, or in the user folder. Check the documentation for the version you run, because field names and commands change over time.

In practice, three things change when you use a subagent instead of asking for everything in one conversation.

• Separate context: the subagent reads files, tests hypotheses and discards what does not help. The main conversation receives only the summary.
• Specialized instructions: a security reviewer can follow its own checklist, different from the one used by whoever implements.
• Its own permissions: each subagent can have a different tool list from the main agent.

The first point connects to what Anthropic describes in its engineering writing on context engineering for agents: subagent architectures exist so that a worker can explore extensively and return a short summary, instead of filling the main agent's context window. The pattern of a coordinator handing work to others also appears in Anthropic's piece on building effective agents, with the caveat that the extra complexity is only justified when the result improves in an observable way.

When splitting a task helps, and when it hurts

Splitting has a cost: more instructions to maintain, more points of failure, and a handoff between agents that can lose detail. So the useful question is not whether a task can be split, but whether the split brings something concrete. A simple decision guide:

• Split if the task requires reading a lot of material and only the summary matters, such as mapping where a business rule appears in a large repository.
• Split if parts of the work are independent and do not depend on each other's results.
• Split if one step needs smaller permissions than the others, such as a review that must not edit files.
• Split if you want a second reading free of the bias of the conversation that produced the change.
• Do not split if the task is short and each step depends on the previous one.
• Do not split if you cannot yet describe, in one sentence, what the subagent should return.
• Do not split just to look sophisticated. A workflow with fewer parts is easier to audit.

A practical sign that the split is wrong: the main agent spends more time explaining the context to the subagent than the subagent spends working. In that case, the task probably belongs in the main conversation.

Another point is consumption. Because each subagent has its own context, the total amount of work processed can grow. That is not necessarily bad, but it should be measured in the pilot, not assumed.

How to restrict each subagent's tools

The principle comes from classic security: least privilege and deny by default, as the OWASP authorization guidance describes. Applied to subagents, it means the tool list is written by inclusion. You state what the subagent may use, not what it may not.

According to the documentation, when the tools field is omitted the subagent inherits the tools of the main conversation. For a pilot, that is the opposite of what you want. Verify this behavior in the version you use and, as a rule, always fill in the list explicitly.

Some profiles that often work as a starting point (a practice recommendation, to adjust to your context):

• Code researcher: reading, pattern search and file listing (for example Read, Grep and Glob). No writing, no command execution.
• Reviewer: the same reading tools, plus the ability to run tests if needed. No file editing.
• Implementer: reading and editing, limited to the part of the project the task involves. No network access and no credentials.
• Test runner: execution of pre-agreed commands, no editing.

Three precautions that make a difference:

• The command execution tool is broad. If a subagent needs it, combine it with the project's permission rules to limit which commands can run, and do not rely only on the instruction written in the text.
• Tools coming from external servers (for example through the Model Context Protocol) count too. Give each subagent only the ones its role requires.
• When the model is configurable per subagent, simple read tasks may use a lighter model. Treat this as a hypothesis and compare quality in the pilot.

The quality of tool descriptions matters as well. Anthropic's writing on how to build tools for agents shows that clear names and a narrow scope reduce misuse. The same applies to the subagent's own description: it is what the main agent reads to decide whether to call it. A vague description like 'helps with code' causes the subagent to be called at the wrong time or never. A description like 'reviews changes already made and flags risks, without editing files' makes the boundary clear.

Illustrative scenario: changing the handoff rule of a customer service agent

Imagine, as an illustrative scenario, a company that maintains the code of a WhatsApp customer service agent and needs to change the rule that decides when a conversation passes to a person. The change touches several files and needs careful review. One possible split:

• Mapper: reads the repository and returns a short list of the places where the rule appears, with the relevant snippets. Read-only tools.
• Implementer: receives the list and makes the change only in the indicated files. Can edit, has no network access.
• Reviewer: reads the result, compares it with the agreed rule and runs the existing tests. Does not edit.

The gain here is not speed but separation of roles. Whoever reviews is not whoever wrote, and whoever maps has no way to change anything by mistake. To know what the handoff rule should do, start from a business document such as the WhatsApp AI agent human handoff playbook, and do not let the agent infer the policy.

One privacy caution: none of these subagents needs to read real customer conversations. Use synthetic or anonymized examples in tests, and keep personal data out of the repository and out of the agent's context.

A plan to introduce subagents to your team

The method we apply in AI projects works here at a small scale: map, limit, pilot and hand over. No hype, just four verifiable steps.

• Map: choose a real, repeated workflow, such as change review or impact analysis. Record how it is done today, how long it takes and where rework and errors show up. Without that starting point, there is no way to know whether things improved.
• Limit: for each subagent, write its role in one sentence, the explicit tool list and what it must return. Decide what requires human approval, for example any write outside the task folder. The AI agent approval policy template helps organize that decision.
• Pilot: run the workflow with one or two subagents, keeping a record of what each one read, executed and returned. Agree on the success criterion beforehand. The article on how to measure an AI automation pilot details metrics and decision gates.
• Hand over: document the subagent files in the repository, define who maintains them, and decide together whether to expand, adjust or stop. Stopping is a legitimate pilot outcome.

If your team is still getting started with the tool as a whole, the Claude Code for teams adoption guide covers the groundwork before subagents: permissions, review and usage routines.

Risks and common mistakes with subagents

Most problems come from excess permission and lack of records, not from model failure. The most frequent ones:

• Inheriting all tools by omission and only noticing when something is changed unexpectedly.
• Giving a subagent that reads external content (web pages, tickets, emails, third-party documents) a write or network tool as well. Instructions hidden in that content can try to divert its behavior. The OWASP list of risks in LLM applications treats this as prompt injection and excessive agency.
• Generic subagent descriptions, which make the main agent call them without criteria.
• Too many subagents with no owner, which nobody updates when the project changes.
• Accepting the subagent's summary as truth without checking. The summary is a synthesis and may omit something important. For risky decisions, ask for the evidence, such as file excerpts and test output.
• Keeping no record. Without a log of what was read and executed, no audit is possible.

A simple rule helps: if a subagent can read something untrusted, it should not be able to act on anything sensitive. Separating reading from acting across different subagents is often the best use of the split.

Frequently asked questions

Do subagents replace human review? No. A reviewer subagent gives a useful second reading, but it does not take responsibility for the change. Keep a person approving what goes to production, especially for code that touches customer data or sends messages.

Can a subagent call other subagents? According to the Claude Code documentation, subagents do not create other subagents, and coordination stays with the main agent. Since this behavior can change between versions, confirm it in the current documentation before designing a workflow that depends on it.

Does using subagents increase consumption? It can, because each one works in its own context and the total processed grows. In return, the main conversation stays cleaner. Measure both effects in the pilot before deciding whether the split pays off.

Do I need subagents to start with Claude Code? No. Start with the tool on simple tasks, with conservative permissions, and create a subagent only when there is a repeated, well-defined role, such as reviewing or mapping impact. A subagent is an organizational feature, not an entry requirement.

Sources

• Anthropic: Effective context engineering for AI agents
• Anthropic: Building effective agents
• OWASP: Authorization Cheat Sheet
• OWASP Top 10 for LLM Applications