Subagent Delegation Patterns

Here is an experience every active Claude Code user recognizes: you are working on a clean feature branch, and you ask Claude to perform a large exploratory task, such as auditing thirty dependency packages or scanning your codebase for security vulnerabilities.

Twenty minutes later, your session context is flooded with 100,000 tokens of raw linter warnings, grep dumps, and library changelogs. The feature you were building earlier is pushed out of recent memory. You spend the rest of the afternoon compacting context and re-explaining earlier decisions.

Subagents eliminate this context pollution. A subagent runs in a separate, isolated context window with its own prompt, tools, and permissions. It performs the noisy side-task, extracts the essential conclusions, and returns a concise summary back to your main session.

Why context isolation is an architectural superpower

Subagents provide what computer science calls encapsulation. In an agentic system, context is memory. By delegating a heavy research task to a subagent, you protect your primary session's attention while allowing the subagent to burn through tokens freely in its own sandbox.

• Context protection: Search logs and failed experiments stay inside the subagent window.
• Tool specialization: A subagent can be granted read-only tools while your main session retains write permissions.
• Model optimization: You can run subagents on lighter, faster models (like Haiku) for bulk scanning while keeping Opus or Sonnet for your main session architecture.

How context: fork works in skill frontmatter

In Claude Code, you do not need complex SDK code to spawn a subagent. A skill can declare that it should run as an isolated worker directly in its frontmatter using `context: fork`:

---
name: security-audit
description: Use when auditing the repository for hardcoded secrets, open vulnerabilities, or outdated packages.
context: fork
agent: security-auditor
---

# Security audit

1. Scan package.json and run npm audit.
2. Use grep to scan for potential API keys or tokens in config/.
3. Verify that .env is properly gitignored.
4. Output a bulleted vulnerability report with severity rankings.

Background vs blocking execution

In recent Claude Code versions (v2.1.218+), skills with `context: fork` run in the background by default. You can continue typing prompts and editing code in your primary session while the subagent works concurrently.

Defining custom agents in .claude/agents/

Notice the `agent: security-auditor` key in the frontmatter above. You can define specialized agent personas in `.claude/agents/<name>.md`. A custom agent definition specifies system instructions, restricted tool permissions, and model overrides.

Managing spawn depth and concurrency caps

To prevent runaway recursive loops where subagents spawn infinite child subagents, Claude Code enforces strict boundaries:

• Spawn depth: Capped at 3 layers deep by default (`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`).
• Concurrency: Capped at 20 concurrent subagents (`CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`).
• Summary return: When a subagent finishes, only its final response is delivered to the parent session. Intermediate reasoning turns are discarded, keeping parent context clean.