72 lines
6.9 KiB
Markdown
72 lines
6.9 KiB
Markdown
# 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) |
|
|
| 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) |
|