Skip to main content

​
Subagents

Atomic bundles @bastani/subagents for bounded specialist work in separate context, with the parent in control. Use one agent or parallel agents to locate code, analyze behavior, research references, reproduce failures, or simplify code when isolation or specialist expertise helps. Keep interactive, exploratory, conceptual, and conversation-led work inline when direct user steering is more useful. Keep immediately blocking work local unless specialist expertise, context isolation, or an explicit delegation request makes a child worthwhile. Delegate independent work you can overlap with your next steps, then continue without duplicating the child’s task. Foreground observation is available when you need a specialist’s result next. Otherwise, rely on completion notices rather than repeated short waits or status polls. Wait when the result becomes a dependency. You do not need to install anything separately when you use @bastani/atomic. Background subagents are supported. See Background tasks for launch examples, the below-prompt status indicator, /tasks, shell output, cancellation, and completion notices.

​
Where to go next

Subagents are focused child agents you delegate bounded work to. Read this page for natural-language use and execution behavior, then continue:

​
Start with natural language

Ask Atomic to coordinate subagents in plain language:
Atomic decides whether delegation adds value, which specialist fits each bounded part, and whether the work should run as a single child, parallel group, or forked-context run. Multiple steps, files, tests, validation, or parallelism alone do not require a workflow; clearly delegated long-running autonomous work that needs durable stages, checkpoints, resumability, HIL, gates, retries, or loops is usually better served by a workflow.

​
Browse agents

Open /agents to browse project, user, and built-in agents:
  • Type to filter by name, description, or source. /agents <query> starts with a filter.
  • Use arrows to select an agent and Enter to inspect its description, model and fallbacks, tools, definition path, and system prompt.
  • Press Escape to return to the catalog, then to chat.
Browsing is read-only and never launches an agent. The catalog is navigation, not an approval prompt. Leaving it open does not mark Herdr blocked or hide active agent work; separate user-decision prompts still report their normal waits. The catalog uses the same effective discovery rules as execution, so overridden definitions and disabled agents are not offered as separate launchable choices. Ask Atomic to create or modify an agent; the catalog does not change configuration.

​
Let Atomic choose the child model

All builtin subagents default to model: "auto". Atomic selects a model and reasoning effort from your available catalog using its shipped evaluation guidance before launching each child, favouring cheaper models for exploration and routine implementation and stronger ones for review and verification. You can also set auto on a custom agent or call. A concrete per-call model overrides the builtin default. Custom agents with no model keep their existing inheritance. See Automatic model selection for configuration and failure handling.

​
Subagent execution is non-interactive

Supported subagent launches start immediately without opening a preview/editor prompt or waiting for terminal input. This applies to single, parallel, forked, fanout, and prompt-template execution. Ask any necessary questions in the parent conversation before delegating. Prompt-template delegation comes from the separately installed pi-prompt-template-model extension, whose requestDelegatedRun emits prompt-template:subagent:request. If that caller must survive an extension reload, import registerPromptTemplateBridgeRequestSettlement from @bastani/subagents, register it before the emit, and unregister it from the normal response, cancellation, or abort path. The hook rejects the caller only when the old bridge drops a stale response emit; normal completion still arrives through prompt-template:subagent:response. Atomic cannot register this opt-in for an out-of-tree emitter. Subagents now run and return their results directly. Atomic does not infer acceptance gates from prompt wording, inject acceptance-report instructions into child prompts, parse or strip acceptance-report blocks, or reject completed child runs because changed-file, test, or review evidence is missing. Put any evidence or validation requirements directly in the task text you give the parent or child agent.

​
Owner-bound task observation

Runtime-created session contexts bind single launches to their actual session or workflow-stage owner. Choose observation behavior with wait:
  • Omitted wait returns an admitted observation with reason default-background.
  • wait: {kind: "background"} uses reason explicit.
  • wait: {kind: "foreground", budgetMs: 30000} opts into foreground-first observation. The omitted foreground budget is 30000 ms.
