Repository navigation
Product Book Spawn
Part of the Product Book. Observable product behaviour at
pi-schematic@36bd569(main, 2026-10-12).
A Pi coding agent can hand a focused task to a child agent through spawn, then receive a concise result back in its own conversation. The child works in a separate context rather than carrying the parent's full transcript, while retaining the tools and working directory needed to do the task. Delegation can also choose a model suited to the task and require particular capabilities before work begins. The live display of child activity is covered in the TUI chapter.
The parent calls the spawn tool with a prompt: a required string describing what the child is to do. A task might ask the child to inspect one component and report the finding while the parent handles a different part of the work. spawn asks the child to return a concise final result under 2000 lines or 50 KB; its conversation with the parent is a report, not a copy of everything it did.
Three optional inputs refine that request. group names a Model Group, a named set of model entries from which the child's model can be selected. thinking sets a requested thinking level: off, minimal, low, medium, high, xhigh, or max. constraints is a JSON object, not a string or array, for declaring capability requirements. For instance, constraints: { modalities: { required: ["image"] } } asks for image capability. The production modality names are text, image, and reasoning; these names describe requirements the selected route must meet, not extra instructions in the task prompt. When composing a request, #group autocomplete also presents group choices with model and thinking details.
Each child begins an in-memory session with its own context, not the parent's transcript. It starts in the parent's working directory and inherits parent tools that are active, registered, and executable in the child's session, including eligible extension and MCP tools. MCP tools are tools supplied through the Model Context Protocol. There is no separate worktree or per-child granular tool policy: separate context does not mean separate filesystem authority.
Notebook tools are available to the child on shared notebook state. The notebook is a set of named pages used to retain information across contexts; the child's prompt lists available page names so it can read a relevant page on demand instead of having every page body loaded at the start. The child has its own notebook tools, but the state they operate on is shared. Children cannot call spawn to create grandchildren and cannot call handoff to replace their own context. Those exclusions keep this delegation one level deep.
The parent's readonly posture also carries into the child. If the parent is readonly, the child's write and edit tools are unavailable, and its bash tool uses the readonly guard. Separate context, in other words, is not a way around that restriction. By contrast, concurrent sibling spawns can run independently and return separate results to the parent.
When no Model Group is supplied, the child uses the parent's public model. Its thinking level is the explicit thinking value if one was supplied, or otherwise the parent's current level. The router trims surrounding whitespace and looks up the group by exact name. For a known group, selection considers only member entries whose models resolve through the registry and have configured authentication; among eligible entries, the choice is uniform, with no rule preventing the same entry from being chosen on consecutive calls. When requirements have been declared, selection preferentially draws only from usable entries satisfying them.
A selected group entry can specify its own thinking level. That level overrides both the explicit request and the inherited level, and the router clamps it to what the selected model supports. An unknown group behaves differently from a known but unusable group: the unknown name visibly falls back to the parent's model and thinking. A known group with zero model entries instead produces a group-specific error, as does one with no configured, authenticated usable entries. There is no weighting, health-based routing, retry, failover, or selection optimizer.
Capability requirements make the route testable before the child starts. By default, a group's modalities are the union of its members' capabilities. An explicit override can narrow that set, but cannot add a modality the members do not support. The router checks declared requirements against both the group's effective capabilities and the selected model; without a known group, it still checks them against the inherited parent model. Unknown constraint keys or malformed requirement values fail before child creation. If required modalities are missing, the failure reports what is missing from the group and/or model rather than starting a child that cannot meet the request. spawn passes the selected public model to a child-owned runtime: failure to resolve it there does not trigger another selection.
spawn draws the result from the most recent assistant message containing text, not from the child's entire transcript. It carries the effective thinking level, the outcome, and a truncation flag; when available, details also give child token, turn, and cost statistics. Results from a routed group identify the selected group, provider/model, and thinking level. If the requested group was unknown, the result visibly identifies fallback to the parent's provider/model and thinking level, so the parent can tell which route actually ran.
Even a concise report has a hard display limit: child result text is restricted to its first 2000 lines and 50 KiB of UTF-8 text. When that limit truncates the result, a visible advisory asks for a shorter summary. An aborted child may return an explicit aborted outcome with empty result text; a non-aborted child that gives no assistant text instead fails with Child agent produced no output. A running child responds to the tool's AbortSignal, allowing the running work to be interrupted. A parent session reset also aborts live children, and spawn disposes of created child sessions after completion or failure. With no parent model configured, spawn fails before child creation with No model configured. Cannot spawn child agent. These outcomes distinguish interruption, missing output, and a report too long to return in full.
PB-SPAWN-01 … PB-SPAWN-45 — 45 atomic behaviour rows
| ID | Behaviour | Evidence |
|---|---|---|
| PB-SPAWN-01 | The agent can delegate with the spawn tool. |
spawn/index.ts:659-665 |
| PB-SPAWN-02 |
prompt is the required string describing the child's task. |
spawn/index.ts:303-309 |
| PB-SPAWN-03 |
group optionally names a Model Group for the child's model route. |
spawn/index.ts:310-312 |
| PB-SPAWN-04 |
constraints optionally declares capability requirements as a JSON object, not a string or array. |
spawn/index.ts:313-315 |
| PB-SPAWN-05 | Modality requirements have the shape constraints: { modalities: { required: ["text", ...] } }. |
spawn/index.ts:299-300 |
| PB-SPAWN-06 | Supported production modality names are text, image, and reasoning. |
model-groups/types.ts:4-6 |
| PB-SPAWN-07 |
thinking optionally accepts off, minimal, low, medium, high, xhigh, or max. |
spawn/index.ts:316-322 |
| PB-SPAWN-08 | The child's task prompt asks for a concise final result under 2000 lines / 50 KB. | spawn/index.ts:449-460 |
| PB-SPAWN-09 | Each child starts in an in-memory session with its own context, not the parent's transcript. |
spawn/index.ts:449-460, spawn/index.ts:485-492
|
| PB-SPAWN-10 | Without a group, the child uses the parent's public model. |
model-groups/router.ts:110-119, model-groups/router.ts:202-212
|
| PB-SPAWN-11 | Without a group, the child uses the explicit thinking level if supplied, otherwise the parent's current thinking level. |
spawn/index.ts:401-412, spawn/index.ts:679-689
|
| PB-SPAWN-12 | The child starts in the parent's working directory. | spawn/index.ts:485-491 |
| PB-SPAWN-13 | The child inherits active parent tools registered and executable in its session, including eligible MCP/extension tools. |
spawn/index.ts:225-241, spawn/index.ts:464-466
|
| PB-SPAWN-14 | The child gets its own notebook tools operating on the shared notebook state. | spawn/index.ts:329-343 |
| PB-SPAWN-15 | The child prompt lists available notebook page names for on-demand reading rather than loading their bodies. | spawn/index.ts:433-455 |
| PB-SPAWN-16 | Children cannot invoke spawn to create grandchildren. |
spawn/index.ts:231-240, spawn/index.ts:449-453
|
| PB-SPAWN-17 | Children cannot invoke handoff. |
spawn/index.ts:231-240, spawn/index.ts:284-286
|
| PB-SPAWN-18 | Under parent readonly posture, child write and edit tools are unavailable. |
spawn/index.ts:243-252, spawn/index.ts:483
|
| PB-SPAWN-19 | Under parent readonly posture, the child's bash tool uses the readonly guard. |
spawn/index.ts:254-278, spawn/index.ts:476-483
|
| PB-SPAWN-20 | A named group is looked up by its exact name after trimming surrounding whitespace. | model-groups/router.ts:202-212 |
| PB-SPAWN-21 | A known group selects only registry-resolved members with configured authentication. |
model-groups/router.ts:121-128, model-groups/router.ts:213-218
|
| PB-SPAWN-22 | Selection is uniform across the eligible member entries, with no no-repeat rule between calls. | model-groups/router.ts:130-136 |
| PB-SPAWN-23 | When requirements are declared, selection preferentially draws only from usable members satisfying them. | model-groups/router.ts:130-135 |
| PB-SPAWN-24 | A selected group entry's thinking level overrides explicitly supplied or inherited thinking, and is clamped to its model. |
model-groups/router.ts:139-148, spawn/index.ts:404-412
|
| PB-SPAWN-25 | An unknown group falls back visibly to the parent's model and thinking. |
model-groups/router.ts:202-212, spawn/renderer.ts:239-252
|
| PB-SPAWN-26 | A known group with zero model entries fails with a group-specific error. |
model-groups/router.ts:33-35, model-groups/router.ts:213-216
|
| PB-SPAWN-27 | A known group with no configured/authenticated usable entries fails rather than falling back. |
model-groups/router.ts:34-35, model-groups/router.ts:215-217
|
| PB-SPAWN-28 | By default, group modalities are derived from the union of member capabilities. | model-groups/constraints/modalities.ts:39-56 |
| PB-SPAWN-29 | An explicit group modality override may narrow supported modalities but cannot add unsupported ones. |
model-groups/constraints/modalities.ts:39-70, model-groups/constraints/modalities.ts:78-80
|
| PB-SPAWN-30 | Declared capability requirements are checked against both the group's effective capabilities and the selected model. |
model-groups/router.ts:161-173, model-groups/router.ts:219-224
|
| PB-SPAWN-31 | Without a known group, declared requirements are still checked against the inherited parent model. |
model-groups/router.ts:161-173, model-groups/router.ts:202-224
|
| PB-SPAWN-32 | Unknown constraint keys and malformed requirement values fail before a child starts. |
spawn/index.ts:360-375, spawn/index.ts:404-414, spawn/index.ts:485-492
|
| PB-SPAWN-33 | Unmet modality requirements fail before child creation, reporting what's missing from the group and/or model. |
model-groups/router.ts:36-43, model-groups/router.ts:176-196, spawn/index.ts:405-414
|
| PB-SPAWN-34 | The selected public model is passed to a child-owned runtime; a child-runtime resolution failure does not trigger another model selection. |
spawn/index.ts:405-415, spawn/index.ts:485-492
|
| PB-SPAWN-35 | The child result uses text from the most recent assistant message containing text, not the child's full transcript. |
spawn/shared.ts:32-45, spawn/index.ts:568-608
|
| PB-SPAWN-36 | The result carries the effective child thinking level, outcome, and truncation flag. |
spawn/index.ts:493-496, spawn/index.ts:591-604
|
| PB-SPAWN-37 | When available, result details include child token, turn, and cost statistics. |
spawn/index.ts:154-173, spawn/index.ts:583-603
|
| PB-SPAWN-38 | Child result text is limited to its first 2000 lines and 50 KiB of UTF-8 text. |
spawn/index.ts:52-53, spawn/index.ts:79-104, spawn/index.ts:118-126
|
| PB-SPAWN-39 | A truncated result ends with a visible advisory asking for a shorter summary. | spawn/index.ts:118-133 |
| PB-SPAWN-40 | Routed results identify the selected group, provider/model, and thinking level. |
spawn/index.ts:417-431, spawn/renderer.ts:239-245
|
| PB-SPAWN-41 | Unknown-group results visibly identify fallback to the parent's provider/model and thinking level. |
spawn/index.ts:424-431, spawn/renderer.ts:246-251
|
| PB-SPAWN-42 | An aborted child can return an explicit aborted outcome even with empty result text. |
spawn/index.ts:568-575, spawn/shared.ts:2
|
| PB-SPAWN-43 | A non-aborted child with no assistant text fails with Child agent produced no output.
|
spawn/index.ts:568-574 |
| PB-SPAWN-44 | A running child responds to the tool's AbortSignal. |
spawn/index.ts:510-545 |
| PB-SPAWN-45 | Concurrent sibling spawns can run independently and return separate results. | tests/unit/spawn.test.ts:1584-1642 |