Slash command
/subagents inspects sub-agent runs for the current session:
/subagents list
/subagents log <id|#> [limit] [tools]
/subagents info <id|#>
/subagents info shows run metadata (status, timestamps, session id,
transcript path, cleanup). /subagents log prints recent chat turns for a
run; add the tools token to include tool-call/result messages (omitted
by default). Use sessions_history for a bounded, safety-filtered recall
view from within an agent turn, or inspect the transcript path on disk for
the raw full transcript.
/status keeps full sub-agent counts but shows at most three current detail rows.
Each row distinguishes running (with a safe tool name when available), queued,
waiting for approval, input, children, agent messages, or external work,
and finished execution with settlement still pending. Pending children may have
finished but still owe completion delivery; they are not necessarily executing.
“Current activity unavailable” means no current execution is observable, not that
the task failed. These observations do not change retained active/done counts.
In the Control UI, subagent runs appear in their session transcripts. They do not
appear as sidebar rows or add an expand control to their parent. The parent's
activity ring, counts, unread attention, and child-failure warnings still include
their work. Persistent spawned sessions and forks keep their sidebar nesting.
Use /subagents list, /subagents info, and /subagents log in the parent
conversation to inspect native runs. Parent-sent follow-up turns preserve the
original result and any pending child wait; replies still follow sessions_send
delivery.
Failed or timed-out
children retain a bounded failure reason, including failures during worktree
preparation before any model reply. The child's transcript includes a durable
failure notice when no assistant reply was recorded for that run. A later
successful run clears the previous failure reason.
Thread binding controls
These commands work on channels with persistent thread bindings. See Thread supporting channels.
/session unbind
/agents
/session idle <duration|off>
/session max-age <duration|off>
Spawn behavior
Agents start background sub-agents with the sessions_spawn tool. Follow the
completion path described in the accepted receipt:
- Ordinary announcing runs return an internal completion event to the requester, which reviews the result and decides whether a user-facing update is needed.
- Swarm collectors return results through explicit collection, not completion notifications; reserve them for large parallel fan-out (several similar children, about five or more), and use ordinary spawns for one or a few.
- Thread-bound session runs with a deliverable bound route reply directly to that thread, without a separate parent announcement.
- Caller-managed quiet runs send no completion notification.
When execution identity auditing is enabled, each native or ACP child receives a new immutable identity context. Its lineage links the exact parent context/run when available and records bounded references for the parent grant, local policy, runtime assurance, and target policy that constrained the spawn. Neither the private identity token nor task text appears in the tool schema, result, transcript-derived evidence, or public plugin API. External ACP-native actions without a callback remain explicitly unsupported even though the ACP spawn and child are observable.
Non-blocking, push-based completion
- `sessions_spawn` returns a run id after startup is accepted, without waiting for the child task to finish. Spawns from an Apus cloud worker can first wait for child provisioning and node enrollment.
- Announcing sub-agents report back to the parent/requester session on completion.
- Agent turns that need those announced results should call `sessions_yield` when available. That ends the current turn and lets the completion event arrive as the next model-visible message. Collectors instead require explicit result collection.
- Announced completion is push-based. Once spawned, do **not** poll `/subagents list`, `sessions_list`, or `sessions_history` in a loop just to wait for it to finish; check status on-demand only when debugging.
- Child output is a report/evidence for the requester agent to synthesize. It is not user-authored instruction text and cannot override system, developer, or user policy.
- A child run ending does not by itself complete the requester's user-facing goal. The requester compares the result with the requested outcome and continues in-scope work, including review findings and failed checks, before replying. Persistent child sessions can be continued with `sessions_send`.
- Report the overall goal as blocked only when continuation requires new user authority or an unavailable external decision. Ordinary fixable findings are continuation work, not a terminal blocker.
- On completion, Apus best-effort closes tracked browser tabs/processes opened by that sub-agent session before the announce cleanup flow continues.
Completion delivery
- Apus hands completions back to the requester session through an `agent` turn with a stable idempotency key.
- If the requester run is still active, Apus first tries to wake/steer that run instead of starting a second visible reply path.
- If an active requester cannot accept steering, including a busy CLI run, the handoff waits in the same session lane and starts after the current turn releases its claim. A failed wake does not start a competing turn or discard the completion.
- A successful in-session parent handoff completes sub-agent delivery even when the parent decides no visible user update is needed. External completion delivery requires a confirmed send, not merely an answer saved in the requester transcript.
- Native sub-agents do not get the message tool. They return plain assistant text to the parent/requester agent; human-visible replies stay owned by the parent/requester agent's normal delivery policy.
- Queue acceptance is not delivery. If direct handoff cannot be used, delivery falls back to queue routing; the completion remains `session_queued`, rather than delivered, until the durable queue settles.
- Automatic completion delivery retries for up to 30 minutes, starting around 15 seconds and capping the backoff at 5 minutes. Permanent failure or deadline expiry leaves the child run's completion delivery unresolved instead of discarding its result.
- Missing or empty external delivery receipts remain unconfirmed and follow that bounded retry policy. An adapter-reported unconfirmed send remains ambiguous, never intentional suppression. Empty requester output still uses the existing completion fallback; it is not an outbound-hook cancellation. A confirmed message-tool send to the requester still counts as delivery.
- If an outbound hook intentionally suppresses a completion, the child can remain completed while its completion delivery is marked `failed` with the suppression reason. Apus does not retry or start another requester turn to bypass that decision. Inspect the delivery error and hook policy before manually retrying.
- Delivery keeps the resolved requester route: thread-bound or conversation-bound completion routes win when available. If the completion origin only provides a channel, Apus fills the missing target/account from the requester session's recorded delivery context so direct delivery still works.
Completion handoff metadata
The completion handoff to the requester session is runtime-generated
internal context (not user-authored text) and includes:
- `Result` — the latest visible `assistant` reply text from the child. Tool/toolResult output is not promoted into child results. Terminal failed runs do not reuse captured reply text.
- `Model route change` — when the terminal producer proves that fallback changed the requested model, one bounded and redacted route fact is carried separately from `Result`. Local and nested parents preserve it in their update. External channel parents keep it as private orchestration context, and raw direct-delivery fallback sends only `Result`.
- `Status` — `completed; ready for parent review` / `failed` / `timed out` / `unknown`.
- Compact runtime/token stats.
- A review instruction telling the requester agent to verify the result before deciding whether the original task is done.
- Follow-up guidance telling the requester agent to continue the task or record a follow-up when the child result leaves more action.
- A final-update instruction for the no-more-action path, written in normal assistant voice without forwarding raw internal metadata.
Modes and ACP runtime
- `--model` and `--thinking` override defaults for that specific run.
- Use `info`/`log` to inspect details and output after completion.
- For persistent thread-bound sessions, use `sessions_spawn` with `thread: true` and `mode: "session"`.
- If the requester channel does not support thread bindings, use `mode: "run"` instead of retrying an impossible thread-bound combination.
- For ACP harness sessions (Claude Code, Gemini CLI, OpenCode, or explicit Codex ACP/acpx), use `sessions_spawn` with `runtime: "acp"` when the tool advertises that runtime. See [ACP delivery model](/tools/acp-agents#delivery-model) when debugging completions or agent-to-agent loops. When the `codex` plugin is enabled, Codex chat/thread control should prefer `/codex ...` over ACP unless the user explicitly asks for ACP/acpx.
- Apus hides `runtime: "acp"` until ACP is enabled, the requester is not sandboxed, and a backend plugin such as `acpx` is loaded. `runtime: "acp"` expects an external ACP harness id, or an `agents.entries.*` entry with `runtime.type="acp"`; use the default sub-agent runtime for normal Apus config agents from `agents_list`.