When you issue several single-agent calls in one turn, each keeps its own wait policy and returns only its own task result. Background completions appear as visible notices and notify the parent agent, including in workflow-stage chats receiving other messages. These calls share the concurrency limit, or the configured subagent parallel limit when omitted, even when their wait policies differ. A background receipt or an expired foreground observation does not free a running child’s slot; queued children start when execution capacity becomes available. Use subagent({action: "wait", id: taskId}) to observe an existing task in the same owner without restarting it. It uses the owner’s observation budget unless explicitly overridden. When a task has settled, the launch result, action: "wait", and action: "status" show its output after the task record: up to 16 KB of text, a Full output: path to a private copy of the complete result, and a Requested output: line naming the output file you asked for (background runs included). The private copies live in a temporary directory readable only by you and are removed when Atomic exits. With outputMode: "file-only" the text is only the saved-file reference, and the private copy holds the file’s contents. A child that stops to ask a question through contact_supervisor settles with the question and a ready-to-run follow-up call in this output. The agent may choose foreground-first or background observation for each authorized call without asking the user merely to select a mode. When a foreground observation expires, the returned task is still running. Wait for terminal completion before using its result in dependent work. See Choosing how long to wait for shell and subagent defaults and the separate execution-timeout behavior. User steering or an incoming Intercom ask/send admitted to the waiting parent releases its active subagent observations, including both foreground launches and action: "wait". This applies to main chat and live workflow-stage chat. The parent can handle the queued message and reply without cancelling the child, closing its owner, or interrupting another owner’s waits. User input yields with reason input-needed; Intercom coordination yields with reason intercom-coordination. The original task can be observed again after handling the message. An Intercom yield keeps the execution alive, including queued parallel siblings. Completion appears in the owning chat with the outcome, error, and response excerpt. Unbound SDK callers retain their existing result fields. Durable ctx.tool callbacks wait for tasks admitted inside their callback before checkpointing, even when the launching observation yielded. Session lifetime closure cancels session-owned work; stage generation closure, not pane detach or fallback session replacement, owns stage tasks.

​
Supervisor coordination

Every builtin specialist includes intercom for live coordination, including read-only researchers and locators. debugger and worker also declare contact_supervisor; prefer it for supervisor requests when available. Explicit parent tool allowlists, exclusions, noTools, and disabled Intercom still apply—builtin declarations do not override caller restrictions. In a parallel run, intercom.ask, contact_supervisor({ reason: "need_decision" }), and interview_request wait only in the requesting child. The supervisor answers with ordinary intercom({ action: "reply", message: "..." }); use pending and replyTo to select the exact question when several asks are pending. The correlated reply returns to the same child execution, with its context and run identity intact. Do not relaunch the requester or its siblings to deliver an answer. intercom.send and contact_supervisor progress updates return after delivery without waiting for a reply. An exact-child Intercom handshake can release the parallel call’s foreground observations so the supervisor can handle the message. This is not execution cancellation: active siblings keep running, queued siblings start once capacity is available, and worktrees stay owned until their children exit. Background calls use the same communication path without needing to release an observation. To update a working child, use ordinary Intercom send or ask with its exact connected name or full session ID from intercom list. An admitted child registers with Intercom when its session starts, so it is listed and reachable while it works even if it never calls Intercom itself. Foreground and background children treat it as a priority interrupt: the child’s current model call or cancellable tool is cancelled and the message is handled next in the same child execution, without relaunching its task or repeating the original prompt. Tools that ignore cancellation finish first, and completed side effects are kept. Multiple updates stay in arrival order. A reply to an incoming ask uses ordinary intercom.reply; this does not change the single-child parent-targeted handoff described below. Run control (pause, quit) stops only the selected child, and it stays resumable. Explicit batch cancellation and workflow-stage closure stop the intended owned children for good, including pending reply waits. Closing or switching away from a session also stops its children, but they stay resumable, as described next. A late or duplicate reply cannot revive a terminal child. Ordinary Intercom group restrictions and the authorized cross-group contact_supervisor route are unchanged. If Atomic exits or crashes while background subagents are still running, they come back when you reopen the session, or continue the workflow whose stage launched them: each unfinished child is relaunched from its own saved session with a continuation prompt. The same applies when you switch away from the session with /new, /resume to another session, or /fork: its running children stay resumable and are restored when you reopen it. A restored child first receives the steering and follow-up messages it had queued and not read, once, in order. A restored child keeps its Intercom name and group and gets a fresh supervisor authorization, so you can keep messaging it. It continues on its own model and thinking level, not on ones you switched to since, and runs on the agent definition it was launched with, even when a project agent of the same name would now shadow it, and a child launched with context: "fork" keeps its Intercom bridge instructions under intercomBridge.mode: "fork-only". Messages sent to it by any session in its group wait for it, from the moment the reopened session starts, or, for a workflow stage’s subagent, from the moment the run becomes addressable, until it has been restored; see Intercom operations. Only children that were still running are relaunched automatically; a child that finished, was paused or quit, or was cancelled for good stays as it was, and you can continue a resumable one with resume. Only the session that launched a child restores it: a fork of that session (/fork, atomic --fork) copies the child’s record but never relaunches or reports it. If a child cannot be restored, for example because its session file or agent definition is gone, the agent gets a notice that it is gone. That notice is given once: the child is then recorded as gone in the session, so later restarts neither retry the restoration nor repeat the notice. Completed, failed, interrupted, and cancelled noninteractive children cannot answer new Intercom asks, even when their retained registration still says idle. Such asks fail immediately with an explicit terminal-child error; an admitted ask also fails if its child terminates before replying. For follow-up work, resume a resumable child or launch a fresh child with the required context. This does not restrict live interactive idle sessions or workflow-stage post-mortem conversations, and does not change send delivery semantics.

