# `SuperPi.Plugins.Subagent`
[🔗](https://github.com/oleksandr/super-pi-beam/blob/v0.1.0/lib/super_pi/plugins/subagent.ex#L1)

Subagent Orchestration Plugin (migrated from Pi ecosystem `subagent/`).

Adds the `delegate_subagent` tool. A call starts a **child conversation** with its own model
loop and its own context window, and returns at once. Pass `tasks` to start several children.

## Flow

1. The tool creates the children and one `pi.subagent` task per child (owned by the parent's
   running task), enqueues one `SuperPi.Workers.SubagentWorker` job per child, puts the parent
   task in `waiting` (`TaskEngine.wait_for_children/4`) and returns an acknowledgement that
   names the children. Its `control` directive `%{"await" => ...}` tells the machine to park.
2. The parent's machine parks in `:awaiting_children`. It still answers `cancel`, `get_state` and
   `compact`. The children run on any node of the cluster, under the `:subagents` queue limit.
3. When every child has ended (`wait_policy: "all"`), or at once when one fails
   (`wait_policy: "fail_fast"`), the parent wakes. The machine appends one message per child with
   its summary and the turn goes on. The model sees the summaries as new messages in its next
   request, not as the result of the tool call.

## What a child gets

- Its own durable conversation (`owner_kind: "task"`, owned by the parent's running task), so
  the work is recorded and inspectable.
- The parent's model, workspace and settings, and a system prompt for its role.
- **Never more permission than the parent.** The roles `scout`, `planner`, `reviewer` and
  `researcher` run the `Planner` harness: `plan` mode with read-only tools. A `worker` runs the
  `Code` harness in the parent's execution mode. Permission settings and
  `dangerouslySkipPermissions` are copied, not raised.
- No `delegate_subagent`, `ask_question` or `handoff` tools: a child cannot spawn children
  beyond `config :super_pi, subagent_max_depth` (default 1) and has no human to ask.

## Limits

- Children use the same provider and credentials as the parent. There is no separate budget.
- A child ends at the timeout (`timeout_ms`, default `config :super_pi, subagent_timeout_ms`
  = 120 s, counted from the start of its job) and is then failed and stopped.
- `session.cancel` on the parent aborts the whole subtree: the children's tasks are aborted and
  their machines stop.
- One delegation at a time: a second call while children run is refused. Give all tasks in one
  call (`tasks`).
- Only the child's final text returns to the parent, not its intermediate steps. It is cut at
  8000 bytes.

## Events

`subagent_started` when a child's job begins, `subagent_finished` when its task settles. Both go
to the parent conversation.

## Tests

`config :super_pi, :subagent_machine_opts` is merged into every child machine's options (an
`llm_responder`). Oban runs in `testing: :manual` there: drain the `:subagents` queue to run the
children.

# `description`

# `id`

# `name`

# `tool_spec`

Returns the tool specification map for direct registration.

---

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