---
id: sub-agents/an-api-endpoint-for-spawning-an-agent-with-a
title: "An API endpoint for spawning an agent with a prompt"
theme: sub-agents
status: open
created: 2026-08-21
date_source: stated
order: 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.


---

**2026-08-21, narrowing this considerably.** The endpoint largely exists:
`POST /api/command-hq/commanders/new` takes a prompt, starts a turn with `ws: null`, waits only for
`session:claude` rather than the whole turn, and returns Claude's own transcript id. A commander is named,
listed and costed by `command_hq_sessions` already.

So the open question "commander or something lighter" answers itself from the code: making a spawned agent
a commander costs nothing and gets all three for free, where a lighter thing needs its own registry to
become visible at all. **The budget condition is now on that route**, so anything spawned through it
already respects the window.

What is genuinely left is the SURFACE an agent can call — MCP tool or authenticated route — and how output
returns to the caller. That is the remaining work on this item; the mechanism underneath it is done.