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 text on that date. Not tested at runtime unless the row says so.
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: false when 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 SendMessage a 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. Pass model to 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 ListAgents before 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)
A 4.6 Igor passing `model: "opus"` to the then 4.6-pinned Athanor got a 4.6 run (the dirigent end review that passed with zero findings).	observed 2026-10-05 (user's attribution; the dirigent report recorded the model as unknown). Consistent with both the alias following the caller and the pin holding, so it is not evidence for alias-over-pin. The 184/184 row and the schema are.
What the `opus` alias resolves to (the caller's model, a session default, or the newest Opus).	unknown. Check the stamped id of every plan, attack and review instead of relying on it.
Every agent sees its exact model id in its system prompt.	observed 2026-10-05 for general-purpose agents (prompt shows `claude-opus-5-5`); not checked for plugin agents with their own bodies
Context window of the bare `claude-opus-5-5` pin versus a `[1m]` suffix (other Spire pins carry `[1m]`).	resolved 2026-10-05: all Opus-pinned Spire agents (igor, adept, athanor, zathras) pinned to `claude-opus-5-5[1m]` (user decision; Pinky, when it exists, stays 4.6); the ~600k guesstimate in `models.md` assumes the larger window

Fork

Claim	Status
The Agent tool schema documents `subagent_type: "fork"`: a fork always inherits the caller's model; the `model` parameter is ignored.	verified 2026-10-05 (schema text)
`fork` is actually offered as an agent type in a given session.	unverified: the schema mentions it, but on 2026-10-05 it was not in the list of agent types offered to the reviewer
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)

7.0 KiB Raw Blame History