Subagent Orchestration with Iterative Retrieval in Claude Code

Claude Code delegates complex codebase exploration to lightweight subagents that execute a four-phase iterative retrieval loop, progressively refining file relevance scores until they return only the essential context to the main session.

Claude Code, as implemented in the affaan-m/everything-claude-code repository, handles large-scale code analysis through subagent orchestration combined with iterative retrieval. This architecture allows the main Claude session to spawn scoped agents that autonomously search, evaluate, and refine their context before reporting back, keeping the primary context window focused and efficient.

How Subagent Dispatch Works

The orchestration begins when the main session invokes the Task tool to create a subagent. According to commands/multi-plan.md, subagents are instantiated with a specific subagent_type—typically general-purpose for retrieval workflows—and inherit a constrained toolset defined in agents/*.md files.

The subagent receives a whitelist of safe tools such as Read, Glob, and Grep, preventing accidental modifications to the main session's state. As documented in AGENTS.md, each of the 27 available agents specifies precise tool scopes and activation conditions, ensuring the subagent operates within a sandboxed environment tailored to the retrieval task.

The Four-Phase Iterative Retrieval Loop

Inside the subagent, the algorithm defined in skills/iterative-retrieval/SKILL.md executes up to three cycles through four distinct phases: DISPATCH, EVALUATE, REFINE, and LOOP.

DISPATCH: Initial Search Broadening

The cycle begins with a broad file-search query (e.g., src/**/*.ts) sent to the retrieval agent. This phase casts a wide net to capture candidate files that might contain relevant code.

EVALUATE: Relevance Scoring

Each candidate file receives a relevance score between 0 and 1 based on the subagent's internal logic. The evaluation checks content against task keywords and semantic patterns to filter noise from the results.

REFINE: Query Optimization

The subagent updates the search query using newly discovered patterns, keywords, and exclusions identified during evaluation. This refinement narrows the search scope for the next cycle.

LOOP: Cycle Control

The algorithm repeats until reaching the maximum of three cycles or until the helper function hasCriticalGaps returns false while at least three files score ≥ 0.7 relevance. This termination condition ensures the subagent stops only when it has gathered sufficient high-quality context.

Returning and Merging Context

Once the iterative retrieval completes, the subagent returns a JSON payload containing file paths that met the relevance threshold. The main Claude session then performs an internal Read operation on each path, appending the content to its working context before resuming the original task.

This handoff ensures the primary agent receives only the final, curated file set rather than intermediate search noise. The merge process effectively compresses the subagent's exploration history into actionable context, preserving token budget for actual implementation work.

Code Implementation Examples

The following examples demonstrate the orchestration pattern using repository conventions.

Dispatching a subagent with iterative retrieval instructions:

Task(
  subagent_type="general-purpose",
  prompt=`When fixing the auth token expiry bug, run the iterative‑retrieval skill to gather all relevant source files.
  Use the following steps:
  1. DISPATCH: search src/**/*.ts for ["token","auth","expiry"]
  2. EVALUATE: keep files with relevance ≥ 0.7
  3. REFINE up to 3 cycles
  4. Return the final file list.`
)

The iterativeRetrieve helper function from the skill implementation:

async function iterativeRetrieve(task, maxCycles = 3) {
  let query = createInitialQuery(task);
  let bestContext = [];

  for (let cycle = 0; cycle < maxCycles; cycle++) {
    const candidates = await retrieveFiles(query);               // DISPATCH
    const evaluation  = evaluateRelevance(candidates, task);    // EVALUATE

    const high = evaluation.filter(e => e.relevance >= 0.7);
    if (high.length >= 3 && !hasCriticalGaps(evaluation)) {
      return high;                                             // STOP
    }

    query = refineQuery(evaluation, query);                    // REFINE
    bestContext = mergeContext(bestContext, high);
  }
  return bestContext;                                          // FINAL
}

Context payload structure returned to the main session:

{
  "files": [
    "src/auth/auth.ts",
    "src/auth/jwt-utils.ts",
    "src/auth/session-manager.ts"
  ]
}

Benefits of Subagent Isolation

Token Efficiency: By confining extensive file exploration to subagents, the main session imports only the final high-value results. This prevents context window pollution with irrelevant intermediate files, as emphasized in the-shortform-guide.md.

Sandboxed Execution: Subagents operate with limited toolsets defined in agents/*.md, creating strict boundaries that prevent side effects on the primary session's state or working memory.

Parallel Execution: Multiple subagents can spawn concurrently for independent retrieval tasks. The Parallel Workflows section of the-shortform-guide.md describes how complex tasks decompose into simultaneous sub-operations, each running its own iterative retrieval loop before aggregating results back to the main thread.

Summary

• Subagent orchestration in Claude Code uses the Task tool to spawn scoped agents with limited toolsets defined in agents/*.md and cataloged in AGENTS.md.
• The iterative retrieval skill runs a four-phase loop (DISPATCH → EVALUATE → REFINE → LOOP) specified in skills/iterative-retrieval/SKILL.md.
• Files are scored on a 0–1 relevance scale; only those scoring ≥ 0.7 are returned to the main session.
• Key implementation functions include iterativeRetrieve, evaluateRelevance, refineQuery, and hasCriticalGaps.
• This architecture delivers token efficiency, isolation, and parallelism for large-scale codebase analysis.

Frequently Asked Questions

What is the maximum number of cycles in the iterative retrieval loop?

The iterative retrieval loop executes a maximum of three cycles as defined by the maxCycles parameter in the iterativeRetrieve function. The loop terminates early if the subagent discovers three or more files with relevance scores ≥ 0.7 and no critical gaps remain in the evaluation.

Which files define the available subagent types and their capabilities?

Subagent definitions reside in the agents/*.md files, with a complete catalog available in AGENTS.md. This documentation describes 27 distinct agents, including the general-purpose type commonly used for retrieval tasks, and specifies which tools each agent may invoke (e.g., Read, Glob, Grep).

How does the main Claude session receive context from a subagent?

After completing the retrieval loop, the subagent returns a JSON payload containing an array of high-relevance file paths. The main session then internally executes Read operations on these paths, merging the file contents into its working context before proceeding with the primary task.

Can multiple subagents run iterative retrieval in parallel?

Yes. According to the-shortform-guide.md, Claude Code supports parallel workflows where multiple subagents spawn concurrently for independent tasks. Each subagent runs its own iterative retrieval loop, allowing simultaneous exploration of different codebase areas before aggregating results back to the main session.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}