Public facade for BEAM-native Subagent orchestration (ADR 0011).
Subagents move through a small lifecycle state machine. The usual path is
queued -> running -> completed, but failures, timeouts, cancellation, and
detached restored children must remain explicit so parents and diagnostics can
tell "finished cleanly" apart from "needs operator attention".
max_depth is an absolute delegation-depth cap from the root Session. A child
spawned by the root runs at depth 1; that child may only spawn another child
when the configured cap is at least 2.
Summary
Functions
Application child spec.
Cancel a running Subagent, or close a queued/terminal Subagent as cleanup.
Default runtime limits.
Return a read-only snapshot of the Subagent Manager runtime for one parent Session.
List Subagents for a parent Session.
Reconstruct Subagent relationships and terminal state from parent History.
Send follow-up input to an idle Subagent.
Spawn or queue a Subagent.
All known Subagent lifecycle statuses.
Summarize agent maps for model-facing output.
Build model-facing text for a structured wait outcome.
Whether a status is terminal.
Statuses that no longer have a live child runtime.
Whether the public lifecycle contract allows a status transition.
Wait for selected Subagents to reach a terminal status.
Wait for selected Subagents and return a structured outcome.
Functions
Application child spec.
Cancel a running Subagent, or close a queued/terminal Subagent as cleanup.
Default runtime limits.
Return a read-only snapshot of the Subagent Manager runtime for one parent Session.
This is volatile process health evidence, not durable history. Use the Session Log and Session tree for canonical lifecycle facts.
List Subagents for a parent Session.
Reconstruct Subagent relationships and terminal state from parent History.
Send follow-up input to an idle Subagent.
Spawn or queue a Subagent.
All known Subagent lifecycle statuses.
Summarize agent maps for model-facing output.
Build model-facing text for a structured wait outcome.
Whether a status is terminal.
Statuses that no longer have a live child runtime.
Whether the public lifecycle contract allows a status transition.
closed is retained as Pixir's local close/cleanup state. Completed, failed,
timed-out, and cancelled Subagents may be restarted by send_input/4; detached
children cannot be resumed because there is no live process handle.
Wait for selected Subagents to reach a terminal status.
Wait for selected Subagents and return a structured outcome.
Unlike wait/4, this keeps partial fanout visible: timed-out, failed, detached,
cancelled, and still-incomplete children are bucketed instead of turning the
parent tool call into an opaque failure. The returned "partial" boolean is
true for any non-completed aggregate status; consumers should use "status"
when they need to distinguish "partial" from "incomplete".