pastilhasandClaude Opus 5
ff7358188d
The failure this prevents is specific — a sub-agent burns the end of a limit window and the session the owner is actually sitting in dies mid-turn, because the credits went somewhere nobody was watching. So it is a condition on spawning rather than a refinement: an endpoint that can start unattended work without checking is wrong from its first call, and the symptom lands on someone else's conversation. Wired into POST /command-hq/commanders/new, which — this is the finding — already IS the spawn mechanism the sub-agents item was asking for. It starts a turn with ws: null, waits only for session:claude, and returns the transcript id, with command_hq_sessions naming, listing and costing it. So "commander or something lighter" answers itself: a commander costs nothing extra and a lighter thing would need its own registry to be visible at all. What is still missing is only the agent-callable surface. Refuses rather than queues or downgrades. Queueing means holding work against a window Officer does not control, and the reset it would wait for is a claim about a shared pool — every claude on the machine spends these, including terminals and pipelines. A refusal naming the window, the percentage and the reset is something a caller can act on now. The floor is 15% and the reasoning is in the file: the interactive failure is not "cannot start a chat", it is "a turn already in flight is cut off", and a turn costs a fraction of a window. Fails OPEN, deliberately. The numbers come from an external endpoint with a credential Officer does not own, so a blip or a signed-out CLI must not stop every spawn on the machine with an error about usage that has nothing to do with usage. The problem is reported so a caller can say "started, but unchecked". Seven tests on the pure rule — tightest window decides rather than the average, no limits allowed rather than blocked, exactly-at-the-ceiling refuses. Verified against the live account, where it correctly refuses right now at Session 90%. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
46 lines
2.4 KiB
Markdown
46 lines
2.4 KiB
Markdown
---
|
|
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.
|