​
Peer coordination

Children do not have to route everything through the supervisor. Children launched in one parallel set, or with the same explicit group, share an Intercom group, and children launched by a workflow stage inherit that stage’s invocation group. A child can run intercom({ action: "list" }) to see live siblings and use ordinary send or ask with them directly: a locator hands file paths to the analyzer, two writers agree who owns which files or who runs the shared test suite, a debugger reuses a sibling’s verified reproduction, or one reviewer challenges another’s finding with evidence before each returns its own verdict. contact_supervisor stays reserved for supervisor decisions, and ordinary Intercom group restrictions still apply. Peers do not coordinate spontaneously. When related work runs in parallel, name the peers and the expected exchange in each task prompt, keep it bounded, and require each child to return its own complete result rather than deferring to a sibling. Scope, product, and architecture decisions still go to the supervisor. Peer asks and one blocking supervisor request can wait concurrently in the same child; mutual asks work as long as both children process inbound work. The intercom skill (/skill:intercom) has copy-paste peer patterns.

​
Single-child handoff

A claimed parent-targeted blocking request ends a single child and returns its question, attachments, agent identity, and [TASK_CONTEXT] through the parent’s subagent call. Start a fresh child with the answer and handoff. In parallel runs and collected sibling launches, the requesting child instead stays alive and continues its ongoing execution after receiving the supervisor’s reply. The handoff explicitly tells the parent to start a fresh child with a normal launch such as subagent({ agent: "worker", task: "[TASK_CONTEXT] ... Continue with this supervisor answer: ..." }). The new child receives a new run identity.

​
Foreground supervisor coordination

See Supervisor coordination for parallel requests and Single-child handoff for claimed single-child requests.

​
Migration from acceptance gates

If you have older subagent calls or custom agents that used the removed gate fields:
  • Remove acceptance properties from subagent() calls, task entries, and parallel task items. Atomic no longer reads these fields.
  • Remove completionGuard: false from agent frontmatter and custom agent definitions. The no-mutation completion guard no longer exists, so the override has no effect and management rewrites strip it.
  • Move validation, command, evidence, review, or residual-risk requirements into the natural-language task text passed to the parent or child agent.

​
Bundled agents

Atomic currently bundles these agents from @bastani/subagents: Every bundled agent uses model: "auto", without a pinned fallback chain. To pin a role, set subagents.agentOverrides.<name>.model in user or project settings, or pass a concrete model on one call. To restrict automatic choices, use modelConstraints, for example { "allowedEfforts": ["high"] }. Routing and execution fallback do not change your main-chat model. Read-oriented agents inspect and report. debugger, code-simplifier, and worker can edit files, so give them an explicit scope and validation target. The debugger should apply and validate an in-scope fix, not stop at a proposed patch.

​
Review compositions

Atomic does not bundle a single generic review agent. Instead, compose specialists with distinct angles and let the parent session synthesize their findings before applying any fix. Common review angles: Example request:
Compose those review and research passes with the subagent tool. Treat them as parent-side recipes, not bundled slash commands.

​
Foreground work and control

