Subagents from first principles

Skills gave you a procedure that loads on demand instead of sitting in every system prompt - the onboarding checklist for a new content source, pulled into context only when a new source actually shows up. That solved the always-loaded half of the context problem. It didn’t solve the other half: even a skill that loads on demand still loads into the one window you’re sitting in. Everything Pi does for you, it does inside that same context, competing for the same budget, one turn at a time.

stash now has a job that doesn’t fit in one window at all, no matter how little you load into it. Every article saved before you fixed the readability extractor is sitting in the database with mangled, nav-cluttered text - hundreds of them, each one independent of every other, exactly the kind of work that drowns a single context in file dumps and dead-end greps without ever needing your judgment.

That’s the first half of this module’s problem. The second half shows up once you’ve solved the first. The moment work happens in a window you can’t see into, you’re stuck trusting whatever comes back out of it. A child process finishes and reports “re-extracted, index updated.” Was it? The extractor still mangles some sites even after your fix. Search still drops accented characters sometimes. A report and the truth are two separate claims, and putting the work in its own window doesn’t make them the same claim - it just makes the gap between them harder to see.

Name it: one window cannot hold the job, and isolation costs you the handoff. Split the job across windows and you buy back room to work. What you pay for that room is a handoff - a report you didn’t watch get produced, standing in for work you didn’t watch happen. Call that cost the handoff tax. Every pattern in this module - one child, a chain of them, a fan-out of dozens, a verifier watching another agent’s work - pays that tax somewhere. What this module actually teaches is what you get for it, and where it lands.

Other coding agents hand you a built-in answer to both problems - a Task tool, typed subagent roles, a delegation API you call and trust. Pi hands you none of that. No subagent tool, no roster, no dispatcher. Every flavor of Pi multi-agent work you’ll ever see - dispatcher teams, sequential pipelines, background workers, parallel research fan-outs - is the exact same twenty-line idea underneath: spawn a second pi process, tell it to run headless, read its output as it streams. That’s not a workaround for a missing feature. It’s the feature, disassembled, and building it yourself once is the fastest way to actually understand what a subagent is instead of just trusting a black box that says “delegating to subagent.”

This module builds that primitive and spends its cost on the two problems above:

• Spawn a child Pi and read its JSONL - the one mechanism every multi-agent pattern in this module is built from.
• Chain agents in sequence, then fan a big job out in parallel - clear the whole re-extraction backlog without burning your own context on it, and pay the handoff tax on purpose instead of by accident.
• Build a verifier that doesn’t trust the builder - a second agent that reads the first one’s transcript instead of its summary, and - because it has no way to chat back - is forced to write what it learns down as a durable rule instead of a one-off reply.

By the end you’ll know exactly what isolation buys you and exactly what it costs, on both sides of the handoff. Start with spawning your first child agent.