6e2de33f26
`continue` returned "started" the instant `Claude::spawn` handed back a pid, and a resume that matched nothing only surfaced later, as an end-of-turn todo. By then the caller had moved on believing it had a running subagent. A pid is proof enough for `start`, which creates its session: the spawn succeeding is the whole story. It is not proof for a resume — claude exits non-zero a fraction of a second *after* the process exists. So `continue` now waits for the first real answer and reports a miss as its own `Err`, carrying claude's message and the directory searched. The wait ends on whichever comes first, so a successful `continue` pays no fixed delay: the turn's first non-terminal stream event settles it at about the same moment a miss's exit would have. Measured on this box: 14 runs of the driver's own invocation against a missing session took 550-1087 ms spawn to exit, and a healthy turn's first event lands at roughly 500 ms. The five-second cap is ~4.6x the slowest miss and is only ever reached by a child that neither speaks nor exits. The underway signal reads the event's kind, not its content: a missed resume is not silent — it emits a terminal `result` event and stderr before exiting — so "any sink callback" would have reported every miss as a successful start. Liveness still counts all three callbacks. The end-of-turn todo is unchanged for every failure later in the turn; the only one it no longer repeats is the miss the caller was just handed. Refs #4405
8.4 KiB
| name | description |
|---|---|
| claude-subagents | Spin up a short-lived headless `claude` sub-instance to grind through a well-scoped, mechanical batch (bulk relabeling, a repetitive find/replace, a mechanical migration) instead of burning your own context on it inline. Use this when a task has a clear, describable recipe and is either big enough to eat your context or long enough that you'd rather not babysit it. Not for judgement-heavy work, anything needing operator back-and-forth, or a task whose blast radius you can't bound up front. |
Ephemeral Sub-Agents
A sub-instance you spawn inherits the same filesystem and credentials you have. This is a first-class tool for offloading a bounded, mechanical batch.
When to use it
- Yes: mechanical batches with a clear recipe (relabel N issues, rewrite a call-site pattern, migrate a config field), especially when the batch would eat your context or take long enough that you'd rather not babysit it turn-by-turn.
- No: judgement-heavy work, anything needing back-and-forth with a human, or a task whose blast radius you can't bound up front.
The subagent MCP tools
Your container's subagent MCP server (hive-subagent-daemon) runs this
skill's recipe for you:
start(name, prompt_file, model?, effort?, trigger?)
continue(name, prompt, model?, effort?)
status(name)
interrupt(name, force?)
start and continue return once the turn is under way, not once it
finishes — a completion lands as a todo (get_loose_ends), same as any
other producer. continue takes the extra moment to confirm the resume
actually attached, so a continue naming a session that isn't there
fails the tool call outright instead of looking like it worked; the error
says which directory it searched, which is usually the fix (pass dir).
Use status for a
zero-cost "is it still going" check — for a running subagent it also
reports how long since that turn last produced output, so a few seconds
means it's working and an age climbing into the minutes means it's
wedged and worth an interrupt. Reach for continue only once you
actually have a new instruction for it, since that spends a turn.
interrupt genuinely stops a running turn (force: true for SIGKILL).
Model choice, prompt hygiene, splitting big batches, verify-then-report — everything else in this skill — applies exactly the same whether you're calling the tool or thinking through the recipe by hand.
Effort
An omitted effort defaults to medium here — cheaper than claude's own
model default (high on most models), a deliberate cost-conscious choice
for subagent work specifically, same spirit as "cheaper-than-you" model
choice above. Raise it explicitly when the task is complex enough to
actually need deeper reasoning, not as a reflex.
Anthropic's own levels (per current Claude Code docs — names/availability
are model-dependent, check before relying on an exact list): low,
medium, high, xhigh, max. Each trades token spend for capability:
low— short, scoped, latency-sensitive tasks that aren't intelligence-sensitive.medium— cost-sensitive work that can trade off some intelligence. This skill's default for subagent work.high— balances token usage and intelligence; Anthropic's own recommended default for most interactive coding tasks (not what this skill defaults subagents to — see above).xhigh— deeper reasoning at higher token spend.max— demanding tasks only; diminishing returns and overthinking are a real risk, per Anthropic's own guidance — don't reach for it as a default.
Anthropic's guidance: treat effort as a general preference, not a task-by-task dial — raise it if a subagent keeps skipping files, not running tests, or not double-checking its own work; lower it for routine work where quality hasn't suffered. Changing effort between turns on the same session invalidates prompt caching, so pick a level for the whole session rather than flipping it turn-to-turn.
Prompt hygiene - this is where batches succeed or fail
- Concrete constants, not "figure it out": exact ids, field names, option values, endpoints.
- Critical ordering rules, spelled out - the sub-agent won't infer invariants you don't state.
- Explicit scope + exemptions, plus a fallback rule for ambiguous cases: "leave it as-is where genuinely unclear; do not guess."
- Ask for a report file - per-item results + anything skipped and why, so you can verify without re-deriving.
- Tune on ONE item first, eyeball the result, fix the prompt, then turn it loose on the full batch. A prompt bug replicated across 100 items is 100 cleanups.
Split a big independent batch across parallel subagents
One subagent is a sequential worker — a 50-item batch takes roughly 50 items' worth of wall-clock even though nothing about the recipe forces serialization. If the items are independent (each one touches its own file/issue/row, nothing depends on another item's result) and the batch is big enough that wall-clock matters, chunk it across N subagents running at once instead of handing the whole thing to one.
- Split by natural boundaries, not an arbitrary item count — one subagent per file, per directory, per module, per label, whatever grouping keeps each worker's slice self-contained. A worker that has to coordinate with another worker mid-task isn't actually independent work; re-scope the split until it is.
- Isolate each worker's writes. For a git-based batch, give each
worker its own
git worktree(own working directory, own branch, same underlying repo — cheap, no full reclone) so N workers editing different files never race on the same working tree or index. For a non-git batch (issue relabeling, API calls), independent items don't need filesystem isolation at all — just launch N in parallel. - Launch all N and don't babysit any single one — same as the
one-subagent case, just N
startcalls instead of one. Check on them as a batch, not by polling each individually in a loop. - Mind the container's memory cap before picking N. Your whole
container shares one
MemoryMax(a few GB by default) with every subagent you spawn and your own process. Aclaudeprocess plus its MCP servers can hold several hundred MB to ~1GB depending on the task; spawning a dozen at once on a small container doesn't just slow things down, it can OOM the whole container — taking your own in-flight turn down with it, not just the subagents. Rule of thumb: 2-4 concurrent workers on a default-sized container; checkfree -h(or ask whoever owns the container's config for itsMemoryMax) before going higher, and chunk a bigger batch into successive waves of that size rather than firing everything at once. - You own the merge. Once all N report done, review + verify each worker's slice (same "don't trust the self-report blind" rule as below), then combine — for a git-based split, that's you merging N branches (or cherry-picking) into one, not each worker pushing/PRing its own slice.
Skip this for a batch small enough to finish in a couple minutes single- threaded — the coordination overhead isn't worth it below that size.
Resume for follow-ups
continue reuses the same session, so the sub-agent keeps every constant
and gotcha it already discovered instead of re-learning the surface from
a cold prompt. Reach for start under a new name only for a genuinely
unrelated task.
Verify, then report
On completion: read the report file, spot-check a handful of results yourself (don't trust the self-report blind), then summarize. Surface anything the sub-agent left ambiguous or exempted for a human call.
Pitfalls (all observed in practice)
- Using a model bigger than yourself → paying premium cost for mechanical work that didn't need it.
- Skipping the one-item tuning pass → a systematic mistake smeared across the whole batch.
start-ing fresh instead ofcontinue-ing for a follow-up → throws away all the context the first pass earned.- Baking an unverified assumption into the recipe - if a quick check suggests something "isn't possible" or "doesn't exist," confirm it before writing that conclusion into the prompt; a wrong assumption gets replicated across the whole batch.
- Handing a big independent batch to one subagent instead of splitting it across several in parallel - a 50-item sequential run burns wall- clock the split-by-worktree approach above would've avoided for free.