Explicit foreground-first observations wait for the child until it settles or the observation yields. The child continues after a yield; owner-bound calls without wait use background observation by default. Natural-language examples:
Tool examples:
Use run control to stop, hold, or continue a child. Cancelling the parent turn stops a running foreground child. This is terminal cancellation, not completion or a retryable failure. Atomic returns labelled partial findings from the run’s modified progress.md, the last assistant text, or a cancellation notice with available artifact paths. Parallel siblings do not each receive duplicate copies of shared progress. Use the returned task or run ID for status and run control. Expand status cards to see every child, full paths, task, parent, and any recorded termination cause; status inspection does not start work. When a workflow stage closes for good (the stage finished, or its run ended or was cancelled), it cancels its remaining children and suppresses their late findings. Every subagent it launched then becomes terminal, whether it was running, paused, quit, completed, or failed: resume on one returns an error that says why. Already-submitted Intercom sends are not retracted, so a transport acknowledgement is not proof that a finding appeared in parent chat. Deliberate post-mortem stage chat remains separate. Live progress and completed results show each step’s resolved model ID and effective reasoning level, including after a model fallback; parallel steps keep their metadata separate. Fast inference is part of the model ID, so an agent pinned to a fast variant renders it directly — codebase-analyzer (openai-codex/gpt-5.6-sol-fast · thinking medium) — with no separate fast badge. Select fast inference in an agent definition’s model and fallback model fields, for example openai-codex/gpt-5.6-sol-fast:medium; normal and fast IDs stay distinct fallback candidates and distinct records. See Providers for which providers publish fast variants and what each one sends upstream. Owner-task rows, status cards, foreground result receipts, and background completion cards retain these settings too. Background launch receipts include the concrete model and known, capability-clamped reasoning level selected at admission, including inherited defaults, without waiting for child session startup. A launch receipt remains a snapshot; inspect /tasks for later session resolution or fallback changes. Settings that are not yet resolved remain unavailable rather than being guessed from the parent’s display. Completion metadata is persisted with the notification so it remains visible when replaying chat history.

​
Run control

The subagent tool has the same run-control actions as the workflow tool: pause, resume, and quit. id accepts the child id (<runId>:<index>), its task id, its Intercom name, or the run id of a run that launched one child.
  • pause stops the child’s current turn and holds its queued steering and follow-ups in place; resume delivers them once, in order, before its own message. Intercom messages sent to a paused child wait until you resume it, as long as the same Atomic process keeps running.
  • quit stops the child gracefully, including a child that is already paused, by you or with its workflow stage. A quit child stays resumable while the session or workflow stage that launched it can still resume it; once that workflow stage closes for good, the child becomes terminal like every other child of the stage.
  • A parallel child still waiting for a free slot behind its concurrency limit can be paused or quit too, by id or with all: true. It then does not start when a slot frees; resume starts it on its original task, with message, if given, added after the task. This also works after Atomic restarts: the child starts as a new launch under the same child id, Intercom name, and group, with its original agent, task, working directory or worktree, model, thinking level, and skills. A child that inherited your model and thinking level keeps the ones you had when you launched it, even if you have switched since; if that model is no longer available, resume reports the child as gone instead of starting it on your current model. A child launched with context: "fork" starts on the copy of your conversation it was launched with; if that copy no longer exists, resume reports the child as gone instead of starting it without your conversation. A child that was still waiting for a slot when Atomic exited starts the same way when its session reopens.
  • A resumed child of a parallel run, queued or not, waits for a free slot under that run’s concurrency limit, as its original launch did. A paused or quit child holds no slot.
  • resume continues the child from its own saved session, under the same child id, Intercom name, and group, with fresh supervisor authorization. For a paused, quit, or interrupted child, message is delivered once as its next prompt, and after replying the child continues where it left off. For a completed or failed child, message is one fresh prompt in the same session, with nothing queued after it. Without message, the child is asked to continue where it left off, or to stop if its task is finished; this works for completed and failed children too. all: true is not accepted for resume.
Paused, quit, interrupted, completed, and failed children are resumable, including a paused child that you later quit. So are children whose session you closed or switched away from, whether Atomic exited or crashed, or you used /new, /resume to another session, or /fork; they are restored when that session reopens. Subagents of a workflow stage that was paused or quit, including by Atomic exiting or a session switch, stay resumable too: the stage agent can continue them with resume, and resuming the run after Atomic restarts restores them with the stage. These children are terminal, and resume returns an error that says why:
  • Killed: cancelled for good by an owner or batch cancellation. This includes stopping the subagent from /tasks and the removed kill action.
  • Stage ended: the workflow stage that launched it finished, or its run ended or was cancelled. This covers every subagent of that stage, including ones you paused or quit, and also a run killed while it waited, after a restart, for /workflow resume. The error reads <agent> (<child-id>, <intercom-name>) is terminal and cannot be resumed: its workflow stage ended (the stage finished, or its run ended or was cancelled). Launch a fresh subagent if its work is still needed.
  • Gone: it could not be restored after a restart.
