Subagents

When a task splits cleanly — parallel edits, mechanical repetition, or read-only investigation — the main agent can hand subtasks to short-lived subagents through the task tool. Each subagent runs in its own isolated context; the main agent keeps the cross-file reasoning and owns the final result. The task tool is on by default.

Two kinds of subagent

Type	What it can do
explore	Read-only investigation — reads and searches the codebase to answer a “where / how” question, then returns findings. Cannot edit files.
worker	Executes a tightly-specified change. Reads freely, but its writes are confined to a declared `scope`.

How they run

Subagents run in parallel, up to max_concurrent at a time, each in an isolated context.
Each subtask carries a difficulty: simple routes to your fast model, hard routes to your capable model — chosen by the capable_model rank across your configured providers. With a single provider, the subagent uses the current model.
The main agent reviews each result before continuing — a subagent proposes, the main agent decides.

Worker scope & safety

A worker subtask must declare a scope: a list of working-directory-relative globs it is allowed to write, e.g. ["src/auth/**", "Cargo.toml"]. This is enforced, not advisory:

Writes outside the scope (edit_file, write_file, search_replace) are hard-denied — not prompted — by the WorkerScopeGate.
Reads and bash are not restricted by scope.
A dispatch that contains any worker is treated as a Risky action, so it goes through approval first, with the scopes shown.
When several workers run at once, give them non-overlapping scopes so they cannot clobber each other.

Configuration

Tune the subagent pool in ~/.atomcode/config.toml:

[subagent]
max_concurrent = 3     # parallel subagents at once (min 1)
timeout_secs   = 900   # per-subtask wall-clock limit, seconds (min 30)
max_rounds     = 200   # per-subtask model-round cap (0 = unbounded)

Key	Default	Meaning
`max_concurrent`	3	How many subagents run in parallel
`timeout_secs`	900	Wall-clock timeout per subtask (floored to 30s)
`max_rounds`	200	Model-round high-water mark per subtask; `0` = unbounded

Environment overrides: ATOMCODE_SUBAGENT_TIMEOUT and ATOMCODE_SUBAGENT_MAX_ROUNDS take precedence over the config values.

Turning it off

The task tool is enabled by default. To remove it entirely, set:

ATOMCODE_SUBAGENT=0 atomcode

Any of 0, false, or off disables it; unset (or any other value) leaves it on.

Built-in Tools — the tools a subagent has access to
Permissions & Approvals — why a worker dispatch asks for approval
Configuration — the full config.toml reference