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)
max_rounds     = 0     # per-subtask model-round cap (0 = unbounded)

Child rounds are unlimited by default; existing explicit positive budgets are preserved. Set [subagent] max_rounds = 0 or ATOMCODE_SUBAGENT_MAX_ROUNDS=0 to remove an old 200-round limit. Positive budgets allow at most one extra text-only closing request. Concurrency, cancellation and repetition guards remain independent. External Codex/Claude agents retain their own execution policies.

Key	Default	Meaning
`max_concurrent`	3	How many subagents run in parallel
`max_rounds`	0	Model-round high-water mark per subtask; `0` = unbounded

Environment overrides: ATOMCODE_SUBAGENT_MAX_ROUNDS take precedence over the config values.

Custom team roles

The team (team) picks members by role. Besides the built-in roles you can define your own as Markdown files in either of:

<project>/.atomcode/agents/<role>.md — this project only;
~/.atomcode/agents/<role>.md — every project.

The file name (without .md) is the role's name. A file named like a built-in role replaces it; when both directories have a file of the same name, the one in your home directory wins.

A role file is a header of fields between --- lines, then the role's instructions:

---
permission: explore      # required: explore (looks, changes nothing) | worker (may edit files and run commands)
difficulty: hard         # required: simple (the fast model) | hard (the strong one)
effort: high             # optional: low | medium | high | xhigh | max
model: glm-4.6           # optional: a model selection id, overriding difficulty
when: designing systems  # optional: one line on when to hand it work
tools: read_file, grep   # optional: limit its tools, chosen from what permission allows
---
You design. Read the existing code first, then propose a design and its trade-offs.

Field	Required	Values
`permission`	yes	`explore` (read-only investigation) or `worker` (scoped writes)
`difficulty`	yes	`simple` (fast model) or `hard` (strong model)
`effort`	no	`low` / `medium` / `high` / `xhigh` / `max`
`model`	no	A model selection id; without it, chosen by `difficulty`
`when`	no	One line on when to hand this role work
`tools`	no	Comma-separated tool names, a subset of what `permission` allows

Two things to note:

This permission is not the CLI's --permission-mode (plan / accept_edits / auto); they only share a name. This one decides whether the member may change anything; that one is how the whole session asks for approval.
This is not Claude Code's agent file format. name, description, allowed_tools and user_invocable are not read: the role's name is the file name, and its tools are limited with tools.

A role file that does not parse is skipped and the session starts anyway. You are told once per session which file was skipped and everything that is missing or wrong in it; a file named like a built-in role leaves the built-in in use.

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