> ## Documentation Index
> Fetch the complete documentation index at: https://ade-app.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Subagents

> Delegate work inside one provider, or hand it to another provider entirely — with the parent staying in charge.

A subagent is an agent another agent started. ADE supports two kinds, and they differ in who owns the orchestration:

| | **Provider-native** | **ADE child chat** |
| - | - | - |
| Started by | The provider's own subagent tool | `ade new chat`, or the parent's shell |
| Same provider? | Always | No — any of ADE's providers |
| Visible as | Nested transcript entries | A real Work session with its own row |
| Reports to parent | Provider-managed | ADE-managed wake and summary |
| Survives a client restart | Provider-dependent | Yes — it is a normal persisted chat |

Most work uses one kind. The interesting cases use both.

![Three subagents reporting back into one parent chat](https://mintcdn.com/ade-ac1c6011/m_EKJqJVzAE9PL2s/assets/readme/machines.gif?s=8893ab57ce98824249427e7163ea403b)

A Claude parent delegates to GPT, Claude Haiku, and DeepSeek at once; each child reports back into the parent.

## Provider-native subagents

Claude Code has its own subagent tool. Codex has its own delegation. When a provider starts one of these, ADE does not intercept it — it normalizes the activity into the transcript and preserves the parent/child relationship.

The result: nested tool activity you can expand, collapsed by default so a deep delegation does not bury the parent's work, and no second chat cluttering Work. This is the right choice for short, parallel research or a narrowly scoped edit.

When one of these subagents needs an approval, its card shows in the parent chat and names the subagent ("Explorer asks"). With several cards open, the composer lists who is waiting and for what, and the subagents panel marks a waiting subagent "needs you". The cards stay open through the default Stop and the end of the parent's turn, because the subagent keeps running; they close when that subagent ends or is stopped. **Accept all** on a subagent's card covers the whole chat. If ADE restarts while a subagent's question is open, the card closes and offers to send your answer to the main agent instead.

## ADE child chats

An ADE child is a full session — its own lane-scoped context, its own tools, its own permissions — that records the parent it came from. Any chat can start one:

```bash theme={null}
ade new chat --mode chat --lane auto --parent <session> --type subagent --prompt "Run the auth tests and report failures"
```

Two spawn types make the coordination contract explicit:

* **`subagent`** — the parent needs the result. The child wakes the parent when it finishes, with a bounded summary, and the parent can join, read, or review the work.
* **`peer`** — fire-and-forget. The child leaves a quiet completion note and never wakes the parent.

The child can run a **different provider and model** from the parent. That is the cross-product case: a Claude parent can hand a mechanical refactor to a fast model, visual review to a model with vision, and a second opinion to a different vendor — then reconcile all three.

> [!NOTE]
>
> The child is a normal agent, not a restricted helper. It gets the same runtime, tools, and permissions as any other chat in that lane. The spawn type is a coordination contract, not a permission ceiling.

## What the parent sees

* A **subagent panel** in Chat Info listing running and completed children.
* A **card in the transcript** for each child, with its status and latest summary.
* A **wake** when a `subagent` finishes, so the parent continues rather than polling.

Demoting a subagent to a peer is an explicit action — from the composer banner, the session menu, or `ade chat demote`. Demoting stops the report channel; promoting restores it while the parent still exists. A later dispatch from the parent promotes a peer back automatically.

## Choosing between them

| Situation | Use |
| - | - |
| Short parallel research inside one provider | Provider-native |
| Work that must survive a restart or be inspected on its own | ADE child |
| A different model or vendor should do it | ADE child |
| Fire-and-forget side task | ADE child with `--type peer` |
| Deep, provider-specific delegation the runtime optimizes | Provider-native |

> [!TIP]
>
> Give a subagent a narrow, verifiable job and tell it what to report. "Run the auth suite and list failures with file and line" produces a usable summary; "look into auth" produces a paragraph the parent has to re-check.

> [card] [Multi-agent setup](https://ade-app.dev/docs/guides/multi-agent-setup.md)
>
> A worked setup for running several agents together.

> [card] [Chat capabilities](https://ade-app.dev/docs/chat/capabilities.md)
>
> What each agent can do inside its lane.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.