Context Flow with Subagents

When Claude Code delegates a task to a subagent:

1. The main agent generates a task prompt — a focused description of what it needs
2. The subagent receives only that prompt — not the full conversation history
3. The subagent executes in complete isolation
4. Only the final result travels back to the main agent
5. All intermediate work (tool calls, file reads, reasoning) is discarded

This isolation is the foundation of efficient, scalable agentic workflows.

How Context Flows Between Agents

1. The subagent starts with two inputs only:
2. Its own system prompt (the .md file body)
3. The task prompt generated by the main agent
4. It knows nothing about the user's original question or conversation history
5. Output flows one way: subagent → main agent
6. The quality of the task prompt the main agent writes directly determines the subagent's output quality

Context Window Growth and Its Costs

1. Every model has a maximum context window — a token limit
2. As a session grows, the window fills with conversation, tool outputs, and file content
3. Cost — API pricing is per input token; large contexts are expensive
4. Latency — Processing more tokens takes longer on every turn
5. Quality — Models reason worse when the context is noisy and bloated

Context Pollution

1. Intermediate results that are no longer needed stay in the context
2. Example: 20,000 tokens of raw file reads linger after the summary is produced
3. Those tokens are re-sent (and re-paid) on every subsequent request

Subagents as Context Preservation

1. Delegating a task to a subagent keeps the main context lean
2. All noisy intermediate work stays in the subagent's isolated side chain
3. Only the clean, condensed result comes back to the main thread
4. Multiple subagents can run in parallel without interfering with each other

Subagents are not just convenience — they are a deliberate strategy for long-session quality.

Building the Mermaid Diagram Subagent

A subagent lives in .claude/agents/mermaid-diagram-generator.md

The YAML frontmatter defines its identity and constraints:

1. name — How Claude Code identifies this agent
2. description — Controls when and how the main agent delegates
3. tools — Only the tools this agent actually needs
4. model — Right-sized: sonnet is sufficient for diagrams

Tool Pollution and Least Privilege

1. Every tool in a subagent's list is loaded into its context as a definition
2. Irrelevant tools add noise, slow reasoning, and increase cost
3. Tool pollution: giving an agent far more tools than it needs

The Principle of Least Privilege

1. Give a subagent only the tools it needs for its specific job
2. A diagram generator needs: Read, WebSearch, WebFetch, Write
3. It does not need: Bash, Edit, MultiEdit, KillBash
4. A subagent that cannot use Bash cannot accidentally delete files
5. Least privilege is a safety mechanism, not just an optimisation

Shaping Subagent Behaviour via the Description Field

The description field has two distinct roles:

1. Routing trigger — tells the main agent when to delegate to this subagent
2. Prompt shaping — tells the main agent how to write the task prompt

Example from the diagram generator's description:

1. This is an instruction to the main agent, not the subagent
2. Before delegating, the main agent will distil and sketch the concept
3. The subagent receives a cleaner, more focused input as a result
4. The description field is a pre-processing instruction

Refining Subagent Output

Two refinement points, two different targets:

System Prompt (subagent behaviour)

1. Step 0: Added to make the subagent research patterns online before drawing
2. Step 7: Added to enforce machine-readable output — diagram only, no preamble

Description Field (main agent prompting)

1. Controls what context the main agent provides when it delegates
2. Add "simplify to GIST + ASCII sketch" to improve input quality

Refinement is iterative: deploy → observe output → identify weakest point → add targeted instruction.

Key Takeaways

1. Subagents receive only the task prompt the main agent generates — never the full conversation history
2. All intermediate work stays in the subagent's isolated context — only the final result returns to the main thread
3. Subagents are a context preservation strategy: they keep the main session lean, fast, and high-quality
4. The description field controls both when the main agent delegates and how it writes the task prompt
5. Apply least privilege to tool selection — fewer tools means faster, cheaper, and safer subagents
6. Always review third-party subagent description fields — they are injected into the main agent's system prompt