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

# Sub-agents

> How a run hands self-contained subtasks to bounded sub-agents, what each sub-agent may do, and how its report comes back.

A long task often splits into parts that do not depend on each other: survey three directories, check four files, draft two sections. A run can hand such parts to sub-agents. A sub-agent is a fresh run with its own context that works one subtask to the end and returns a short report, so the intermediate tool output stays out of the parent's context.

## The two tools

The model decides when to delegate, through two native tools:

| Tool | What it does |
| - | - |
| `run_subagent` | Runs one subtask in a fresh sub-agent and returns its report. |
| `run_subagents` | Runs up to four subtasks at the same time and returns one report each. |

Each task has these fields:

| Field | Required | Meaning |
| - | - | - |
| `goal` | yes | What the sub-agent should do, stated completely. The sub-agent does not see the parent's conversation. |
| `context` | no | Background the sub-agent needs: where to look, constraints, earlier decisions. |
| `deliverable` | no | The shape of the report to return (a list, a summary, a diff). |
| `read_paths` | no | Paths this task may read, at most 64. |
| `write_paths` | no | Paths this task may write, at most 64. |

You ask for delegation in plain words. The model fills in the tasks:

```text theme={null}
Use run_subagents to run these two independent subtasks in parallel, do not do them yourself: (1) create alpha.txt containing exactly ALPHA; (2) create beta.txt containing exactly BETA. When both reports are back, answer with one line per subtask: label, status, model.
```

## Scopes

`read_paths` and `write_paths` narrow a sub-agent. They never widen it: a declared path outside what the parent may reach is refused. For `run_subagents`, tasks whose write paths overlap another task's read or write paths are rejected before any sub-agent starts, and a task that declares no scope runs on its own instead of beside the others.

A sub-agent whose only write path is a single file has no working directory. It can write that file when its goal names it by absolute path, and a relative name is refused. To fan out file edits, give each task its own file by absolute path in both `write_paths` and `goal`.

## Rights of a sub-agent

What a sub-agent may do depends on who started the parent run.

### A person's sub-agents

Every person may use sub-agents (see [Persons](https://stampede.autonomousorganizations.ai/persons/overview.md)). A person's sub-agent has the same rights as its person:

* the same program list for `run_command` (the person's list, or any program for a `maintainer` or `free` person),
* the same MCP tools, from the same running servers,
* the same file roots, and the same refusals for the configuration tools.

Each call is decided through the person's policy, so a sub-agent can do nothing its person could not. A `research` person's sub-agent is offered `run_command` and refused it, as its person is. A sub-agent that names no scope starts with its person's roots and workspace.

A person's sub-agent runs commands in the foreground only, with the same `timeout_secs` limit as any command (see [Budgets and timeouts](https://stampede.autonomousorganizations.ai/models/limits.md)). It is not offered `start_command`, `command_output`, `kill_command`, `inspect_lost_job` or `terminate_lost_job`, because a background job would end with the sub-agent. A person's sub-agents run one at a time.

A declared scope narrows the sub-agent's file tools and the directory its commands start in. It does not bound what a program the sub-agent runs may read or write.

### Runs without a person

A sub-agent started from the operator's own console turn or a headless `stampede agent` run reads where its parent reads and writes only inside a scope it declared. It runs no command and no MCP tool. A task that needs to write must say where in `write_paths`.

### Headless runs

A run with nobody at the keyboard (`stampede agent`, or `stampede chat` with piped input) may delegate only when the top-level key `unattended_delegation` is set in `~/.stampede/config.toml`:

```toml theme={null}
unattended_delegation = true

[tools]
full_access = false
```

Put the key above the first table header; under a table it is refused at load. It authorizes `run_subagent` and `run_subagents` and nothing else. `full_access = true` does not imply it. A person's run (a gateway request, mail, a schedule fire, a request from a paired machine) follows the person's policy, and this key does not apply to it.

## Limits

| Limit | Value |
| - | - |
| Tasks in one `run_subagents` call | 4 |
| Sub-agents in one turn, in total | 12 |
| Sub-agents running at the same time | 4 |
| Nesting | A sub-agent may delegate once more; its own sub-agents cannot. |

The parent and all of its sub-agents share one budget: the model calls and input tokens of the turn (`turn_model_calls`, `turn_input_tokens`) and one wall-clock deadline. A sub-agent cannot be resumed on its own, apart from its parent.

## Model

Every sub-agent runs on the profile with `role = "subagent"` in `config.toml`, or on the parent's model when no profile has that role. A cheaper model is a common choice:

```toml theme={null}
default = "sonnet"

[models.sonnet]
role = "primary"
provider = "anthropic"
model = "claude-sonnet-5"
key_env = "ANTHROPIC_API_KEY"

[models.haiku]
role = "subagent"
provider = "anthropic"
model = "claude-haiku-4-5"
key_env = "ANTHROPIC_API_KEY"
```

`stampede agent` drives its parent on the profile with `role = "orchestrator"` when one exists. Roles are described in [Providers and models](https://stampede.autonomousorganizations.ai/models/providers.md).

## Reports

Each sub-agent returns a report with a label, a status, a summary and its token usage. The status is one of `completed`, `partial`, `cancelled`, `timed out`, `needs reconciliation` or `failed`. The report names the configured model and, when the provider reports it, the model that answered.

The console prints one line per sub-agent as it finishes:

```text theme={null}
sub #1 completed · claude-haiku-4-5 (configured) · 2 iters · 10309 tok
```

`(configured)` marks the model from the profile. `(actual)` marks the model the provider said answered, which a session provider can report.

Every sub-agent is a run of its own in the run store, linked to its parent:

```bash theme={null}
stampede runs list
stampede runs show RUN_ID
```

`runs list` prints one line per run with its status, provider and model. `runs show` on the parent lists the `run_subagents` call with its outcome, or the gate that refused it. `runs show` on a sub-agent prints a `child access:` line with the number of read and write roots it ran with.


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