platform/todo/sub-agents/an-api-endpoint-for-spawning-an-agent-with-a.md

id, title, theme, status, created, date_source, order

id	title	theme	status	created	date_source	order
sub-agents/an-api-endpoint-for-spawning-an-agent-with-a	An API endpoint for spawning an agent with a prompt	sub-agents	open	2026-08-21	stated	1

An API endpoint for spawning an agent with a prompt. Wanted 2026-08-21. An agent calls it, names a prompt, and gets another agent running. A sub-agent system — but defined by the owner, which is the whole point of building one rather than leaning on the harness's own: the shapes, the limits and the vocabulary are Officer's, so every harness gets the same door and the definition does not change when a CLI does.

It has more of a starting point than it looks. startClaudeTurn already runs a turn with no browser attached (nudger.ts:102, ws: null), so the mechanism for "run an agent from the backend" is proven — what is missing is spawning a NEW one on request rather than feeding a known session, plus the surface an agent can actually call, which is MCP or an authenticated route.

Open: whether a spawned agent is a Command HQ commander (named, listed, costed — command_hq_sessions already does all three) or something lighter that disappears when it finishes; how its output returns to the caller, streamed or awaited; and what the caller may set — model, effort, cwd, permission mode — versus what Officer fixes.

Bounded by the budget rule in sub-agents/spawning-must-respect-the-account-s-own, which is not optional. An endpoint that spawns freely is exactly how a weekly limit gets spent by something nobody was watching.