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 amaintainerorfreeperson), - the same MCP tools, from the same running servers,
- the same file roots, and the same refusals for the configuration tools.
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 headlessstampede 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:
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 withrole = "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 ofcompleted, 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.