# `Pixir.Subagents`
[🔗](https://github.com/Ranvier-Technologies/pixir/blob/main/lib/pixir/subagents.ex#L1)

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`.

# `child_spec`

Application child spec.

# `close`

Cancel a running Subagent, or close a queued/terminal Subagent as cleanup.

# `default_limits`

Default runtime limits.

# `diagnostics`

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`

List Subagents for a parent Session.

# `reconstruct`

Reconstruct Subagent relationships and terminal state from parent History.

# `restrict_resume_posture`

```elixir
@spec restrict_resume_posture(map() | nil, Pixir.Permissions.mode(), map() | nil) ::
  {:ok, map() | nil} | {:error, map()}
```

Apply the common restrict-never-widen rules to a restored posture.

# `resume_posture`

```elixir
@spec resume_posture(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, map()}
```

Rehydrate a Session's durable permission posture for a cold resume.

Root Sessions record their posture at creation (`Pixir.Conversation.start/1`,
lineage `root`, trusted only in root position: first non-`session_fork` event,
runtime-authored source) and restore the recorded capability ceiling —
including unbounded auto when the marker declared it. Spawned
children record theirs in the Subagent Manager (lineage `child`) and keep the
stricter contract: write-capable history restores only with a bounded policy.
Legacy Logs without posture evidence remain resumable only when they contain
no write-capable evidence, and then restore an explicit read-only ceiling;
otherwise they fail closed with reason `missing`, which is the one
classification the operator may override via the CLI's explicit legacy-root
attestation (never as unbounded auto).

# `send_input`

Send follow-up input to an idle Subagent.

# `spawn_agent`

Spawn or queue a Subagent.

# `statuses`

All known Subagent lifecycle statuses.

# `summarize`

Summarize agent maps for model-facing output.

# `summarize_wait_outcome`

Build model-facing text for a structured wait outcome.

# `terminal?`

Whether a status is terminal.

# `terminal_statuses`

Statuses that no longer have a live child runtime.

# `transition_allowed?`

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.

# `validate_spawn`

Validate and normalize a Subagent spawn without creating runtime state.

# `wait`

Wait for selected Subagents to reach a terminal status.

# `wait_outcome`

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"`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*