Claude Explore Agent Architecture

Complete reverse engineering of Claude Code's Explore sub-agent.

Overview

The Explore sub-agent is spawned when Claude Code needs to search or understand a codebase. It runs as a completely independent Claude instance with its own system prompt, restricted tools, and conversation context.

Spawning

The parent agent spawns an Explore sub-agent via the Task tool:

{
  "name": "Task",
  "input": {
    "subagent_type": "Explore",
    "prompt": "Explore this codebase to understand the proxy architecture...",
    "description": "Explore proxy interception architecture"
  }
}

System Prompt

The Explore agent receives a specialized system prompt:

You are a Claude agent, built on Anthropic's Claude Agent SDK.
You are a file search specialist for Claude Code, Anthropic's official CLI
for Claude. You excel at thoroughly navigating and exploring codebases.

=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
This is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:
- Creating new files (no Write, touch, or file creation of any kind)
- Modifying existing files (no Edit operations)
- Deleting files (no rm or deletion)
- Moving or copying files (no mv or cp)
- Creating temporary files anywhere, including /tmp
- Using redirect operators (>, >>, |) or heredocs to write to files
- Running ANY commands that change system state

Your role is EXCLUSIVELY to search and analyze existing code.

Key System Prompt Components

Model Information

You are powered by the model named Haiku 4.5.
The exact model ID is claude-haiku-4-5-20251001.
Assistant knowledge cutoff is February 2025.

Available Tools

The Explore sub-agent has 21 tools (varies based on MCP servers):

Core Tools (8)

MCP Tools (13)

• mcp__logger__log_message
• mcp__logger__get_trace
• ListMcpResourcesTool
• ReadMcpResourceTool
• mcp__plugin_claude-mem_claude-mem-search__* (9 tools)

Explicitly Missing Tools

Request/Response Cycle

Initial Request Structure

{
  "model": "claude-haiku-4-5-20251001",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "<prompt from Task tool>",
          "cache_control": { "type": "ephemeral", "ttl": "1h" }
        }
      ]
    }
  ],
  "system": [
    { "type": "text", "text": "You are a Claude agent..." },
    { "type": "text", "text": "You are a file search specialist..." }
  ],
  "tools": [ /* 21 tools */ ],
  "stream": true,
  "max_tokens": 16000
}

Conversation Flow (Observed)

A typical exploration makes 20+ API calls:

Turn | Messages | Tool Calls           | Stop Reason
-----|----------|---------------------|------------
#16  | 1        | Bash (find)         | tool_use
#17  | 1        | (parsing)           | end_turn
#18  | 3        | Bash (ls)           | tool_use
#19  | 1        | (parsing)           | end_turn
#20  | 5        | Read, Glob, Bash    | tool_use
#21  | 1        | (parsing)           | end_turn
#23  | 7        | Read ×3             | tool_use
#24  | 9        | Read, Bash ×2       | tool_use
...  | ...      | ...                 | ...
#38  | 23       | (final response)    | end_turn

Parallel Tool Calls

The system prompt encourages parallel tool calls:

"Wherever possible you should try to spawn multiple parallel
tool calls for grepping and reading files"

Observed parallel calls:

• Read × 3 files simultaneously
• Bash × 2 commands simultaneously
• Read + Glob + Bash in one turn

Result Return

The sub-agent's final response is returned to the parent as a tool_result:

{
  "type": "tool_result",
  "content": [
    { "type": "text", "text": "<sub-agent findings>" },
    { "type": "text", "text": "agentId: a04bf57 (for resuming...)" }
  ],
  "tool_use_id": "toolu_016JusHyXdMABbVTCwtgNiz1"
}

Agent ID

Every sub-agent execution returns an agent ID:

• Format: 7-character hex string (e.g., a04bf57)
• Purpose: Resume the agent with full context
• Usage: Pass to Task tool with resume parameter

Observed Behavior

Tool Usage Patterns

From our captured session:

Request #16: find ... -type f        (discover file structure)
Request #18: ls -la ...              (detailed listing)
Request #20: Read proxy.js           (read main file)
            Glob **/*.js            (find all JS files)
Request #23: Read proxy-modifier.js  (read related files)
            Read mini-client.js
            Read mcp-logger.js
Request #24: Read README.md          (understand project)
Request #27: Read ARCHITECTURE-SUMMARY.md
            Read REVERSE-ENGINEERING.md
Request #29: Read DEEP-DIVE.md
Request #31: Read 0001_request.json  (examine captures)
            Read 0001_response.json
Request #32: Read analyze-session.js
            Read trace-conversation.js
Request #34: grep -r "proxy|8888"    (search patterns)
Request #36: grep -r "stream|SSE"    (search streaming)

Search Strategy

1. Discovery: find to get file tree
2. Structure: ls -la for details
3. Entry Points: Read main files (proxy.js, README.md)
4. Deep Dive: Read related files found
5. Pattern Search: grep for specific terms
6. Documentation: Read docs for context

Performance Characteristics

Limitations Discovered

Response Size Limit

Large responses (166KB+) can cause errors:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "The request body is not valid JSON:
               unexpected end of data: line 1 column 166995"
  }
}

No Sub-Sub-Agents

Explore agents cannot spawn their own sub-agents:

• No Task tool available
• Single-level hierarchy only

Read-Only Enforcement

The system prompt says tools will "fail" but actually:

• Edit/Write tools are not in the tool list
• Bash commands are not actually blocked
• Relies on prompt-level instructions

Comparison with Main Agent

Resumption

To resume a sub-agent:

{
  "name": "Task",
  "input": {
    "resume": "a04bf57",
    "prompt": "Continue exploring and focus on..."
  }
}

The resumed agent:

• Has full previous context
• Continues conversation history
• Can reference prior findings

Implementation Notes

Caching

Each sub-agent request includes:

"cache_control": { "type": "ephemeral", "ttl": "1h" }

The sub-agent builds its own cache independent of the parent.

Token Counting

Interleaved with sub-agent requests are token counting calls:

• Requests #3-15: Parallel count_tokens calls
• Uses same Opus model as parent
• Not part of sub-agent conversation

Headers

Sub-agent requests include:

anthropic-beta: oauth-2025-04-20,interleaved-thinking-2025-05-14
user-agent: claude-cli/2.1.20 (external, cli)
x-app: cli

Reverse engineered from captured API traffic. See experiments/captures-subagent/ for raw data.