Claude Code Sub-Agents: A Complete Breakdown from Architecture Design to Practical Application

After introducing Sub-Agents in Claude Code, Anthropic has overcome the limitations of a single AI model handling all tasks. Claude Code Sub-Agents allow you to create multiple specialized sub-agents, each with its own independent context, dedicated tool permissions, and specific model configurations. Instead of having one general AI agent handle code review, dependency checks, and test writing simultaneously, Sub-Agents achieve true task isolation. This isn't just an incremental feature addition; it's a fundamental architectural shift.

Imagine you are a project manager with research specialists, execution specialists, and quality assurance specialists reporting to you. You wouldn't have a research specialist make code modifications, nor would you have a quality assurance specialist make architectural decisions. Claude Code Sub-Agents are the AI-level implementation of this logic. Each agent focuses on a single domain, preventing context pollution and improving task completion accuracy.

According to the official Claude Code documentation, model selection for Sub-Agents follows a clear priority order: `CLAUDE_CODE_SUBAGENT_MODEL` environment variable > `model` parameter in each call > `model` field in the Sub-agent definition > the main conversation's model. This set of priority designs allows engineers to have fine-grained control at the global, project, and call levels.

This article will break down Sub-Agents from three dimensions: First, understand why the isolation architecture

Why a single AI agent can't handle complex engineering tasks

Why is the isolated design of Claude Code Sub-Agents superior to a single AI agent?

A Claude Code agent simultaneously handling code review, dependency checking, and unit test writing creates a hidden bottleneck: context pollution.

When an agent switches between three completely different engineering domains within just 5 minutes, its reasoning paths interfere with each other. Reviewing logic decision rules affect the thought process of test writing. Inspecting tool outputs pollutes subsequent code analysis. The result is a decrease in decision quality, an increase in execution time, and a rise in error rates.

Traditional monolithic model architectures force all tasks to share the same context window. Suppose your agent needs to simultaneously maintain the review rules for Project A, the dependency configuration for Project B, and the testing framework for Project C. These three sets of rules would compete for attention within the same memory space. The core reason Anthropic introduced Sub-Agents in Claude Code is to break through this limitation.

Claude Code's Three Built-in Sub-agent Types and Their Operating Mechanisms

Anthropic has built three specialized sub-agent types into Claude Code, each designed for a specific engineering task [citation:8]. This is not simply a functional classification – but rather architectural differences based on read/write permissions, model configurations, and automatic routing logic.

Explore Katako Proxy: The Read-Only Expert

The core limitation of the TypeSpec proxy is that it's read-only. It can scan the entire codebase, analyze file structures, and extract dependency lists, but it cannot modify any files.

Explore-type sub-agents are particularly useful when you need to quickly understand the architecture of an unfamiliar project. For example, when a new developer takes over a 50-file Node.js project on their first day, an Explore-type sub-agent can generate a complete directory tree diagram and core module relationship diagram within 30 seconds [citation:4]. This read-only design ensures the security of the codebase while providing rapid architectural understanding.

Pattern Proxy: The Execution Specialist

The child agent has write permissions, allowing it to directly modify code, update configuration files, and submit changes. It is suitable for automated code refactoring, dependency upgrades, and test fixes.

Audit type sub-agent: Audit expert

The Audit subtype agent combines reading and verification capabilities, which can check code quality, security vulnerabilities, and compliance issues, but cannot directly modify files.

Subagent Model Selection Priority and Cost Optimization Strategy

Anthropic designed a four-tier priority system in Claude Code to determine which model a Subagent uses [citation:1]. From highest to lowest priority, these are: the environment variable CLAUDE_CODE_SUBAGENT_MODEL, the `model` parameter during a single call, the `model` field in the Subagent definition, and finally, the primary conversation model.

The highest priority environment variable allows globally switching all Subagent models through environment configuration without modifying code. This is particularly valuable for production environments that require rapid adjustments to cost or performance.

In practice, a combination of the Haiku, Sonnet, and Opus models effectively balances cost and performance. Code review (which requires in-depth semantic analysis) is assigned to Opus, dependency checking (rule verification) to Sonnet, and code exploration (quick scanning) to Haiku.This configuration can reduce overall costs by more than 40% while maintaining high-quality review results.

Design Patterns for Permission Control, Tool Access, and Conditional Rules

