M01
Chapter 1: The Seam — One Pi Session Becomes a Fleet
Draw the ownership boundary between Pi's runtime primitives and the orchestration layer added by pi-subagents.
A source-guided field guide
Pi Subagents,
from the rock layer up.
Learn how an extension turns ordinary Pi sessions into an observable fleet—without inventing a second agent loop. Every implementation claim traces to a fixed source baseline.
- Extension
- pi-subagents 0.18.0 · 3f9d35c
- Foundation
- Pi 0.84.2 · 914cf14
runtime trace one process
- 01 Pi extension hostloads one factory
- 02 AgentManagerowns records + policy
- 03 Parent AgentSessioncalls the Agent tool
- 04 Child APi AgentSession Child BPi AgentSession Child CPi AgentSession
The fleet layer coordinates. Pi still executes every model turn and tool call.
The governing distinction
Keep the ownership line visible.
Most architectural mistakes disappear once each behavior has one named owner.
Pi owns
- model and tool loop
- AgentSession and persistence
- extension lifecycle and events
- TUI and UI primitives
pi-subagents adds
- agent registry and spawn policy
- records, queueing, and ownership
- nested capabilities and result routing
- fleet projections and control surfaces
The learning path
Nine source-guided chapters. Read in order once; return by boundary when you investigate the code.
M02
Chapter 2: The Tool Boundary — Turning Delegation into a Pi Tool
Follow the extension factory, tool definition, registration, and execute contract that makes delegation model-callable.
M03
Chapter 3: The Child Session — Building on createAgentSession
Assemble resources, persistence, model policy, tools, extensions, and a prompt into one real child AgentSession.
M04
Chapter 4: The Fleet — Lifecycle and Concurrency
See how AgentRecord and AgentManager coordinate an observable fleet, while a ten-slot pool admits ordinary top-level background work and nested work bypasses it to avoid dependency deadlock.
M05
Chapter 5: Runtime Control — Steering Without Owning the Loop
Control a Pi-owned run through events, steering, aborts, resume, turn limits, and a finite child-session shutdown boundary.
M06
Chapter 6: The Capability Membrane — Resolving Effective Authority
Resolve configuration precedence and follow tool, extension, prompt, context, and worktree policy to the runtime boundary.
M07
Chapter 7: The Ownership Tree — Ownership-Scoped Nested Delegation
Treat nested delegation as an opt-in runtime ownership boundary, not as a prompt convention or inherited sandbox.
M08
Chapter 8: The Return Path — Results Become Product Surfaces
Follow settled child outcomes through foreground inline return or background delivery, retrieval, grouped notifications, events, and Pi TUI projections.
M09
Chapter 9: The Evidence Trail — Persistence, Failure, and Verification
Compare persistence artifacts by owner and guarantee, classify failure evidence, and trace an unfamiliar feature without outrunning the tests.