Resume also refuses a child that is still running (pause or quit it first) and an id this session did not launch. A resume that fails, for example because the child’s agent is no longer defined, keeps its worktree: true worktree with its changes and branch. An SDK session without a task host runs its subagents directly and records them in its session the same way, so pause, resume (with or without message, queued messages included) and quit work there by id and with all: true, also after the session is reopened. A child resumed there runs in the background, and its result arrives as a completion notice. Closing the session stops such a child; reopening the session relaunches it automatically, and the messages it had queued and not read are delivered once, in order. For a terminal child, launch a fresh child with an explicit context handoff. The kill action was removed, and interrupt before it. Calls with either are rejected with an error that names quit as the replacement. For kill it reads:
Each background subagent launch card shows the child’s latest state, including after you reopen the session with /resume or atomic --session <id>, and when you view a workflow stage’s transcript: Running in background, Paused (resumable), Quit (resumable), Interrupted (resumable), Paused with its workflow stage (resumable), Completed, Failed, Terminal · killed, Terminal · gone after a restart, or Terminal · its workflow stage ended. A resumed child continues in its original launch card, marked · resumed, and the resume call’s own card says the child continues in its original launch card. Expand a launch card to see the end of the child’s saved transcript. Earlier pause, resume, and quit calls show their results, and rejected calls show their error.

​
Task inspection

Hosts with an owner task store expose /tasks and /tasks <id> for background agents and shells, including their retained terminal results. Foreground-only work is excluded. Enter opens detail; arrows select an explicit action. Cancel asks for confirmation of the selected task. Terminal tasks retain transcript inspection but omit foreground, cancellation, and stdin actions. Escape returns from detail or stdin before returning to the composer. Cancelling a subagent from /tasks stops it for good: its row shows Killed (non-resumable) and resume refuses it. To stop a child and keep it resumable, use subagent({ action: "quit", id }) or pause instead. /tasks appears in slash-command autocomplete. The inspector groups agents and shells with counts, status symbols, and a highlighted selection. Task descriptions lead; the selected row shows secondary activity and tool counts. The header and footer remain visible in ordinary terminal sizes, with a compact fallback for short terminals. The list opens as a compact inline widget, like the /workflow connect picker. Detail, transcript, input, and stop-confirmation pages are fullscreen; returning to the list preserves selection. Every agent row includes its resolved model and reasoning level when available, including completed background tasks. While /tasks or its fullscreen transcript/detail view is active, Escape navigates back or closes that view; it does not cancel a pending ask_user_question. The questionnaire waits out of the way and returns with its selection intact after task navigation closes. With no task view active, Escape cancels the questionnaire normally. In the default isolated CLI, background subagents continue running after their launch observation returns. The engine publishes a compact task-status indicator below the prompt box, without task rows or activity previews. Run /tasks to open the list and inspect individual tasks; task updates never open it automatically. Completed tasks leave the live indicator and remain available in completion cards and /tasks. Inspecting does not restart work or create a second task owner. Top-level model bash commands use this owner on POSIX and native Windows; native Windows PowerShell is also owner-bound. Commands inside subagent sessions retain their existing execution path. See Background shells for platform support and the separate execution timeout. Transcript inspection uses a dedicated scrolling view with pinned identity, position, and controls. Retained child messages use the normal message renderers, excluding hidden reasoning and inline images. Missing capture is reported as Transcript unavailable; metrics never substitute for missing messages. Arrows scroll, PageUp/PageDown moves one viewport, and PageUp at the top loads earlier retained history. Home/End jumps within loaded history. Live transcripts refresh streaming text and tool results without reopening. Earlier pages remain anchored, and leaving the view does not affect execution. Detail views pin task identity, state, available metrics, and the selected action while PageUp/PageDown scrolls the body. Recent activity shows up to five retained tool actions; errors and input requests appear explicitly. Left returns to the previous view. x requests cancellation without bypassing confirmation or configured task bindings. Shell inspection shows a bounded output tail with omission markers. After a confirmed x stop settles, the owning chat receives a visible stopped notification and the parent model receives the stop context, even if the child returns no final message. Repeated stops do not duplicate notifications or replace an already-recorded terminal result. Closing the owner still suppresses late completion delivery.

