Repository navigation
Spec2Contract Spawn
The Spawn area of the pi-schematic Product Book, left space PB-SPAWN-01…PB-SPAWN-45
(45 rows), describes the child-agent delegation tool: schema/envelope validation, Model Group
routing and capability gating, child tool/notebook inheritance, abort/invalidation lifecycle, and
result/stat/identity surfacing. Its contracts are carried primarily by the spawn fixtures
(T01–T07), with the routing and modality rows genuinely sealed by the Model-Groups fixtures
(T15, T17, T18) and the readonly, state, render-snapshot and e2e fixtures (T28, T37, T43, T45,
T47, T49) corroborating the corresponding surfaces. Rows with several distinct contract surfaces are
split and the aspect is named in Notes.
| Claim ID | Assertion (terse) | Fixture(s) | Status | Notes |
|---|---|---|---|---|
| PB-SPAWN-01 | spawn tool is registered and executable | T01, T05, T49 | ✅ asserted |
spawn.test.ts — "registerSpawnTool registers a tool with correct name and metadata" (name spawn, label, description, renderShell self); spawn-after-handoff.test.ts — "spawn tool execute succeeds after handoff module initialization"; real-host.test.ts — "host starts and extension registers" lists the spawn tool. |
| PB-SPAWN-02 |
prompt is a required string |
T01, T06 | ◐ partly asserted | String form exercised: spawn.test.ts — "spawn tool schema validates constraints via Value.Check" accepts {prompt:"Do the task"}; spawn-runtime-compatibility.test.ts — "spawn accepts max thinking parameter in schema". Missing portion: no test omits prompt and asserts the schema/execute rejects it as required. |
| PB-SPAWN-03 |
group optionally names a Model Group |
T01, T15 | ✅ asserted |
spawn.test.ts — "spawn execute composes Model Group routing with readonly child guards" (group review routes); "spawn accepts max thinking parameter in schema" accepts {prompt} with group omitted; model-groups-router.test.ts — "omitted and unknown groups inherit parent route with fallback metadata". |
| PB-SPAWN-04 |
constraints optional JSON object, not string/array |
T01 | ✅ asserted |
spawn.test.ts — "spawn requirements validate the canonical envelope and keep its shape" (stringified constraints and bare-array modality both throw); "spawn tool schema validates constraints via Value.Check" rejects stringified and bare-array forms and accepts an omitted constraints. |
| PB-SPAWN-05 | modalities shape { modalities: { required: [...] } }
|
T01 | ✅ asserted |
spawn.test.ts — "spawn tool schema validates constraints via Value.Check" accepts the nested envelope and rejects bare-array modalities, array-with-embedded-required, and non-object requirements; "spawn requirements validate the canonical envelope and keep its shape". |
| PB-SPAWN-06 | production modalities are text / image / reasoning | T01, T17 | ✅ asserted |
spawn.test.ts — "spawn tool schema validates constraints via Value.Check" accepts text/image and rejects out-of-vocabulary audio; model-groups-constraints.test.ts — "generic multi-select editor enumerates automatic + one toggle per choice" enumerates text/image/reasoning. |
| PB-SPAWN-07 |
thinking accepts off/minimal/low/medium/high/xhigh/max |
T01, T06 | ◐ partly asserted |
spawn-runtime-compatibility.test.ts — "spawn accepts max thinking parameter in schema" (max); spawn.test.ts — "spawn execute composes Model Group routing…" uses xhigh and "spawn forwards requested thinking…" uses high/max. Missing portion: off/minimal/low/medium are never driven through the spawn schema and no out-of-enum thinking value is asserted rejected. |
| PB-SPAWN-08 | child task prompt asks for a result under 2000 lines / 50 KB | T06 | Output truncation is asserted (spawn-runtime-compatibility.test.ts — "real child output is truncated at the public line limit"), but no test reads the built child prompt. What would seal it: assert the built prompt matches /Keep the result under 2000 lines \/ 50KB/ (natural home: spawn.test.ts — "spawn execute builds prompt with notebook pages and task"). |
|
| PB-SPAWN-09 | child starts in an in-memory session with its own context | T01 | ✅ asserted |
spawn.test.ts — "spawn execute passes broad active registered tool formula to child session" asserts sessionManager.isPersisted()===false, getSessionFile()===undefined, getEntries()===[]. |
| PB-SPAWN-10 | without a group, child uses parent's public model | T01, T15 | ✅ asserted |
spawn.test.ts — "spawn execute passes broad active registered tool formula to child session" (seenConfig.model.id===ctx.model.id, route inherited); model-groups-router.test.ts — "omitted and unknown groups inherit parent route with fallback metadata". |
| PB-SPAWN-11 | no group: explicit thinking used when supplied |
T01 | ✅ asserted |
spawn.test.ts — "spawn forwards requested thinking and reports the session effective thinking" (requested max reaches the child config unchanged). |
| PB-SPAWN-11 | no group: otherwise parent's current thinking level | T06 | ◐ partly asserted |
spawn-runtime-compatibility.test.ts — "real child completes through inherited/default thinking" runs the no-thinking path on the host default medium, but the non-reasoning model clamps the effective level to off, so the inherited value itself is not observable. Missing portion: assert the no-explicit-thinking path forwards the host's current level on a reasoning-capable model. |
| PB-SPAWN-12 | child starts in the parent's working directory | T01 | ✅ asserted |
spawn.test.ts — "spawn execute passes broad active registered tool formula to child session" (seenConfig.cwd==="/tmp", sessionManager.getCwd()===resolve("/tmp")). |
| PB-SPAWN-13 | child inherits active registered/executable parent tools incl. MCP/extension | T01 | ✅ asserted |
spawn.test.ts — "child tool names inherit active registered builtins and exclude recursive controls", "…MCP extension tools", "…project package and local extension tools", "…exclude inactive registered and active phantom tools", and "spawn execute passes broad active registered tool formula to child session" (active+registered filter). |
| PB-SPAWN-14 | child gets its own notebook tools | T01 | ✅ asserted |
spawn.test.ts — "spawn execute passes broad active registered tool formula to child session" (customTools = notebook_write/read/index, and present in tools); "child tool names exclude inactive registered and active phantom tools". |
| PB-SPAWN-14 | child notebook tools operate on the shared notebook state | T06 | ◐ partly asserted |
spawn-runtime-compatibility.test.ts — "real child prompt includes injected notebook pages" proves shared read (parent-seeded pages reach the child); no test drives a child notebook_write and asserts the shared page map mutates. |
| PB-SPAWN-15 | prompt lists available notebook page names, not bodies | T01, T06 | ✅ asserted |
spawn.test.ts — "spawn execute builds prompt with notebook pages and task" matches entry-a: preview line; spawn-runtime-compatibility.test.ts — "real child prompt includes injected notebook pages" and "…'No notebook pages.' branch when state is empty". |
| PB-SPAWN-16 | children cannot invoke spawn
|
T01, T28 | ✅ asserted |
spawn.test.ts — "child tool names inherit active registered builtins and exclude recursive controls", "buildChildToolNames (2-arg fallback) removes spawn and handoff from inherited tools"; readonly-spawn.test.ts — "buildChildToolNames excludes spawn and handoff from inherited tools". |
| PB-SPAWN-17 | children cannot invoke handoff
|
T01, T28 | ✅ asserted | Same exclusion tests as PB-SPAWN-16 (handoff filtered from the child tool list). |
| PB-SPAWN-18 | parent readonly ⇒ child write/edit unavailable |
T01, T28, T43 | ✅ asserted |
spawn.test.ts — "spawn execute composes Model Group routing with readonly child guards" (write/edit absent); readonly-spawn.test.ts — "filterReadonlyToolNames removes write and edit in readonly mode", "real readonly child omits write/edit…"; notifications.test.ts backs the readonly copy constants. |
| PB-SPAWN-19 | parent readonly ⇒ child bash uses the readonly guard |
T01, T28, T43 | ✅ asserted |
spawn.test.ts — "spawn execute composes Model Group routing with readonly child guards" (bash custom tool + readonly prompt copy); readonly-spawn.test.ts — "readonly bash guard blocks non-temp writes and allows temp writes", "real readonly child omits write/edit and blocks a non-temp bash write". |
| PB-SPAWN-20 | named group looked up by exact name (unknown ⇒ fallback) | T15, T03 | ✅ asserted |
model-groups-router.test.ts — "omitted and unknown groups inherit parent route with fallback metadata", "known empty and all-unusable groups fail clearly"; spawn-render.test.ts — "spawn result identity formats default routed and unknown fallback". |
| PB-SPAWN-20 | group name trimmed of surrounding whitespace before lookup | T01 | ◐ partly asserted |
spawn.test.ts — "spawn renderCall shows prompt preview and optional routing controls" shows a whitespace-only group renders as no group, but that is render-layer only. Missing portion: a router test asserting group:" review " resolves the review group (trim before the effective-group map lookup). |
| PB-SPAWN-21 | known group selects only registry-resolved + authenticated members | T15 | ✅ asserted |
model-groups-router.test.ts — "capability pre-selection excludes unauthenticated capable models and picks randomly from the capable set", "known empty and all-unusable groups fail clearly". |
| PB-SPAWN-22 | uniform random selection; no no-repeat rule between calls | T01, T15 | ✅ asserted |
spawn.test.ts — "spawn routes capability requirements to capable members via random selection on the filtered pool"; model-groups-router.test.ts — "routed empty modality requirements select by RNG across usable members" (exactly one RNG draw) and the 6-draw pre-selection test reaching both capable members. |
| PB-SPAWN-23 | declared requirements preferentially draw satisfying members | T15, T01 | ✅ asserted |
model-groups-router.test.ts — "required modalities prefer a capable member and still reject a wholly-incapable group", "capability pre-selection excludes unauthenticated capable models…"; spawn.test.ts random-pool routing test. |
| PB-SPAWN-24 | selected group entry's thinking overrides explicit/inherited | T01 | ✅ asserted |
spawn.test.ts — "spawn execute composes Model Group routing with readonly child guards" (entry low overrides requested xhigh). |
| PB-SPAWN-24 | entry thinking clamped to the selected model's capability | T15 | ◐ partly asserted |
model-groups-router.test.ts fixtures omit thinkingLevel on entries, so clampThinkingLevel is never driven against a stricter model. Missing portion: an entry whose thinkingLevel exceeds the selected model's capability, asserting the clamped route thinking. (spawn-runtime-compatibility.test.ts — "real child completes through inherited/default thinking" clamps the session's inherited level, not a routed entry.) |
| PB-SPAWN-25 | unknown group falls back visibly to parent model/thinking | T15, T03 | ✅ asserted |
model-groups-router.test.ts — "omitted and unknown groups inherit parent route with fallback metadata"; spawn-render.test.ts — "spawn result identity formats default routed and unknown fallback" (rev? fallback → openai/parent • medium). |
| PB-SPAWN-26 | known group with zero model entries fails group-specifically | T15 | ✅ asserted |
model-groups-router.test.ts — "known empty and all-unusable groups fail clearly" (reason empty). |
| PB-SPAWN-27 | known group with no usable/authed entries fails, no fallback | T15, T01 | ✅ asserted |
model-groups-router.test.ts — "known empty and all-unusable groups fail clearly" (reason no-usable-models); spawn.test.ts — "executeSpawn propagates unusable-group errors before creating child work" (factory not called, no session published). |
| PB-SPAWN-28 | default group modalities = union of member capabilities | T15, T18 | ✅ asserted |
model-groups-router.test.ts — "automatic mixed groups default effective to the union so a capability routes to a capable member"; model-groups-modalities.test.ts — "derives ordered common, supported, and override-effective modalities from the live registry". |
| PB-SPAWN-29 | explicit override narrows; cannot add unsupported modalities | T15, T17, T18 | ✅ asserted |
model-groups-router.test.ts — "explicit override stays a subtractive ceiling even when a capable member exists"; model-groups-constraints.test.ts — "fully stale non-empty modality overrides fall back to the union while explicit empty remains text-only"; model-groups-modalities.test.ts — "caps stale overrides without mutation and restores them when catalog support returns". |
| PB-SPAWN-30 | requirements checked against group effective AND selected model | T01, T15 | ✅ asserted |
spawn.test.ts — "registered spawn tool rejects injected scalar group and model requirements before publication" (constraintUnsatisfied.length===2); model-groups-router.test.ts — "required modalities prefer a capable member and still reject a wholly-incapable group", "explicit override stays a subtractive ceiling…" (missingFromGroup vs missingFromModel). |
| PB-SPAWN-31 | no known group ⇒ requirements checked against inherited parent model | T15, T01 | ✅ asserted |
model-groups-router.test.ts — "plain inherited route honors requiredModalities with empty-array no-op" (missing-modality against parent, group <inherited>); spawn.test.ts — "executeSpawn forwards inherited constraints to routing and succeeds when satisfied". |
| PB-SPAWN-32 | unknown constraint keys / malformed values fail before child | T01 | ✅ asserted |
spawn.test.ts — "executeSpawn rejects unknown requirements before factory or session publication" (factoryCalls 0, registries empty); "spawn requirements validate the canonical envelope and keep its shape"; "spawn tool schema validates constraints via Value.Check"; "registered spawn tool schema accepts injected scalar requirements". |
| PB-SPAWN-33 | unmet modality fails pre-child, reporting group and/or model miss | T01, T15 | ✅ asserted |
spawn.test.ts — "executeSpawn propagates missing modalities before creating child work", "registered spawn tool rejects missing modalities before creating child work"; model-groups-router.test.ts — "required modalities prefer a capable member and still reject a wholly-incapable group" (missingFromGroup). |
| PB-SPAWN-34 | selected public model → child runtime; failure does not reselect | T06 | ✅ asserted |
spawn-runtime-compatibility.test.ts — "spawn routes through the public registry but uses only the selected-model child session boundary" (source asserts model: childModel, no registry re-injection) and "a parent-transient selected model fails explicitly in the real child runtime without fallback". |
| PB-SPAWN-35 | result text = most recent assistant message containing text | T01 | ◐ partly asserted |
spawn.test.ts — "spawn execute returns result and stats" asserts the final text from the single assistant message; "spawn execute throws when child produces no output" covers the all-empty case. Missing portion: a trailing assistant message with no text (thinking/tool-call only) plus an earlier text-bearing message, asserting the earlier text is returned. |
| PB-SPAWN-36 | details carry effective thinking, outcome, truncation flag | T01, T06, T03 | ✅ asserted |
spawn.test.ts — "spawn execute returns result and stats", "spawn execute marks stats unavailable when stats collection throws"; spawn-runtime-compatibility.test.ts — "real child records an aborted outcome…"; spawn.test.ts — "spawn renderResult distinguishes aborted and error outcomes" (+ render-snapshots.test.ts aborted/error goldens). |
| PB-SPAWN-37 | details include token / turn / cost stats when available | T01, T06 | ✅ asserted |
spawn.test.ts — "spawn execute returns result and stats" (all stat keys) and "spawn execute marks stats unavailable when stats collection throws"; spawn-runtime-compatibility.test.ts — "real child publishes the session stats contract shape". |
| PB-SPAWN-38 | result text limited to first 2000 lines / 50 KiB UTF-8 | T01, T06 | ✅ asserted |
spawn.test.ts — "truncateText respects line limit before byte limit", "truncateText applies byte limit after line limit", "truncateText handles multi-byte boundaries correctly"; spawn-runtime-compatibility.test.ts — "real child output is truncated at the public line limit". |
| PB-SPAWN-39 | truncated result ends with visible shorter-summary advisory | T06 | ✅ asserted |
spawn-runtime-compatibility.test.ts — "real child output is truncated at the public line limit" matches [Result truncated to 2000 lines / 50KB. |
| PB-SPAWN-40 | routed result identifies group, provider/model, thinking | T03, T45, T01 | ✅ asserted |
spawn-render.test.ts — "spawn result identity formats default routed and unknown fallback" (review → openai/gpt-routed • high); render-snapshots.test.ts — "spawn result success matches snapshot"; spawn.test.ts route-details assertions in "spawn execute composes Model Group routing…". |
| PB-SPAWN-41 | unknown-group result visibly identifies fallback identity | T03, T45 | ✅ asserted |
spawn-render.test.ts — "spawn result identity formats default routed and unknown fallback" (rev? fallback → openai/parent • medium); render-snapshots.test.ts spawn-result-* goldens. |
| PB-SPAWN-42 | aborted child returns explicit aborted even with empty text |
T01, T06, T03 | ✅ asserted |
spawn.test.ts — "spawn execute swallows prompt rejection when signal aborts mid-flight" (outcome aborted, text ""), "spawn execute aborts child session when signal fires during execution"; spawn-runtime-compatibility.test.ts — "real child records an aborted outcome when the parent aborts mid-prompt"; spawn.test.ts — "spawn renderResult distinguishes aborted and error outcomes" + aborted snapshot. |
| PB-SPAWN-43 | non-aborted child with no assistant text fails Child agent produced no output.
|
T01, T06, T47 | ✅ asserted |
spawn.test.ts — "spawn execute throws when child produces no output"; spawn-runtime-compatibility.test.ts — "real child with no output triggers the 'produced no output' rejection"; basic.test.ts — "spawn tool errors gracefully without model infrastructure". |
| PB-SPAWN-44 | running child responds to the tool's AbortSignal
|
T01, T06, T07, T02, T37 | ✅ asserted |
spawn.test.ts — "spawn execute aborts child session when signal fires during execution", "…swallows prompt rejection when signal aborts mid-flight", "spawn invalidation wins the abort and prompt-rejection race"; spawn-runtime-compatibility.test.ts — "real child abort before prompt rejects without publishing a result"; abort-child-session.test.ts (promise dedup/throw handling); spawn-lifecycle.test.ts deduplicated abort; state-invariants.test.ts epoch guard behind reset-driven cancellation. |
| PB-SPAWN-45 | concurrent sibling spawns run independently, separate results | T01, T06 | ✅ asserted |
spawn.test.ts — "concurrent spawn executions produce independent results"; spawn-runtime-compatibility.test.ts — "concurrent real children both complete". |
-
PB-SPAWN-08 — no test asserts the child task prompt carries the "under 2000 lines / 50 KB"
instruction. What would seal it: read the built child prompt (e.g. via the
spawn.test.ts — "spawn execute builds prompt with notebook pages and task"capture ofseenPrompt) and assert it matches/Keep the result under 2000 lines \/ 50KB/.
Whole contract surfaces with no fixture: none — every other claim in this area has at least one representing fixture.
| Claims | Junction rows | ✅ | ◐ | |
|---|---|---|---|---|
| 45 | 49 | 41 | 7 | 1 |