Skip to content

Spec2Contract Spawn

Grzegorz Nowak edited this page Oct 10, 2026 · 2 revisions

Spec-to-contracts — Spawn (book ↔ in-tests contracts)

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.

Junction rows

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 ⚠️ no test yet 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".

Empty surfaces in this area

  • 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 of seenPrompt) 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.

Area coverage summary

Claims Junction rows ✅ ◐ ⚠️
45 49 41 7 1

Clone this wiki locally