# Subagents

A subagent is a separate agent loop with its own context and tools that takes on one branch of work and returns a summary.

> A subagent is a separate agent loop, started by the main agent, with its own context and tools. It does one piece of work and returns only a summary.

Source: https://ai-sw-factory.mellicci.dev/fundamentals/subagents

**Diagram:** The main agent delegates a branch of work; each subagent works in its own context and returns only a summary.

- Main agent — goal, plan, summaries
- → delegate
- Separate contexts:
  - Subagent A — own context and tools
  - Subagent B — read-only reviewer
- → summary only
- Main context — grows by a summary

A subagent is a second agent loop that the main agent starts for a specific job. It gets its own context window, its own instructions and, often, a narrower set of tools. When it finishes, only its final summary returns to the main context, so the main context grows by a summary rather than by all the work behind it. The main loop treats the delegation much like a tool call.

Two properties matter. **Isolation** keeps noisy work, such as reading thirty files, out of the main window. **Specialisation** lets you give the subagent a focused role and fewer permissions, such as a reviewer that can read but not write.

## Why it exists

In one long session, the context fills with search results, logs and file dumps that mattered for one step and never again. The model has less room for the task and tends to lose earlier instructions. Also, a single agent that both writes and reviews its own change carries its own assumptions into the review.

## How it works

**Diagram:** The main agent hands a brief to a saved or ad-hoc helper, which runs its own loop under inherited limits and returns a summary, while the main agent waits or keeps working.

- Who does the work:
  - Saved specialist — a file with name, description, instructions
  - Ad-hoc helper — general-purpose, briefed on the spot
- → brief, no history
- Subagent · own context (permissions, sandbox):
  - Runs its loop — tools and model inherited or narrowed
- → summary
- Main agent:
  - Foreground — waits for the result
  - Background — keeps working, collects later

Delegation costs extra model calls and time, and anything the summary leaves out is lost to the
main agent.

## Saved or ad hoc

Subagents appear in two ways, and harnesses often support both:

- **Ad hoc.** The main agent starts a general-purpose helper and writes its brief on the spot. No
  file is involved.
- **Saved specialists.** You store a definition in a file: a name, a description of when to use it,
  its instructions, and optionally its tools and model. As with [skills](https://ai-sw-factory.mellicci.dev/fundamentals/skills), the
  main agent reads the descriptions and picks a specialist when a task fits. You can also name one
  directly in a prompt or an [instruction file](https://ai-sw-factory.mellicci.dev/fundamentals/instruction-files), for example "have
  the reviewer check this change".

## What carries over

A subagent does **not** see the main conversation. It gets its own instructions and the brief. The
table shows what else it gets.

| | Typically | Variations to look for |
|---|---|---|
| **Permissions and sandbox** | Inherited from the main session | Some harnesses let a definition tighten them, for example read-only |
| **Tools** | All tools the main agent has, including MCP tools | A definition can list or exclude tools; some harnesses give background helpers fewer tools |
| **Model** | The main agent's model | Some harnesses let a definition, a config default or the spawn request pick another model, for example a cheaper one for search or a different one for a second opinion |
| **Blocking** | Differs by agent and mode | The main agent waits for the result (foreground), or keeps working and collects results later (background, often several in parallel) |

The layer 3 pages list exactly what each agent inherits and what can be overridden.

## Use it when

- A subtask produces lots of output but needs a short answer (search, log analysis, review).
- You want a role with restricted tools, such as read-only review.
- Independent subtasks can run separately.

## Use something else when

- The task is small and needs the main context → keep it in the main loop; see [How coding agents work](https://ai-sw-factory.mellicci.dev/fundamentals/how-coding-agents-work)
- You only need to add know-how → [Skills](https://ai-sw-factory.mellicci.dev/fundamentals/skills)
- You need an enforced guarantee, not a second opinion → [Hooks](https://ai-sw-factory.mellicci.dev/fundamentals/hooks)
- You need external data → [MCP](https://ai-sw-factory.mellicci.dev/fundamentals/mcp)

## Key terms

- **Subagent** — a separate loop with its own context and tools.
- **Context isolation** — intermediate output stays out of the main window.
- **Tool restriction** — a narrowed tool set for a role.
- **Delegation** — handing off a task, receiving a summary.