Claude Code subagents are specialized agents that handle delegated work in separate context windows. Their role definitions limit which tools are available, while Claude Code permission rules decide whether matching tool calls are allowed, require confirmation, or are denied.
What Claude Code subagents are
A Claude Code subagent handles a delegated task in its own context window and returns its result to the main conversation. Its intermediate file reads, tool results, and exploration can therefore remain outside the main context. This helps preserve space and focus in a long-running session.
Claude Code includes Explore, Plan, and general-purpose subagents. Explore and Plan use read-only tools, with Write and Edit denied. The general-purpose subagent can use every tool available to subagents, making it suitable for work that may require both investigation and changes. The important distinction is that each type combines a particular role with a documented level of tool access; assigning a role does not by itself grant unrestricted authority.

When subagents help—and when they add overhead
Subagents are useful when a task involves substantial research, a fresh review, verification, or a phased workflow. For example, one subagent can investigate relevant files and return a compact result without filling the main conversation with every search and read operation. A separately scoped reviewer can also approach work with a fresh context.
Independent tasks can be delegated to multiple subagents concurrently, allowing their work to finish in parallel instead of waiting for each task sequentially. Different roles can also have different access profiles, such as read-only tools for research and broader editing tools for implementation.
Delegation still has overhead. For a small, tightly connected task, describing the assignment and transferring the result may cost more time or context than completing it directly in the main conversation.

How custom subagents and tool permissions work
Custom subagents are Markdown files with YAML frontmatter. Project-level definitions can be stored in .claude/agents/, while user-level definitions can be stored in ~/.claude/agents/. Documented configuration fields include tools and disallowedTools, which control tool availability, as well as model and permissionMode. A read-only reviewer, for example, can be limited to Read, Grep, and Glob to reduce the possibility of unintended modifications.
Tool availability and permission outcomes are related but distinct. A subagent’s configuration narrows the tools it can access. Claude Code’s permission rules then classify matching tool use as allow, ask, or deny: allowed calls proceed without manual approval, ask rules request confirmation, and denied calls are prevented.
Rules for the Agent tool can match a direct input parameter such as model or isolation. They cannot match nested fields, and separate conditions require separate rules. To prevent all subagent delegation, deny the Agent tool. To block selected built-in subagent types instead, add those types to permissions.deny.
There is also a session-discovery detail to remember. If a scope’s agents directory did not exist when the current session began, restart Claude Code after creating its first agent file so the new directory can be detected.
Conclusion
Claude Code subagent behavior depends on three layers: the role’s instructions, the tools made available to it, and the permission rules applied to matching calls. Start with one recurring, bounded role. Grant only the tools it needs, then verify which calls are allowed, require confirmation, or are denied. If you created the scope’s first agents directory during the session, restart Claude Code before trying the new subagent on a limited task.
Disclosures and limitations
- AI assistance was used to draft and organize this article.
- Product capabilities and procedures are based on the cited Anthropic documentation. Check current provider documentation before setting permissions for your own project.
Sources
- Create custom subagents – Claude Code Docs — Claude Code Docs
- Claude Code Hooks and Subagents: Deterministic Automation and Parallel Work — claudemap.org
- GitHub – VoltAgent/awesome-claude-code-subagents: A collection of 100+ specialized Claude Code subagents covering a wide range of development use cases — GitHub
- Claude Code Subagents: What They Are and How They Work | ADevGuide — ADevGuide
- Configure permissions – Claude Code Docs — Claude Code Docs
- Curated research source from code.claude.com — code.claude.com
- How and when to use subagents in Claude Code — Claude
- Subagents in the SDK – Claude Code Docs — Claude Code Docs
- Subagents · Claude Code 101 · Claude Academy — Claude Academy
- GitHub – weaponslab/claude-agents: A collection of production-ready subagents for Claude Code — GitHub
Improve this guide
Report a problem or suggest the next question
Submissions enter a private editorial queue. They are reviewed and deduplicated before any public update or new page is created.
