Skip to main content

​
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 workflow BACKGROUND widget when present:
The indicator counts active agents and shells, including queued, stopping, and attention-needed tasks. Completed, failed, and stopped tasks leave it immediately. It disappears when no background work is active. Quiet tasks do not expire.

​
Open the task inspector

Run /tasks to inspect work without stopping it:
  • The compact picker opens in the editor slot, with the conversation visible above it. It lists only tasks owned by that chat.
  • Within the Agents and Shells sections, tasks are ordered by status: running (tasks needing attention first), stopping, queued, failed, cancelled, then completed. The newest launch or settlement comes first within each status, and your selection follows its task when it moves.
  • Detail, transcript, input, and cancellation-confirmation pages use the full screen.
  • Escape returns to the picker with your selection preserved, then to chat.
  • Completed background work remains available, including after a later foreground wait. Foreground-only commands are excluded.
  • Updates never open or close the inspector automatically. Closing it does not stop tasks.
Results and failures remain in completion cards and /tasks after leaving the live indicator. The command appears in workflow-stage slash suggestions even when skill commands are disabled. Main and workflow-stage pickers share the same layout. Their footers retain the chat’s resolved model and reasoning level, current folder and Git branch, and MCP status, including during foreground streaming. Opening /tasks is navigation, not approval. It does not mark the agent blocked in Herdr or produce a “Main chat needs input” notice. A genuine question waiting behind the workflow graph still shows that notice until answered or the graph is hidden or closed.

​
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. For ordinary shell commands, leave wait out rather than routinely requesting one-second waits. Short waits can background otherwise brief commands and add follow-up calls without speeding up execution. Use explicit background observation when you have independent work to do, and a short budget only when you need control back sooner. Explicit budgets remain supported on every platform. Keep immediately blocking work local unless a specialist, isolated context, or your explicit delegation request makes a subagent worthwhile. After spawning, continue independent work without duplicating the child’s task. Wait when its result becomes a dependency; otherwise rely on completion notices rather than repeated short waits or status polls. 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. On command launches it belongs inside a foreground wait; existing-task action: "wait" calls take it at the top level. 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. A zero-budget wait may return a background state immediately. It still refers to the same task; execution continues.

​
Background subagents

Ask Atomic to delegate a bounded task:
For tool callers, owner-bound launches default to background observation. Explicit examples:
Parallel tasks have independent identities. Accepted work beyond the concurrency limit stays queued. Use /agents to browse available definitions before choosing an agent. Intercom communication does not cancel a parallel batch. A blocking ask or supervisor decision waits only in the requesting child and resumes that same execution after the matching reply. Sends and progress updates remain nonblocking. Foreground observations may yield so the parent can reply; execution concurrency, queued siblings, and task identities are preserved. Stop a selected task explicitly, or close its owner to cancel all owned work. 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

When specialist delegation is useful and its result is needed next, use foreground observation:
If that observation budget expires, the same child continues in the background. It is not an execution timeout. Observe the task ID returned by the original call:
To stop, hold, or continue a child, use pause, quit, and resume; see Run control. Do not launch a duplicate just to retrieve its result. Use the task ID returned at launch. IDs are scoped to the session or workflow stage that owns them. Foreground subagent launches and explicit action: "wait" calls also yield when user steering or an Intercom ask/send is admitted to the waiting parent, in main chat or a live workflow stage. The message stays in the normal delivery queue so the parent can handle it and reply. This releases only observation: children keep running under the same task IDs, and other owners’ waits are unaffected.

​
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:
The parent model also receives the result context. Delivery retries do not relaunch the child. Workflow completions stay in their owning stage chat, not the main conversation. Supervisor progress messages are labelled Historical supervisor update with their original Sent: timestamp. They describe the child’s state when sent, not its current status, and can arrive after completion. Prefer a later correction or final result over an earlier progress hypothesis; use /tasks for the current task state. Stopping a subagent through /tasks (x, then y) delivers a stopped card and stop context to the parent model. The notice arrives only after termination is confirmed, not while the task is Stopping. It requires no final response from the child. Cancelling queued work sends the notice without starting it. A subagent stopped this way cannot be resumed; to stop one and keep it resumable, use subagent({ action: "quit", id }) (see Run control). A subagent stopped with subagent({ action: "pause" | "quit", id }), or by its workflow stage pausing, is not ended. Its notice reads paused · awaiting resume (for a quit child, Subagent <agent> quit · paused, awaiting resume), gives Stop reason: pause or quit, and names the call that continues it, subagent({ action: "resume", id: "<child-id>" }), instead of telling the model the execution has ended. Its /tasks row shows Paused · awaiting resume. Repeated stop requests or late child results do not duplicate the notice or overwrite the recorded outcome. A task that finished before cancellation keeps its actual result. Closing the owning session or workflow stage still suppresses late notices. Restored completions may have only an outcome and task identity if the original live task or transcript is unavailable. Atomic does not invent missing output. Excerpts are bounded; inspect retained history for more detail. Long titles and previews are truncated or wrapped within the card width. Its background covers the ellipsis, expand hint, and trailing padding on every row.

