Background tasks
Background subagents keep working after the launch call returns. You can continue chatting without restarting them or keeping a task list open. In main chat and live workflow-stage chat, a compact indicator appears below the prompt box and MCP status, and above the workflowBACKGROUND widget when present:
/tasks, so an old failure cannot keep the live indicator red. Running tasks do not expire merely because they are quiet.
Run /tasks to open the background-only list. The command also appears in workflow-stage slash suggestions, including when skill commands are disabled. Foreground-only commands do not appear. Work that ran in the background stays available after completion or a later foreground wait. Updates never open the list automatically. Closing the inspector does not stop the tasks.
Opening /tasks is navigation, not an approval request. It does not mark the agent blocked in Herdr. The inspector stays open until you close it, even when its tasks finish; task history is not deleted when the compact indicator disappears.
Choose how long to wait
The agent can choose foreground-first or background observation for each authorized shell or subagent call. Choosing a mode does not require a separate user confirmation and does not relax tool permissions or task ownership.
If the task finishes during observation, the call returns its terminal result instead. Automatic backgrounding is observation expiry, not a slow-task failure, a restart, or a second execution. Use foreground-first observation for a dependency and background observation for independent work. If a dependency yields, wait for its actual completion before using the result.
Shell
budgetMs accepts finite non-negative milliseconds; zero means no observation delay. It is only valid for foreground observation. A trusted SDK host can override the usual budgets or select tasks.wait.kind: "until-settled"; omitted foreground budgets then wait until settlement. Explicit per-call budgets still take precedence.
Background subagents
Ask Atomic to delegate a bounded task:/agents to browse available definitions before choosing an agent.
A launch result says Launched in background. This records what happened at launch; it is not a permanently live status label. The below-prompt indicator and /tasks show the current state.
Waiting is not restarting
To wait briefly before continuing:Completion messages
Completion creates a shaded notification card in the owning chat without depending on a model reply. It uses the chat theme’s card background and padding, with a colored outcome, the agent or shell name, and an available result preview:Inspect tasks
Configured task bindings take precedence over the default Left, page, and
x shortcuts. Input mode receives ordinary typing, including x, without stopping the task. The footer shows the applicable controls.
The list groups Agents and Shells, with counts and status symbols. Detail views pin identity, state, available metrics, and the selected action while their body scrolls. Missing metrics are omitted rather than displayed as zero. Recorded zero values remain visible.
Agent details include recent retained tool activity, the prompt, a latest-response preview, and error or attention information. Transcript inspection uses a dedicated scrolling view with a pinned title, line position, and controls, rather than nesting full chat components inside a detail box. It renders retained messages and tool results without hidden reasoning or inline images. Earlier pages do not jump back to the latest page when background activity arrives.
Shell details show the command, available exit information, and a bounded output tail. The preview shows up to ten wrapped lines from the retained 8 KiB tail. Output gaps and omitted earlier content are labelled. An empty output stream says No output available. Shell transcript inspection exposes the retained tail, not an invented agent conversation or an unlimited log viewer.
States
Completed, failed, and stopped tasks retain inspection but do not offer execution controls. Foreground wait observes a running task; it does not transfer ownership or create a second execution.
Background shells
Top-level modelbash calls on POSIX use the session’s task owner. A long command can outlive its foreground observation budget and return a task ID while continuing to run. Its status then appears below the prompt and under Shells in /tasks. An explicit execution timeout still ends the command; it is separate from observation yielding.
timeout is seconds and defaults to 300, with a maximum of 3600. It continues counting after backgrounding. Choose a timeout appropriate for the command; reducing budgetMs does not shorten or extend it. Use the returned task ID to inspect or stop the existing task through /tasks. Background completion notifies the parent automatically, so there is no need to launch the command again to collect its result.
Shell completions use the same shaded card as subagents, with a retained output preview and available exit code. Nonzero shell exits are shown as failures even though the process itself reached a terminal state. Cancellation shows Stopped. The card and below-prompt count update in the owning main or workflow-stage chat.
Native Windows bash and bash calls inside subagent sessions retain their existing execution paths. Without a supported task owner, explicit background requests are refused before execution; foreground calls wait for completion rather than automatically yielding. Custom BashOperations adapters receive wait but must implement it themselves. External-terminal processes are not adopted into /tasks. A child’s own tool use appears in that subagent’s activity and transcript.
Lifetime and scope
Background means independent of the current observation, not independent of its owner. Pausing main chat or a workflow-node chat aborts the foreground turn only; already-running background agents and shells keep their identities, output, and later completion. Closing a session cancels its session-owned work. Workflow-stage tasks belong to the stage generation: detaching a pane, pausing, or ending a single model turn does not cancel them. Closing that generation does, without cancelling sibling stages. Closing/tasks only disposes the view. Explicit /tasks stop and declared execution timeouts remain separate controls.
Task inspection is owner-scoped. It is not a machine-wide process list. Switching sessions does not copy the previous session’s task rows into the new one. Missing retained history is reported explicitly.
Task state and completion delivery
Foreground and background describe observation, not different executions. Each admitted task keeps its identity and owning session as callers start or stop waiting. The nativewasBackground field remains set after a designated wait yields, including after a later foreground wait or settlement.
Execution outcome and resource cleanup are separate states. A terminal result does not by itself prove that resources were reaped. Cleanup failures remain explicit. Supervised shells retain output while running, and finish output draining as part of cleanup.
Native integrations can use TaskSupervisor.taskSettlement(task) from @bastani/atomic-natives to retrieve an authentic terminal receipt without creating a new wait. This supports recovery when a bounded event journal no longer contains the completion event. Session-history completion intents and acknowledgements reuse the same identity when notification delivery is retried.
UI previews are bounded and are not a substitute for retained output. Gaps and truncation are labelled; unavailable history is reported rather than reconstructed from activity counters.
Related documentation
- Subagents covers definitions, models, context, and delegation boundaries.
- Keybindings covers task-action remapping.
- Workflows covers durable stage lifecycles.