g4borg
e51520723c
The implementation skill now states the lean loop: attack the plan against the code before building, build phases in blocks with a cheap gate between them, test and review once per phase, one fix pass, stop. Harness mechanics, model observations and the run-log template move to references with dated, sourced claims. The Athanor becomes a build furnace pinned to claude-opus-5-5: one phase per turn, no planning, no plan attack, no self-review. It no longer preloads superpowers; those skills stay available as tools.
6.2 KiB
6.2 KiB
Spawning agents in Claude Code
Harness mechanics for dispatching, resuming and forking agents in Claude Code. Other harnesses get their own spawning-<harness>.md when needed.
Each claim carries a status and a date:
- verified: read from the tool schema or checked directly, on that date.
- observed: seen in real runs; the mechanism may be assumed. Source given.
- assumed: inferred, not checked. Treat as a hypothesis.
- unknown: open; check before relying on it.
The harness changes. When a claim fails, fix it here with a new date.
Rules of thumb
- Foreground for sequential work. Pass
run_in_background: falsewhen the next step depends on the result. Background only for independent leaves whose result can go to the session root. - Resume only from the session root. Igor may
SendMessagea finished agent (the Athanor between phases, an adept). A subagent should not resume its own children; it dispatches fresh foreground agents instead. - Pinned agents: omit
model. The per-call alias overrides the agent's frontmatter pin. Passmodelto a pinned agent only when you mean to override it, and say so in the journal or run log. - Unpinned agents: pass
model. Otherwise they inherit the caller's model, which may be Fable. - Stamp the model id. Every agent reads its exact id from its system prompt and writes it into its output.
- Leaf briefs say "do this yourself; do not dispatch further agents." Only orchestrators (the Athanor) are meant to fan out.
- Notifications report a turn ending, not a job finishing. Read the result text before concluding anything. Check
ListAgentsbefore resuming.
Dispatch and notification
| Claim | Status |
|---|---|
Agent calls run in the background by default; run_in_background: false runs them in the foreground and returns the result to the caller. |
verified 2026-10-05 (Agent tool schema) |
| Background children of a subagent notify the session root, not their parent. The parent sees nothing and stalls until the root feeds it the result. | observed 2026-09-24 and 2026-09-28 (spacecraft journals, "athanor stalled twice … nudged with results"); dirigent memory, settled 2026-09-29. Mechanism assumed. |
An agent that hands work to a background child and then yields notifies completed at once, before any deliverable exists. Expect one more notification per background grandchild, each with its own task-id. |
observed 2026-09-22 (Spire harness notes) |
The same task-id may notify more than once (one per turn). Track the deliverable, not the count. |
observed 2026-09-22 |
Background grandchildren show up in ListAgents as flat, top-level agents of the session. If one is still writing your output path, do not resume its parent: that starts a second writer. TaskStop the child first if you mean to abandon it. |
observed 2026-09-22 |
TaskList is the todo list, unrelated to agents. TaskOutput on an agent dumps its whole transcript into your context; do not use it for agents. |
observed 2026-09-22 |
A general-purpose agent has the Agent tool and will delegate if its brief reads like an orchestration brief. |
observed 2026-09-22 |
Resume
| Claim | Status |
|---|---|
SendMessage to a finished agent's name or id resumes it with its context intact. A new Agent call starts fresh. |
verified 2026-10-05 (Agent tool schema) |
| A resume issued from inside a subagent runs in the background; its completion goes to the root and the subagent stalls. From the root (Igor) it is safe, because the root is where the notification lands. | observed once 2026-10-05 (spacecraft journal: orchestrator resumed its implementer via SendMessage, went background, yielded). Mechanism assumed from the routing above. |
Models
| Claim | Status |
|---|---|
The per-call model parameter accepts aliases only (opus, sonnet, haiku, fable) and takes precedence over the agent definition's model frontmatter. |
verified 2026-10-05 (Agent tool schema) |
With model omitted, a pinned agent runs on its pin; an unpinned agent inherits the caller's model unless a default subagent model is configured. |
verified 2026-10-05 (Agent tool schema) |
A full model id (e.g. claude-opus-5-5) can only be set in the agent definition's frontmatter, so pinning by full id means a pinned agent dispatched without model. |
verified 2026-10-05 (follows from the alias-only parameter) |
The opus alias overrode 4.6 pins in 184 of 184 spawns (they ran on 5.5). |
observed 2026-09-27 (spacecraft MVP retrospective) |
Passing model: "opus" gave the Athanor the model Igor was running on: a 4.6 Igor produced a 4.6 Athanor (the dirigent end review that passed with zero findings). |
observed 2026-10-05 (user's attribution; the dirigent report recorded the model as unknown). How the alias resolves is assumed, not checked: it may follow the caller's model or a session default. Either way the alias, not the pin, decided. |
| Every agent sees its exact model id in its system prompt. | verified 2026-10-05 (this agent's prompt shows claude-opus-5-5) |
Fork
| Claim | Status |
|---|---|
subagent_type: "fork" exists. A fork always inherits the caller's model; the model parameter is ignored. |
verified 2026-10-05 (Agent tool schema) |
| A fork copies the caller, not an arbitrary agent. Only the agent holding a context (e.g. the Athanor as trunk) can fork it. | assumed (no parameter names a fork source; Igor's skill calls it "forking yourself") |
| A fork starts with the caller's full transcript, so it starts at the caller's token count. | assumed, not measured |
| Can a fork fork again? Does a foreground fork return its result to the caller? Does it see the caller's preloaded skills? | unknown; check in a throwaway preflight before relying on trunk and forks |
Agent types
| Claim | Status |
|---|---|
Plugin agent types (athanor, adept, researcher, …) can be missing in remote sessions, where /reload-plugins is not available. Fallback: general-purpose with an explicit model, and the agent file's body pasted into the brief. |
observed 2026-10-05 (reliquary Igor journal, 21:00) |
Explore and Plan are read-only (no Edit/Write). Do not use them for tasks that must write a file. |
observed 2026-09-22 (Spire model tiers) |