Subagents should receive distilled system prompts tailored to their role

Summary

Subagents receive the full ~15.6K token terminal agent system prompt, including instructions for features they can't use (git commits, PR creation, etc.). Limited agents like Explore should receive a distilled prompt with only relevant instructions.

Environment

• Claude Code version: 2.1.29
• OS: Arch Linux 6.18.3

The Problem

An Explore agent has 4 read-only tools (Bash, Glob, Grep, Read), but receives the same system prompt as the terminal agent which includes:

• Git commit guidelines and safety protocols
• PR creation workflows
• Write/Edit tool instructions
• Full MCP server instructions
• Plugin agent descriptions

None of these are relevant to a read-only exploration task.

Test Results

Spawned Explore agent (tools: Bash, Glob, Grep, Read only):

Total context: 17,508 tokens
  - Cached (shared base): 15,617 tokens (89%)
  - Agent-specific: 1,881 tokens (10%)
  - User prompt: 10 tokens

What's in that 15.6K base prompt?

| Section | Relevant to Explore? | Tokens (est.) |
|---------|---------------------|---------------|
| Git commit guidelines | ❌ No (read-only) | ~800 |
| PR creation workflow | ❌ No (read-only) | ~600 |
| Write/Edit tool instructions | ❌ No (not available) | ~400 |
| MCP server instructions | ❌ No (not available) | ~1,500 |
| Plugin agent descriptions | ❌ No (can't spawn subagents) | ~2,400 |
| Core coding guidelines | ✓ Yes | ~2,000 |
| Tool usage policy | ✓ Partial | ~500 |

Expected: Distilled Prompts Per Role

| Agent Type | Role | Expected Prompt Size |
|------------|------|---------------------|
| Explore | Read-only codebase search | ~3-4K tokens |
| Code-reviewer | Read + analyze | ~4-5K tokens |
| Plan | Design without writing | ~5-6K tokens |
| General-purpose | Full capabilities | ~15K tokens (current) |

Example: Distilled Explore Prompt

An Explore agent prompt might include:

• Core identity and tone guidelines (~500 tokens)
• Codebase exploration best practices (~500 tokens)
• 4 tool definitions: Bash, Glob, Grep, Read (~2,000 tokens)
• Safety rules relevant to read operations (~500 tokens)

Total: ~3,500 tokens vs current 17,500 tokens

---

Cumulative Impact: Typical Programming Session

Based on actual session logs, here's the token overhead for a typical feature implementation:

Session Profile

• 1 planning phase (Plan agent)
• 3 exploration tasks (Explore agents)
• 2 code reviews (code-reviewer agents)
• Plugin overhead on every request (~50 requests)

Token Bloat Calculation

| Source | Count | Bloat per | Total Bloat |
|--------|-------|-----------|-------------|
| Explore agents | 3 | ~12K | 36K |
| Plan agent | 1 | ~10K | 10K |
| Code-reviewer agents | 2 | ~10K | 20K |
| Plugin context overhead | 50 requests | ~4.4K | 220K |
| Total session bloat | | | ~286K tokens |

Cost Impact (Sonnet pricing)

| Metric | With Bloat | Optimized | Savings |
|--------|------------|-----------|---------|
| Subagent tokens | 66K | ~18K | 48K |
| Plugin overhead | 220K | ~50K* | 170K |
| Total | 286K | ~68K | ~218K (76%) |

*Assumes granular plugin skill control reduces overhead by ~75%

At Scale

| Sessions/month | Current Cost | Optimized | Monthly Savings |
|----------------|--------------|-----------|-----------------|
| 100 | ~$86 | ~$20 | ~$66 |
| 500 | ~$429 | ~$102 | ~$327 |
| 1000 | ~$858 | ~$204 | ~$654 |

(Based on Sonnet input pricing: $3/1M tokens)

---

Impact

• Every subagent spawn costs ~12K unnecessary tokens
• No cost savings from using limited-tool agents
• Irrelevant instructions may confuse the model about its capabilities

Proposed Solution

Create role-appropriate prompt templates:

1. Base prompt - Identity, tone, core safety rules (~1-2K)
2. Role-specific sections - Only include instructions for available tools
3. Tool definitions - Only tools the agent can actually use

The prompt builder would compose: base + role_instructions + tool_definitions

Prior Art

• #12428 - Same feature request, closed by autoclose bot without action. That issue specifically called out the Committing changes with git and Creating pull requests sections being unnecessary in Explore agents.

Related Issues

• #22335 - LSP plugins spawn eagerly regardless of file types
• #22345 - Plugin skills lack granular control
• #13605 - Custom plugin subagents cannot access MCP tools