Skip to main content
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: Each task has these fields: You ask for delegation in plain words. The model fills in the tasks:

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). 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). 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:
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

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:
stampede agent drives its parent on the profile with role = "orchestrator" when one exists. Roles are described in Providers and models.

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:
(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:
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.