This is not an option—rather, it's a necessary design to prevent sub-agents from performing operations outside their scope of responsibility. Permission control stems from the "principle of least privilege," ensuring that each sub-agent can only access the resources and tools required to complete its specific tasks.

Tool access lists are the first line of defense. You can explicitly define which tools each sub-agent can use. Audit agents should only be able to read files and version control history, and be prohibited from modifying code. For example, allow read tools like `git log` and `grep`, but prohibit destructive commands like `git push` and `rm`.

The dependency check agent needs to perform package manager tool version verification, but direct modification of package.json should be prohibited. If the audit agent accidentally gains write access, critical code could be mistakenly deleted; if the dependency agent can modify configurations, it could introduce incompatible versions.

Condition rules are the second line of defense. You can set logical conditions to verify agent decisions. For example, modify agents to require passing static analysis checks before executing code changes; dependency agents must verify backward compatibility before upgrading versions. These condition rules ensure the safety and controllability of automated processes.

FAQ

Does the Sub-Agent have a context size limitation?

Each sub-agent has its own independent context [citation:4], which means it does not share conversation history with other agents.In practice, if your main conversation is already using an 80% context window, a newly created sub-agent will start with a brand-new context and will not inherit the parent agent’s history. This is critical when working on long-term projects—the code review sub-agent will not be contaminated by logs from previous dependency checks.

What is the order of precedence for model inheritance?

Model selection follows a clear hierarchy of priorities [citation:1]: the CLAUDE_CODE_SUBAGENT_MODEL environment variable is checked first, followed by the model parameter during a one-off call, then the model field in the Sub-Agent definition, and finally the model of the main conversation. If not explicitly specified, Sub-Agents will default to inheriting the model of the main conversation [citation:3]. Supported aliases include ‘sonnet’, ’opus’, ’haiku’, or full model IDs like ‘claude-opus-4-8’ [citation:2].

How to troubleshoot when automatic routing fails?

Check three aspects: First, verify that the Sub-Agent's tool access permissions are correctly configured [citation:7]. Second, confirm that the logic of the conditional rules aligns with the actual task. Finally, check that the model aliases are using supported formats. A common reason is that the permission mode is set too restrictively, preventing the Sub-Agent from accessing necessary tools.

Can multiple sub-agents share the same tool?

Yes, but it needs to be clearly defined at the permission level. Different sub-agents can access the same tools, but their respective permission scopes are independent. For example, a code review sub-agent might only have file read permissions, while a sub-agent executing tests would have execution permissions. This layered design prevents information leakage [citation:5].

What engineering scenarios is Sub-Agent suitable for?

Specialization and reusability are key advantages [citation:6]. Typical applications include: agents dedicated to static analysis, dependency management agents, and code generation agents. Each agent focuses on a single domain and achieves 30–40% higher accuracy than general-purpose agents.Related Topic: “Priority and Cost Optimization Strategies for Subagent Model Selection.”

Conclusion

Claude Code's Sub-Agents architecture transforms the current landscape where a single model struggles with complex engineering tasks. Through three core design principles—isolation, specialization, and permission control—development teams can build more stable and auditable automated workflows while maintaining cost-effectiveness. Isolation ensures that failures do not cascade; specialization allows each agent to focus on its area of expertise, reducing the risk of hallucinations; and permission control prevents unauthorized system changes. In practice, selecting appropriate model priorities (claude-3-5-sonnet for high-frequency tasks and claude-3-opus for complex reasoning), defining clear tool access boundaries, and establishing conditional rules to validate agent decisions are key to moving from concept to production. This is not merely a technical upgrade, but rather an architectural rethinking of software development workflows.

Key Takeaways

• Sub-agents solve the capability bottleneck of a single AI agent in complex engineering tasks through isolation and specialization.
• The three built-in types (code execution, tool use, and reasoning) each have clear operating boundaries and cost characteristics.
• Model selection priority and tool access design directly impact system stability and auditability.
• Condition rules and permission controls are the defenses against proxy out-of-bounds operations, and are also essential mechanisms for production environments.
• From development to deployment, the key lies in clearly defining agent boundaries, rather than piling on more model capabilities.

Sources

1. Subagent model selection follows a priority hierarchy code.claude.com
2. Claude's Code Sub-agents feature enables the creation of multiple specialized child agents with independent contexts. — ithelp.ithome.com.tw
3. Claude Code comes with three built-in subagent types. — ksred.com