Programmatic sub-agent dispatch API — design discussion + two reference implementations #829

First — huge appreciation for the recent sub-agent wave (b77a25f queue, a31d5c5 resume, 2661247 worktree isolation, e3fbbf6 extension tool selectors, e83f4b5 cascade delete, 0ff1138 session-lease keep-alive, …). It clearly covers most of the ground we'd been exploring on our fork, and reading through it changed some of what we're proposing.

The gap we'd like to discuss. Everything above is driven through the chat surface (the Agent tool + profiles). What's still missing for us is a programmatic entry point: an in-process API that lets trusted server-side extensions (our use case: a task-runner adapter living inside the pi-web process) start, steer, and settle sub-agent runs without going through a chat turn.

Sketch (as implemented on our branches):

• registerDispatchRuntime() exposes a versioned globalThis.__piSubagentDispatch with startSubagentDispatch(parentSessionId, params)
• per-dispatch controls that layer on top of profiles: tools / disallowedTools, extensions / denyExtensions (source-aware filter keys: npm package names, or basename for file-path extensions), excludeTools (reserved control names always excluded)
• lifecycle events (started -> completed/aborted) carrying the authoritative effective values (model / thinking / active tool set) resolved by the runtime — not echoes of the request
• per-dispatch persistSession: false -> child runs on an in-memory SessionManager (nothing hits disk), with the run's audit metadata redirected to the parent session
• deliberately no concurrency policy: queueing and per-parent limits belong to SubagentQueue; we dropped our own cap implementation entirely

Two reference implementations, same behavior contract, different structure — happy to rework whichever you'd merge, or close both if this doesn't fit the roadmap:

• incremental: https://github.com/northwang-lucky/pi-web/tree/feat/subagent-dispatch-api (5 commits)
• unified resolution pipeline: https://github.com/northwang-lucky/pi-web/tree/feat/subagent-dispatch-api-pipeline (5 commits)

Both branch off current main (8366762), share a byte-identical dispatch contract suite, and land at 1064 / 1065 tests green (upstream 1020 + ours; tsc / eslint clean). Validated live against a real model: foreground dispatch round-trip, non-echoed effective values, persistSession:false leaves no .jsonl with audit on the parent, and the profile-level fallback.

One honest note from building this: while wiring the ephemeral audit redirect we hit two pre-existing UX issues unrelated to the dispatch work — silent stopReason: "length" truncation, and wake-round visibility. The second one your 0ff1138 lease design already solves (we verified on a real background tab and dropped our patch). The first one is a small standalone PR: #830

Would a programmatic API like this be welcome upstream — and if so, does one of the two structures fit better? Also unsure whether the frozen contract-suite test style we used would fit your review habits; happy to adapt.