Coding agents are most useful when they can inspect a repository, run commands, edit files, and validate their work. Those same capabilities make long sessions noisy. A single agent that reads every candidate file, follows every tangent, and keeps every command result in one transcript eventually spends much of its context budget on stale exploration rather than the current decision.
Context-isolated subagents solve that problem by turning side work into bounded delegation. A parent coding agent keeps the main objective, constraints, and integration responsibility. It spawns a specialized worker for a concrete task, such as “trace the authentication middleware” or “review this diff for SQL injection risks.” The worker receives its own context window, tool scope, prompt, and sometimes model choice. When it finishes, it returns a compact result instead of dumping its full search trail into the parent conversation.
This pattern is narrower than general multi-agent orchestration. The goal is not to simulate a company of autonomous agents. The goal is to preserve the parent session’s working memory, parallelize independent investigation, restrict risky tool access, and reuse repeatable expert roles inside software engineering workflows.
The source repository for this topic catalogs many Claude Code subagent definitions, while the companion documentation explains the mechanism: subagents can be built-in or custom, live at project or user scope, carry YAML frontmatter, and run with explicit tools, permissions, models, hooks, skills, memory, and optional worktree isolation.
A subagent starts with a fresh context shaped by its role and task. It does not need the full parent transcript, and the parent does not need the worker’s full transcript afterward. This keeps high-volume exploration, logs, grep output, and irrelevant file excerpts out of the main reasoning loop.
Isolation is a budget and quality control tool. The parent can delegate breadth while preserving depth: it continues to reason about the end-to-end change while workers chase side questions and report distilled findings.
A reusable subagent is usually a Markdown file with frontmatter plus instructions. The frontmatter declares metadata such as name, description, allowed tools, model, and optional constraints. The body describes how the worker should think, what evidence it should return, and what it must avoid.
The description matters because the parent uses it as a routing hint. A vague description causes accidental delegation; an overly narrow description forces the parent to do work that a worker could handle. Good descriptions name the trigger conditions, expected inputs, and output contract.
Subagents should receive only the capabilities they need. A read-only explorer can use file search and shell inspection without edit tools. A security reviewer can inspect diffs without writing files. A worker that owns a bounded patch can edit files, but destructive commands should remain blocked unless the task explicitly requires them.
Tool scoping turns delegation from a prompt convention into an enforceable boundary. It also makes subagent output easier to trust because the reviewer knows which side effects the worker could and could not perform.
The parent agent should keep responsibility for integration, prioritization, and final validation. Subagents are best used for bounded sidecar work that can run independently and return a clear artifact: findings, a patch in a known file scope, a test result, or a recommendation.
A custom subagent definition typically combines routing metadata with focused operating instructions. The exact field names vary by runtime, but the design pattern is stable: give the worker a name, a delegation description, a tool policy, and a crisp task rubric.
---
name: security-reviewer
description: Review code changes for auth, injection, secrets, and unsafe data access.
tools: Read, Grep, Glob, Bash
model: sonnet
---
You are a security-focused code reviewer.
When invoked:
1. Inspect only the changed files and directly related call sites.
2. Prioritize exploitable issues over style concerns.
3. Cite file paths and line numbers for each finding.
4. Return "no findings" if no concrete risk is present.
5. Do not edit files.The frontmatter is not decoration. It is the routing and capability contract. The worker’s body is the behavior contract. Both need version control review when teams share subagents across a repository.
The parent should send a task that is specific enough for the worker to complete without repeatedly asking for clarification. Good delegated tasks include the objective, file or subsystem boundaries, allowed side effects, expected output format, and any time or depth limit.
def should_delegate(task):
return (
task.is_independent and
task.has_clear_output and
not task.blocks_next_parent_step and
task.context_volume_estimate > 2000
)
delegation = {
"agent": "security-reviewer",
"task": "Review the OAuth callback diff for token leakage and state validation bugs.",
"scope": ["src/auth/oauth.ts", "src/auth/session.ts"],
"output": "Findings ordered by severity with file and line references.",
"side_effects": "read-only",
}This avoids the common failure mode where a subagent is asked to “look around” with no stop condition. A bounded worker can decide quickly, return high-signal context, and let the parent continue integrating the larger change.
The parent should not blindly trust a worker’s conclusion. Useful subagent output includes the answer, the evidence needed to verify it, and any artifact that needs integration. For code edits, the worker should list changed files. For research, it should list the files inspected and the key facts discovered. For review, it should separate findings from residual risks.
Large implementation tasks often need several independent lookups: where a pattern is used, which API shape is preferred, which tests cover a subsystem, and which generated files should not be edited. Read-only explorer subagents can answer these questions in parallel while the parent agent plans or starts non-overlapping work.
Security, performance, accessibility, database correctness, and API compatibility reviews each benefit from a different rubric. Instead of bloating the parent prompt with every checklist, teams can encode those rubrics as reusable subagents and invoke them only when relevant.
When a task decomposes cleanly by file ownership, workers can make limited patches in disjoint areas. For example, one worker can update backend validation while another updates frontend form copy. The parent still reviews diffs, resolves conflicts, and runs the final validation suite.
Build logs, failing test output, and trace dumps can overwhelm a main conversation. A debugging subagent can inspect verbose output, classify the failure, and return only the root cause hypothesis, relevant excerpt, and next command to run.
Before spawning a worker, check whether the task is independent, bounded, useful in parallel, and safe under a restricted tool policy. If the parent needs the answer before its very next step, the parent should often do the work locally to avoid coordination overhead.
class DelegationDecision:
def __init__(self, task):
self.independent = task.no_shared_write_scope()
self.clear_output = task.expected_artifact is not None
self.parallel_value = task.can_run_while_parent_works()
self.safe_tools = task.required_tools.issubset(task.allowed_tools)
def should_spawn(self):
return all([
self.independent,
self.clear_output,
self.parallel_value,
self.safe_tools,
])Explorer subagents should be read-only and optimized for fast code search. Worker subagents may edit files, but they need explicit ownership boundaries and instructions not to revert unrelated work. Keeping these roles separate reduces accidental broad edits and makes output easier to interpret.
Project-specific subagents belong near the code they support. Storing them in a repository-level agent directory lets the team review changes to prompts, tool access, and models just like source code. Global personal subagents are useful for individual workflows, but shared engineering behavior should be visible and auditable.
Track which subagent was used, the task it received, the files it touched, the tools it could call, and the summary it returned. Traces make it possible to debug bad delegations and refine routing descriptions over time.