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

# Subagent Delegation

> Spawn isolated subagents to work on tasks in parallel — each gets its own conversation, terminal, and toolset, returning only a final summary.

# Subagent Delegation

Headmaster can spawn isolated subagents to work on tasks in parallel. Each subagent gets its own conversation, terminal session, and toolset. Only the final summary is returned — intermediate tool results never pollute your main conversation.

***

## How it works

<Steps>
  <Step title="Main agent reads your request">
    The main agent (orchestrator) reads your task and decides it can be broken into independent subtasks.
  </Step>

  <Step title="Spawns subagents">
    For each subtask, it spawns a subagent with a specific goal, context, and toolset.
  </Step>

  <Step title="Subagents work in isolation">
    Each subagent works in its own conversation and terminal session — they can't see each other or your main conversation.
  </Step>

  <Step title="Results returned">
    When a subagent finishes, its final summary re-enters the orchestrator's conversation as a new message.
  </Step>

  <Step title="Orchestrator synthesizes">
    The orchestrator combines all subagent results into a final answer for you.
  </Step>
</Steps>

The subagents run in the background. You and the orchestrator keep working while they run.

***

## Good vs. bad delegation candidates

<CardGroup cols={2}>
  <Card title="Good candidates" icon="check">
    * **Independent research tasks** — researching multiple topics in parallel
    * **Parallel code reviews** — reviewing different parts of a codebase simultaneously
    * **Batch document generation** — creating multiple documents at once
    * **Multi-source data collection** — pulling data from multiple integrations simultaneously
  </Card>

  <Card title="Poor candidates" icon="x">
    * **Sequential tasks** — each step depends on the previous one
    * **Simple tasks** — a single tool call; delegation overhead exceeds the benefit
    * **Tasks needing user interaction** — subagents can't ask you questions; they work autonomously
  </Card>
</CardGroup>

***

## Example

```
Research the top 3 competing products to ours. For each one, find their pricing,
features, and recent reviews. Do all three in parallel.
```

The agent spawns 3 subagents — one per competitor — each doing its research independently. The orchestrator collects the 3 summaries and synthesizes a comparison.

***

## Subagent capabilities

Each subagent:

* 💬 Gets its own **conversation context** — it doesn't see your main conversation history.
* 🖥️ Gets its own **terminal session** — separate working directory and state.
* 🔧 Gets a **specified toolset** — you can restrict what tools the subagent can use.
* 🧬 **Inherits the parent's model** (unless overridden).
* 🚫 **Cannot delegate further** — subagents are leaf workers by default.
* 🤐 **Cannot ask the user questions** — they work autonomously and report back.
* 📋 Returns only a **final summary** — intermediate tool results stay in the subagent's context.

***

## Orchestrator mode

When you enable orchestrator subagents, they can spawn their own workers (two-level hierarchy: you → orchestrator → workers):

1. You give the orchestrator a task.
2. The orchestrator breaks it into subtasks and delegates each to a worker subagent.
3. Workers do the work and report back.
4. The orchestrator synthesizes and reports to you.

Deeper nesting can be enabled in advanced settings.

***

## Monitoring subagents

While subagents are running:

* 📊 You see a **delegation indicator** in the chat showing how many subagents are active.
* 👆 Click the indicator to see each subagent's status (running, completed, failed).
* 🔍 Expand a completed subagent's card to see its final summary.
* 💬 You can continue chatting with the orchestrator while subagents run.

***

## Delegation vs. multiple conversations

| Feature          | Delegation                    | Multiple conversations                     |
| ---------------- | ----------------------------- | ------------------------------------------ |
| Who decides      | The agent breaks the task     | You open separate chats                    |
| Context sharing  | Orchestrator sees summaries   | No sharing — fully isolated                |
| Parallelism      | Subagents run in background   | You switch between chats manually          |
| Result synthesis | Orchestrator combines results | You read each chat and synthesize yourself |
| Best for         | Parallel subtasks of one task | Independent unrelated tasks                |

***

## Configuration

Configure in **Settings → Headmaster's Library → Advanced → Delegation**:

| Setting                  | Default | What it controls                                            |
| ------------------------ | ------- | ----------------------------------------------------------- |
| Enable delegation        | On      | Whether the agent can spawn subagents                       |
| Max concurrent subagents | 5       | How many subagents can run at once                          |
| Max spawn depth          | 1       | Nesting levels (1 = no nesting, 2 = orchestrator → workers) |
| Subagent model           | Inherit | Which model subagents use                                   |
| Subagent toolsets        | Inherit | Which tools subagents can use                               |

***

## Safety

* Subagents run with the same terminal backend as the parent.
* Subagents inherit the parent's mode but can't ask for approvals — they run autonomously.
* All subagent actions are logged in the orchestrator's conversation transcript.
* The stop button kills all running subagents.

***

<CardGroup cols={2}>
  <Card title="The Council" icon="users" href="/the-council">
    Structured multi-perspective deliberation using specialists — complements delegation.
  </Card>

  <Card title="Modes" icon="sliders" href="/modes">
    Subagents inherit the parent's mode — understand what that means in each mode.
  </Card>
</CardGroup>