​
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 rows and completion cards show the resolved model and reasoning setting, for example openai-codex/gpt-6-astra · thinking medium. These settings update on fallback and remain after completion. Foreground results retain the same metadata. Missing settings are not inferred from token counts; early launch receipts may not yet have a resolved model. 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. An open live transcript updates directly from the child’s session events, including streaming assistant text and partial/final tool results. Shell output refreshes on task state updates, including updates received during an earlier output read. You do not need to leave and reopen the transcript. Reading earlier retained pages keeps your position while the live tail continues updating. 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

Model bash calls on POSIX and native Windows, and powershell calls on native Windows, use the session’s task owner. Subagent shells use their parent’s owner; see Shells started by subagents. 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.
The shell execution timeout is separate: 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. Observe an existing task without running its command again:
Use the original task ID from the same owning session or workflow stage. Omit budgetMs to use the owner’s command observation policy, or pass 0 to poll. A wait returns retained output and a yielded or settled observation; settled results include available exit and failure details. The transcript shows one status line above the output: ✓ completed · exit 0, ✗ exited 1, ● still running · showing output so far, or ○ cancelled. When the output was cut short, a dim line below it gives the path to the full output. The agent receives the same facts as one sentence after the output, and the structured observation stays in the result details. While running, successive yielded waits advance through retained output in bounded pages, including after a session reload. A caught-up wait returns no output until more arrives. Settled waits return all retained output again, subject to labelled gaps and truncation, so they may repeat output you have already seen. Do not combine action: "wait" with command, timeout, wait, env, cwd, or pty. Existing-task waits require a supported task owner, even with custom execution adapters. Unknown or foreign IDs are rejected with No background task "<id>" in this session and a hint to run /tasks. Cancelling a wait or admitting user/Intercom messages releases observation only, not the command. Waiting never extends the original execution timeout or the owner’s lifetime.

​
Stop a shell task from a tool call

Use the kill tool with the exact task ID returned by bash or powershell, whether it launched explicitly in the background or automatically yielded:
The same command works in main and workflow-stage chat. It selects the existing owned shell task; do not supply a process ID, shell name, or another owner’s task ID. Unknown, malformed, foreign-owner, and subagent IDs are rejected. /tasks stop controls remain available. The transcript shows a status line such as ● stopping · cancellation requested, ○ cancelled, or ✓ already completed · exit 0, and the agent receives the same facts as a sentence. The structured result keeps taskId, decision, execution, and cleanup. cancellation-requested means cancellation was requested, not that termination or cleanup has finished. A repeated call preserves that decision while reporting current state. already-settled means the task finished before cancellation and keeps its original outcome. Confirm execution.kind: "settled" and cleanup.kind: "reaped" before treating termination and cleanup as complete. Cleanup failures remain errors, not successful stops. Output and completion notifications remain available; killing a task does not erase its history. 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 refuses owned shell launches it cannot supervise. Legacy Windows WSL bash.exe stdin transport is unsupported; run Atomic inside WSL for the normal POSIX/Bash path.

​
Shells started by subagents

Subagents can run background bash and powershell commands too. Their shell tasks belong to the parent that launched the subagent: in main chat they appear under Shells in the main chat’s /tasks, and in a workflow the subagent’s shells appear in the current stage’s /tasks. The subagent itself still cannot launch other subagents.
  • The subagent can wait on and kill the shells it launched, but not the parent’s own tasks or another subagent’s.
  • The parent can inspect, wait on, and stop those shells from its own /tasks, bash({ action: "wait", id }), or kill({ id }).
  • While the subagent is still running, a background shell’s completion notice goes to the subagent. After the subagent finishes, the notice goes to the parent.
  • Shells keep running after the subagent finishes. They stop when the parent’s session or workflow stage closes, or when a workflow stage pauses.
Custom operations 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 aborts the foreground turn only; its background agents and shells keep running. Detaching a workflow pane, ending a model turn, or closing /tasks also leaves owned background work alone. Pausing a workflow stage blocks new launches, stops its active and queued agents, and cancels its shells. The stopped subagents stay resumable with subagent({ action: "resume", id }). Pause completes only after confirming cleanup; failures are reported rather than treated as a successful pause. Main-chat tasks, sibling stages, and future stage generations are unaffected. Pause does not close the stage’s message generation: queued user and Intercom messages remain held for resume. Resume permits fresh launches but never resurrects cancelled shells; retained task results remain inspectable. Closing a session or stage generation still cancels its remaining owned work. Explicit /tasks stop and declared execution timeouts remain separate controls. On native Windows, Suspend opens a PowerShell subshell rather than freezing Atomic. Exit the subshell to restore the same session; owned background tasks continue while it is open. 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. Closing /tasks does not stop the chat footer’s live Git branch updates.

​
Task state and completion delivery

Foreground and background are observation modes for the same task. Stopping a wait does not create, stop, or restart execution. A terminal result does not by itself confirm resource cleanup. Check the tool’s cleanup status before treating a stop as complete. 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.
  • Subagents covers definitions, models, context, and delegation boundaries.
  • Keybindings covers task-action remapping.
  • Workflows covers durable stage lifecycles.