​
Orchestrator model and group policy

Atomic applies the same delegation policy to any parent chat or workflow stage that orchestrates subagents. A named agent uses the model and fallback sequence declared by its agent definition, so the orchestrator normally omits the subagent tool’s explicit model argument. An override needs either the user’s exact model request or a documented task-specific reason recorded before launch; model diversity alone is not enough. If an agent declares no model or fallback policy, the orchestrator consults the role guidance in Model selection and the measured per-evaluation scores in Evals, then calls workflow({ action: "models" }) when that tool is available. It may pin only a returned fullId and may add a thinking suffix only when the model entry lists that level. When the catalog tool is unavailable, the catalog is empty, or no catalog model matches the documented evidence and role constraints, the child stays unpinned and the orchestrator reports the limit instead of inventing a model or inspecting credentials. Each workflow invocation automatically receives one stable, non-"default" Intercom group as typed admission policy. Its stages and delegated children carry that group across single, parallel, and follow-up work unless a call explicitly overrides group. Outside workflows, children inherit the launching session’s resolved group. This isolates workflow runs from unrelated runs and the main chat while contact_supervisor retains its authorized cross-group route.

​
Context and execution modes

Subagents can run with fresh or forked context:
  • context: "fresh" starts a separate in-process child session with only the task and selected agent context.
  • context: "fork" creates a real branched child session from the parent session leaf. It fails fast if the parent session cannot be forked; it does not silently downgrade to fresh context.
For adversarial review or research, prefer fresh context so the specialist inspects the repository directly. Use forked context when a writer needs the parent conversation history in a separate branch. For parallel implementation work, worktree: true can give each child an isolated git worktree so concurrent edits do not clobber each other. Observation yields do not release these worktrees. The batch’s worktrees and branches are removed once every child that uses them has finished; Atomic first saves each worktree’s changes as a patch under the run’s worktree-diffs/<run id> artifact directory. When a child is paused or quit, or stays resumable because you closed or switched away from its session or its workflow stage paused, its worktree is kept only if it has uncommitted or untracked changes or commits that are not in the run’s base; a clean worktree is removed with the others. Resuming the child continues in its kept worktree, or recreates a removed one from the run’s base with its saved patch applied, so a resumed completed child starts with its earlier changes. A resumed child keeps its worktree until it finishes again, and then saves a new patch (task-<n>-<agent>.<execution>.patch) rather than overwriting the earlier one. Cancelling a child for good, including a queued one, or its workflow stage closing for good, lets its worktree be removed. If you never resume a stopped child that has unsaved changes, its worktree stays on disk under .atomic/worktrees/. Fresh children inherit the invoking session’s SDK configuration, resource-discovery inputs, model/auth runtime and host callbacks. Child tool selections can narrow the parent’s permissions but cannot restore disabled packages or excluded tools. Intercom has no mandatory bypass; a child without access receives no supervisor grant. Model fallback keeps the same inherited restrictions. See SDK child configuration. Top-level parallel calls apply these settings from ~/.atomic/agent/extensions/subagent/config.json after expanding each task’s optional count:
  • parallel.maxTasks defaults to 50 and limits the number of tasks in a parallel set. There is no hard upper cap; raise or lower it as needed.
  • parallel.concurrency defaults to 3 and limits how many children are dispatched at once. Per-call concurrency takes precedence.
  • parallel.runningCapacity defaults to 4 and limits simultaneously running child turns per parent.
