# Subagent Orchestration with Iterative Retrieval in Claude Code

> Discover subagent orchestration with iterative retrieval in Claude Code. Learn how subagents refine context through a four-phase loop for efficient codebase exploration.

- Repository: [Affaan Mustafa/everything-claude-code](https://github.com/affaan-m/everything-claude-code)
- Tags: deep-dive
- Published: 2026-03-20

---

**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`](https://github.com/affaan-m/everything-claude-code/blob/main/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`](https://github.com/affaan-m/everything-claude-code/blob/main/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`](https://github.com/affaan-m/everything-claude-code/blob/main/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:**

```markdown
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:**

```javascript
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:**

```json
{
  "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`](https://github.com/affaan-m/everything-claude-code/blob/main/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`](https://github.com/affaan-m/everything-claude-code/blob/main/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`](https://github.com/affaan-m/everything-claude-code/blob/main/AGENTS.md).
- The **iterative retrieval** skill runs a four-phase loop (DISPATCH → EVALUATE → REFINE → LOOP) specified in [`skills/iterative-retrieval/SKILL.md`](https://github.com/affaan-m/everything-claude-code/blob/main/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`](https://github.com/affaan-m/everything-claude-code/blob/main/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`](https://github.com/affaan-m/everything-claude-code/blob/main/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.