reliquary/plugins/spire/skills/implementation/references/spawning-claude-code.md

# Spawning agents in Claude Code

Harness mechanics for dispatching, resuming and forking agents in Claude Code, and for the headless sessions (`claude -p`) that `spire:gremlins` drives. 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 the Claude Code docs, or reproduced in a local test, on that date; the row names which. 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.
- **Complex blocks go to gremlins via `spire:gremlins`; never resume or fork a headless session by hand.** The helper owns the flags, the cache bookkeeping and the usage ledger (see "Headless sessions" below).
- **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 |
| Headless `--model` takes full ids (and the `[1m]` suffix), so gremlins pin by full id; the per-call alias limit above is an Agent-tool limit. | observed 2026-10-16 (preflight report, P0.5) |
| 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 (Agent tool)

Spire no longer uses Agent-tool forks (goal decision 2026-10-16): complex blocks go to gremlins, headless forks of a trained base (see "Headless sessions" below). The rows stay as a record of what the Agent tool offers.

| 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` was not offered as an agent type on 2026-10-05 or on 2026-10-15. | observed 2026-10-15 (agent-type lists of those sessions; design 2026-10-16-01 §9) |
| A fork inherits the current conversation only; no parameter names another agent to fork. | verified 2026-10-15 (docs, sub-agents) |
| A fork has the same system prompt, tools, model and history as the forking session. | verified 2026-10-15 (docs, sub-agents) |
| An Agent-tool fork cannot fork again: "A fork can't spawn further forks." A headless `--fork-session` of a fork works. | verified 2026-10-15 (docs, sub-agents) for the Agent tool; verified 2026-10-16 (research `2d`, local test T6) for headless |
| Fork mode is on by default in interactive sessions (v2.1.232 and later), off under `-p` and the SDK unless `CLAUDE_CODE_FORK_SUBAGENT=1`. With it on, all subagents run in the background and `run_in_background` is removed. | verified 2026-10-15 (docs, sub-agents) |
| Agent-tool forks and subagents use the 5 min cache bucket by default; the main conversation (including `-p` runs) gets 1 h on a Claude subscription within plan usage. | verified 2026-10-16 (research `F4a`; docs, prompt caching) |
| Whether a foreground Agent-tool fork returns its result to the caller, and whether it sees the caller's preloaded skills. | unknown 2026-10-16 (never tested; Spire does not use Agent-tool forks) |

## Headless sessions (`claude -p`)

`spire:gremlins` (command `spawn`) is the only supported way to start, resume or fork one; these rows say why its command line is what it is. Tested on Windows with `claude` 2.1.283 and 2.1.299. Research ids (`1a` to `F5b`) refer to `docs/workpad/research/2026-10-16-00-claude-headless-fork-sessions.md`; `P0.x` ids to `docs/workpad/reports/2026-10-16-09-headless-forks-preflight.md`.

| Claim | Status |
|---|---|
| `--output-format json` prints one result object: `session_id`, `result`, `usage` (with the cache fields), `modelUsage`, `total_cost_usd`, `permission_denials`, `subagent_stats`. With `stream-json --verbose` the first event is `system/init` with `session_id`, `model`, `tools`, `agents`, `skills`, `plugins`, `permissionMode`. | verified 2026-10-16 (research `1a`; docs, headless; local tests T1, T6) |
| `--resume <id>` finds the session by id in any project on the machine; without `--fork-session` it appends to the same id. | verified 2026-10-16 (research `1b`; docs; local test T5) |
| `--session-id <uuid>` lets the caller choose the id up front, so no output parsing is needed. | verified 2026-10-16 (research `1d`; docs, `--help`) |
| `--continue` means the most recent conversation in the cwd, `-p` sessions included. Do not use it for fan-out; pass explicit ids. | verified 2026-10-16 (research `1c`; docs) |
| `--fork-session` gives the run a new session id and a copy of the base history. | verified 2026-10-16 (research `2a`; `--help` 2.1.283; docs) |
| The base stays unchanged on disk and in later resumes; forks do not see each other. | verified 2026-10-16 (research `2b`; docs, sessions; local tests T2 to T5) |
| Parallel forks of one base work and each gets its own id and transcript. Resuming the same id in two processes without forking interleaves both into one transcript. | verified 2026-10-16 (research `2c`; local tests T2 and T3 in parallel; docs) |
| A fork of a fork works. | verified 2026-10-16 (research `2d`; local test T6) |
| Forks hit the cache on the shared prefix (T2 and T3 each read 14,650 tokens against the base's 8,661 created). | verified 2026-10-16 (research `3a`; local test) |
| A cache hit needs an identical tool set, model and system prompt. A fork with different flags read 0 and re-created 17,474; one that changed only the model read 4,293 and created 7,213. | verified 2026-10-16 (research `3b`; local tests T6, T7) |
| A fork does not inherit the base's permission mode, `--allowedTools` or `--tools` (T6 came up in `default` with all 43 tools). Pass them again, identically, on every fork. | verified 2026-10-16 (research `4b`; local test T6; docs, sessions) |
| Also not restored on resume: `--mcp-config`, `--settings`, `--plugin-dir`, `--fallback-model`, `--add-dir`. The system prompt (including `--append-system-prompt`) is recorded at the first request and reused on resume and fork until compaction; later flag text is ignored (`--system-prompt-snapshot`, `--help` 2.1.283). | verified 2026-10-16 (research `4c`; docs, sessions and CLI reference) |
| The model is restored on resume; `--model` on the fork overrides it (a haiku fork of a sonnet base ran on haiku). | verified 2026-10-16 (research `4d`; docs; local test T7) |
| `total_cost_usd` and `modelUsage` on a resumed or forked run are cumulative for the conversation, base spend included (v2.1.277 and later). Per-call cost is a difference against the base's total; never sum results. `--max-budget-usd` counts only the call's own spend. | verified 2026-10-16 (research `3d`, `F4e`; docs, headless, cost tracking) |
| The 1 h cache TTL is the default only for the main-conversation bucket (interactive turns and `-p` runs) on a Claude subscription within plan usage; usage credits, API key and cloud providers default to 5 min, as does the main conversation over the plan limit. | verified 2026-10-16 (research `F4a`, `3c`; docs, prompt caching; local `ephemeral_1h` writes in T1 to T7) |
| The TTL is configurable: `CLAUDE_CODE_PROMPT_CACHE_TTL` or `promptCacheTtl` (main bucket), `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` or `subagentPromptCacheTtl` (everything else), each `5m` or `1h`, v2.1.242 and later. `ENABLE_PROMPT_CACHING_1H=1` sets both; `FORCE_PROMPT_CACHING_5M=1` overrides everything. | verified 2026-10-16 (research `F4b`; docs, prompt caching) |
| A cache hit resets the TTL timer, so forks spaced under the TTL keep the base prefix warm. Parallel sessions in the same directory share a prefix; a different cwd or git-status snapshot changes it, so run every fork from the base's cwd. | verified 2026-10-16 (research `F4c`, `F4d`; docs, prompt caching) |
| Under `-p` nothing can prompt: without a host or `--permission-prompt-tool`, anything that would prompt is denied, listed in `permission_denials`, and the run continues. `dontAsk` denies anything not pre-allowed. | verified 2026-10-16 (research `4a`; docs, headless and permission modes) |
| `system/init.model` is not the model that ran: read `modelUsage` or `assistant.message.model`. | verified 2026-10-16 (research `5d`, `F2a`, `F2c`; local tests M1, M2) |
| `--permission-mode plan` upgrades a Haiku session to Sonnet. The docs imply it (availableModels section) and do not state it as a rule. | observed 2026-10-16 (research `5d`, `F2a`, `F2b`; local tests T1 to T5, M1, M2; docs only indirect) |
| Aliases resolve by CLI version: `haiku` is Haiku 4.5 on 2.1.283 and Haiku 5.5 on 2.1.299 (Haiku 5.5 needs v2.1.293 or later, Sonnet 5.5 v2.1.284 or later). | verified 2026-10-16 (research `F2c`; local tests; docs, model config) |
| Without `--bare`, `-p` loads installed plugins, skills, agents, hooks, MCP and CLAUDE.md like an interactive session. | verified 2026-10-16 (research `5a`; docs; local test T6) |
| `--bare` skips all of that discovery and refuses OAuth (`Not logged in`); it needs `ANTHROPIC_API_KEY`. | verified 2026-10-16 (research `5b`, `F3d`; docs; local test E2) |
| `--model` (alias or full id), `--agents`, `--agent`, `--append-system-prompt[-file]`, `--settings`, `--max-budget-usd`, `--max-turns` and `--json-schema` exist in 2.1.283. | verified 2026-10-16 (research `5c`; `--help`; docs) |
| A nested `claude -p` inherits `CLAUDECODE=1` and `CLAUDE_CODE_CHILD_SESSION=1`; no recursion guard blocks it, and the session is still persisted. | verified 2026-10-16 (research `6a`; docs, env vars; local env listing) |
| Agent depth is counted per process from its main conversation; the parent's depth is not passed down. A nested `claude -p` can use the Agent tool, and a second level nests too. At the depth limit the Agent tool is simply absent: no error. | verified 2026-10-16 (research `F1a` to `F1d`; local tests D1 to D3; docs, env vars) |
| A nested process does not count against the parent's Agent depth or concurrency caps. | assumed 2026-10-16 (research `6b`; inferred from per-process `subagent_stats`, not tested with a deep parent) |
| `--bg` does not combine with `-p`. | verified 2026-10-16 (research `6c`; docs, headless) |
| A headless run is invisible to the parent's task notifications, `ListAgents` and `TaskStop`: the orchestrator must block on Bash or poll. | assumed 2026-10-16 (research `6c`; not a tracked Agent, never tested from a subagent) |
| Transcripts land in `~/.claude/projects/<cwd with every non-alphanumeric character as '-'>/<session-id>.jsonl`, one file per fork, each holding the copied base history under its own `sessionId`; 30-day retention. | verified 2026-10-16 (research `6d`; docs, sessions; local listing) |
| The nested process inherits the Desktop host's env: `CLAUDE_CODE_MESSAGING_SOCKET`, `CLAUDE_CODE_ENTRYPOINT=claude-desktop` and the OAuth-refresh variables, among others. Removing twelve of those vars (`F3a`) with `env -u` drops the Artifact tools (35 to 32 built-ins); auth still works. | observed 2026-10-16 (research `6e` as corrected by `F3a`, `F3b`; local tests T6, E1) |
| The `messaging_socket_path` in `system/init` is the nested process's own pipe, different on every run and never the host's. This corrects the first reading of `6e`. | verified 2026-10-16 (research `F3c`; local tests T6, E1) |
| Whether the nested process's pipe can reach the host app, and which single env var gates the Desktop Artifact tools. | unknown 2026-10-16 (research `F3c`; not isolated) |
| The PATH `claude` (2.1.283, native installer) and the Desktop host's bundled `claude.exe` (2.1.299, reachable as `$CLAUDE_CODE_EXECPATH`) are separate installs. | verified 2026-10-16 (research `F5a`; local) |
| A fork made by another binary or on another model misses the base's cache: a 2.1.299 fork of a 2.1.283 base read 0 and created 15,020. Pin one binary and a full model id for the base and all its forks. | verified 2026-10-16 (research `F5b`; local test V1; docs, prompt caching) |

Observed in the Phase 0 preflight on this Windows host (2026-10-16):

| Claim | Status |
|---|---|
| `uv run` adds `VIRTUAL_ENV` and a venv `Scripts` entry at the head of PATH, and sets no `UV_*` vars; stdout stays clean (one JSON line). | observed 2026-10-16 (preflight report, P0.0) |
| No job objects on this host (`IsProcessInJob` false for the `uv run` launcher and every supervisor). | observed 2026-10-16 (preflight report, P0.1) |
| The Bash tool's `TaskStop` kills by process tree (parent links). A supervisor created through CIM `Win32_Process.Create` (parent `WmiPrvSE.exe`) survived the stopped Bash call; rungs that start it as a child of the launcher died with it. | observed 2026-10-16 (preflight report, P0.1) |
| A supervisor surviving the end of the agent's turn (the hand-back) was not tested in Phase 0; the parentage under `WmiPrvSE.exe` makes it expected. | unknown 2026-10-16 (preflight report, "Not tested / open"; Phase 4 smoke) |
| An unhidden CIM spawn opens a visible Windows Terminal window. The fix is `Win32_ProcessStartup.ShowWindow=0` plus `CREATE_NO_WINDOW` on every child; no window was seen in 26 checks, including a `claude` to `bash` to `PING` tree. | observed 2026-10-16 (preflight report, P0.1) |
| A CIM-created process gets the registry default user env, not the caller's (58 of the Bash env's variables missing, among them every `CLAUDE*` var and `CLAUDE_CODE_EXECPATH`), so the launcher must pass the full scrubbed env to the supervisor itself. | observed 2026-10-16 (preflight report, P0.1) |
| The Bash tool backgrounds a call that passes its `timeout`; it does not kill it. | observed 2026-10-16 (preflight report, P0.1(d)) |
| An unlisted model (not admitted by `availableModels`) is substituted silently: the run uses a permitted model and emits a `system/informational` warning ("Model … is restricted by your organization's settings. Using … instead."). | observed 2026-10-16 (preflight report, P0.5) |
| An `!` injection runs in an Agent-tool subagent's skill preload, but the skill's `allowed-tools` did not pre-approve the subagent's later `uv run` call (denied: "This command requires approval"). The probe dir was an untrusted workspace; Phase 4 re-checks in a trusted project. | observed 2026-10-16 (preflight report, P0.8) |

## 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) |