To run up to 100 children at once, raise both concurrency and running capacity as well as the task limit:
Running capacity is selected when a parent’s first child is created. Restart Atomic after changing this setting to apply the new capacity. When one assistant response emits several sibling execution-mode subagent tool calls, Atomic collects that synchronous burst before starting a child and runs it as one indexed parallel set. Each original tool call still receives one result containing only the children it requested, and its live result, progress, control, and artifact updates are projected to that same route without sibling data. The TUI redraws the shared run as one aggregate parallel widget rather than retaining one widget per original call. A single call keeps its original SINGLE or PARALLEL mode, calls awaited in sequence remain separate runs, and management actions bypass collection. An execution call that arrives after a child has started still receives the existing in-progress rejection. Prefer one explicit { tasks: [...] } call when planning parallel work; burst collection handles sibling calls emitted by a model. For a collected burst, each call contributes its top-level agent task first and then its tasks entries in array order. Atomic preserves duplicates, expands count in place, and applies parallel.maxTasks after flattening and expansion. Each call-level cwd selects that call’s agent-discovery scope and child base directory. A task-level cwd stays relative to that call base and changes only that child’s execution directory, not agent discovery. This per-origin discovery rule applies only to collected sibling calls; an ordinary explicit { tasks: [...] } call keeps one discovery scope from its top-level cwd. Per-call and per-task group values also stay with their originating children. Shared run options must match across every sibling call: concurrency, worktree, context, share, control, sessionDir, maxOutput, artifacts, includeProgress, and agentScope. A mismatch rejects the whole burst before any child launches and names the incompatible field. For a collected worktree: true burst, every call-level cwd must resolve to the same path. That common path becomes the shared worktree root; differing origins reject the burst before launch, and any task-level cwd must still resolve to that root. Each projected caller result keeps shared worktree diff text and terminal control guidance while its child results and standard child-output sections remain route-local. Use group on a call or task to select the child’s Intercom group. A named string joins that group; true creates one shared UUID group for a parallel set. Precedence is explicit subagent group > inherited current-session group > config > "default". Workflow children inherit their invocation group. Children without Intercom access receive no group or supervisor channel. contact_supervisor can reach the authorized supervisor across group boundaries; ordinary Intercom remains group-bound. Pending Intercom asks belong to the addressed session. A workflow child cannot inspect or answer its parent stage’s pending asks, and sibling children keep separate pending lists. Detached children remain owned by the workflow stage that launched them. When that stage completes, Atomic cancels every still-running owned child (single or parallel) with the existing parent-cancellation outcome (status: "interrupted", cause: "abort") and suppresses late findings and completion notifications instead of routing them to the parent/main chat. These children are terminal; resume refuses them with an error that says their workflow stage ended. When the stage completes, or its run ends or is cancelled, every other subagent it launched becomes terminal too, whether it was paused, quit, completed, or failed. A detached child that finishes while its stage is still live notifies normally, and completing one stage does not affect children owned by other stages or sessions. When a subagent call or parallel task uses a cwd, Atomic validates that working directory before starting the child runtime. Missing or non-directory paths are reported as cwd problems instead of lower-level runtime errors. Single-agent calls also accept reads: string[] | false. Atomic prepends those files as read context for foreground execution through the same in-process session path. Relative entries resolve against the effective child cwd (including a relative top-level cwd resolved from the parent); absolute entries are unchanged. Invalid values fail before the child session starts. Single-agent calls accept progress: boolean in foreground mode. progress: true creates a run-scoped progress.md under isolated subagent artifact storage and instructs the child to maintain it without writing progress.md into the child cwd; progress: false disables an agent’s defaultProgress. When progress is omitted, the agent’s default is inherited, except that inherited progress is suppressed for read-only tasks (progress: true still explicitly opts in). Foreground runs remove this run-owned progress storage after the child exits when artifacts: false, including children temporarily detached for intercom coordination. This is separate from includeProgress: true, which only includes detailed runtime progress telemetry in the final tool result and does not create or maintain a file.

​
Delegation and child boundaries

Delegation is exactly one level deep and cannot be configured. Children complete their assigned tasks directly; they cannot launch other children or pause, resume, or quit them. Children can still run background shells. Those shells appear in the parent’s /tasks: the main chat’s, or the current workflow stage’s. See Shells started by subagents. They may inspect definitions and status with list, get, status, and wait; management-restricted children also cannot create, update, or delete definitions. Child prompts omit parent orchestration artifacts and prior subagent control traffic. Tool availability does not grant delegation authority. The parent remains responsible for orchestration.

​
Custom agents

Moved to Custom subagents.

​
Fallback models

Moved to Subagent reference.

​
Reasoning levels

Moved to Subagent reference.
  • Workflows for multi-stage reusable automation.
  • Intercom for cross-session messaging and supervisor escalation.
  • Skills for reusable instructions invoked with /skill:<name>.
  • Settings for user and project configuration.

​
Owner-bound task projection

Moved to Subagent reference.