Use Tool Search Tool pattern for Task subagents to reduce context overhead

Problem

The Task tool currently loads all 142 subagent descriptions (~4,500 tokens) into context on every message, regardless of whether agents are used.

This is a significant token drain that scales poorly as more agents are added.

Solution

Apply the existing Tool Search Tool pattern to subagents:

{
  "type": "tool_search_tool_bm25_20251119",
  "name": "subagent_search"
},
{
  "name": "python-pro",
  "description": "Expert Python developer specializing in...",
  "defer_loading": true
},
{
  "name": "golang-pro", 
  "description": "Expert Go developer specializing in...",
  "defer_loading": true
}
// ... remaining agents with defer_loading: true

How it would work

1. Keep 5-10 most-used agents (Explore, Plan, general-purpose, etc.) as non-deferred
2. Mark remaining ~130 agents with defer_loading: true
3. When user/Claude needs a specialized agent, search via BM25/regex
4. Load only the matched agent definition into context

Benefits

| Metric | Current | With defer_loading |
|--------|---------|-------------------|
| Base context overhead | ~4,500 tokens | ~500 tokens |
| Tokens per agent used | 0 (already loaded) | ~30-50 tokens |
| Break-even point | Always pays full cost | ~80 agent invocations/session |

For typical sessions using 1-5 agents, this saves 3,500-4,000 tokens per message.

Implementation

The Tool Search Tool infrastructure already exists (advanced-tool-use-2025-11-20 beta). This would be:

1. Add defer_loading: true to non-core subagent definitions
2. Include tool_search_tool_bm25_20251119 in Task tool setup
3. Keep core agents (Explore, Plan, Bash, general-purpose) always loaded

References

• Tool Search Tool docs
• Beta header: advanced-tool-use-2025-11-20
• Supports up to 10,000 tools with 3-5 results per search