Skip to main content

​
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

1

Main agent reads your request

The main agent (orchestrator) reads your task and decides it can be broken into independent subtasks.
2

Spawns subagents

For each subtask, it spawns a subagent with a specific goal, context, and toolset.
3

Subagents work in isolation

Each subagent works in its own conversation and terminal session — they can’t see each other or your main conversation.
4

Results returned

When a subagent finishes, its final summary re-enters the orchestrator’s conversation as a new message.
5

Orchestrator synthesizes

The orchestrator combines all subagent results into a final answer for you.
The subagents run in the background. You and the orchestrator keep working while they run.

​
Good vs. bad delegation candidates

Good candidates

  • 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

Poor candidates

  • 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

​
Example

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

​
Configuration

Configure in Settings → Headmaster’s Library → Advanced → Delegation:

​
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.

The Council

Structured multi-perspective deliberation using specialists — complements delegation.

Modes

Subagents inherit the parent’s mode — understand what that means in each mode.