Sub-Agent Parallel Research

Sub-agents execute read-only tools in parallel within isolated contexts, then return summaries to the main conversation.

Why Sub-Agents?

Heavy research tasks (multi-file analysis, multi-round reasoning) consume context tokens rapidly. Sub-agents isolate this work:

Main context: 50k tokens used
  → Spawn sub-agent for research
  → Sub-agent: 30k tokens of exploration (isolated)
  → Returns: 500 token summary
  → Main context: still 50k tokens (no pollution)

How It Works

Spawning a Sub-Agent

Sub-agents are spawned automatically when the LLM determines a research task is heavy enough to warrant isolation:

LLM: "I need to analyze the full auth module before making changes"
  → Spawns sub-agent with task: "Analyze auth module structure"
  → Sub-agent runs in isolated context
  → Returns summary: "auth.py has 3 classes, login uses JWT..."

Read-Only Execution

Sub-agents can only use read-only tools:

Allowed Blocked
read_file write_file
glob_files edit_file
grep_content execute_bash
locate_symbol
find_references

This ensures sub-agents cannot modify your code.

One-Time Use

Each sub-agent is spawn-and-forget:

  1. Created with a specific task
  2. Runs tools to completion
  3. Returns a brief summary (to_brief)
  4. Context is discarded — never reused

Integration with Main Conversation

Sub-agents are part of the harness (autonomous chat) paradigm:

Main harness loop:
  → LLM identifies heavy research task
  → Calls spawn_subagent tool
  → Continues other work while sub-agent runs
  → Receives summary
  → Uses summary to inform next action

The sub-agent's summary enters the main context as a tool result — just like any other tool output.

Example: Multi-File Analysis

User: "Before refactoring the auth module, analyze all related files"

LLM decides to spawn a sub-agent:
  Task: "Analyze all files related to authentication:
         - Find all files that import from auth/
         - Check each file's dependencies
         - Report structure and coupling"

Sub-agent runs:
  1. grep_content("from.*auth") → 12 files
  2. read_file each → examine imports
  3. locate_symbol("AuthService") → 3 definitions
  4. find_references("login") → 15 references

Sub-agent returns summary (500 tokens):
  "Auth module: 5 files in auth/, imported by 12 files.
   AuthService class defined in 3 places.
   login function has 15 call sites.
   Tightest coupling: routes/auth.py → services/auth.py"

Main context receives this summary without any of the sub-agent's intermediate exploration.

Concurrency

Multiple sub-agents can run in parallel:

LLM spawns 3 sub-agents simultaneously:
  Agent 1: Analyze auth module
  Agent 2: Analyze user module
  Agent 3: Analyze database schema

All 3 run concurrently → summaries arrive → LLM synthesizes

This dramatically reduces wall-clock time for multi-area research.

Effort and Client Sharing

Aspect Behavior
Effort level Follows main conversation (shared effort_ref)
API client Shares connection pool with main conversation
Token budget Independent — doesn't consume main context tokens
Context Fully isolated — never touches main message history

When Sub-Agents Are Used

The LLM autonomously decides when to spawn sub-agents. Generally:

Trigger Example
Large codebase scan "Analyze all files in src/"
Deep dependency analysis "Trace the full call chain from entry point"
Multi-file comparison "Compare auth implementations across 3 modules"
Research before edit "Understand the architecture before refactoring"

Monitoring Sub-Agent Activity

Sub-agent spawning appears in the status bar:

🧠 medium  📊 12.4k tokens  🔍 [子agent] Analyzing auth module...

After completion:

🔍 [子agent success] tokens=2.1k

Summary

Sub-agents are a token efficiency mechanism. They let the LLM do heavy research without polluting your main conversation context. The research stays isolated, only conclusions enter the main flow.