reliquary/docs/workpad/research/2026-10-16-00-claude-headless-fork-sessions.md

# Claude Code headless: train one session, fork it per subsection

Model: `claude-opus-5-5` (researcher). Date: 2026-10-16. CLI on PATH: `claude` 2.1.283 (`/c/Users/g4b/.local/bin/claude`); the host Desktop session runs 2.1.299 (`AI_AGENT=claude-code_2-1-299_agent`), so the nested CLI is older than the host.

## Answer

Yes, it works. `claude -p ... --output-format json` returns `session_id`. `claude -p --resume <base> --fork-session` gives each run a new session id and a copy of the base history. The base stays as it was. Two forks ran in parallel without trouble, and each hit the prompt cache on the base prefix, provided its flags matched the base's. The catches:
- Permission, tool and model flags are not inherited. Pass them again, identically, on every fork, or the cache misses.
- The nested process is invisible to the Agent tool's tracking. The orchestrator has to block on Bash or poll for results.
- `--permission-mode plan` quietly changed the model.

## Claims

Sources: H = https://code.claude.com/docs/en/headless, C = https://code.claude.com/docs/en/cli-reference, S = https://code.claude.com/docs/en/sessions, P = https://code.claude.com/docs/en/permission-modes, E = https://code.claude.com/docs/en/env-vars, T = test log below.

| # | Claim | Status |
|---|---|---|
| 1a | `--output-format json` prints a single result object with `session_id`, `result`, `usage` (incl. `cache_read_input_tokens`, `cache_creation_input_tokens`), `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 (docs H; local test T1, T6) |
| 1b | `--resume <id>` finds the session by id in any project on the machine. It also accepts a `.jsonl` path. Without `--fork-session` it appends to the same id. | verified (docs H, C, S; local T5: resumed base kept id `433df7b7…`) |
| 1c | `--continue` = most recent conversation in the cwd. `claude -p --continue` includes `-p`/SDK sessions; interactive `--continue` skips them. Do not use it for fan-out, because "most recent" is ambiguous. Pass explicit ids instead. | verified (docs C, S) |
| 1d | `--session-id <uuid>` lets the caller choose the base id up front, so no output parsing is needed. | verified (docs C, `--help`) |
| 2a | `--fork-session` exists in 2.1.283: "When resuming, create a new session ID instead of reusing the original". | verified (`--help`; docs C) |
| 2b | The fork sees the base context. Forks do not see each other. The base is unchanged on disk and in later resumes. | verified (docs S "The original is unchanged on disk"; local T2-T5) |
| 2c | N forks from one base, run concurrently, work, and each gets its own id and `.jsonl`. Resuming the *same* id in two processes without forking interleaves both into one transcript. | verified (local T2+T3 run in parallel; docs S for the interleave warning) |
| 2d | A fork can be forked again (fork of a fork). | verified (local T6 forked fork A) |
| 3a | Forks hit the cache on the shared prefix: T2/T3 each had `cache_read` 14650 and `cache_creation` ~345, against the base's 8661 creation. | verified (local test) |
| 3b | A cache hit needs identical tool set, model and system prompt. A fork with different flags (T6: no `--tools ""`, default mode, haiku) got `cache_read` 0 and creation 17474. A fork that changed only the model (T7) got 4293 read and 7213 created. | verified (local test) |
| 3c | Cache writes here were `ephemeral_1h` (1-hour TTL). Forks spaced more than about an hour after the base's last request pay full creation for the base prefix. Docs S: after about 1 h inactive "the session's prompt cache has expired". The 1 h TTL may be plan/account dependent. | verified (local usage field; docs S); TTL policy across accounts unverified |
| 3d | `total_cost_usd` on a resumed or forked run is the cumulative conversation total, base spend included. Per-fork cost = fork total minus base total (T2: 0.0403 - 0.0359 = ~$0.0044). | verified (docs H "reports the conversation's whole total"; local numbers consistent) |
| 4a | A `-p` run starts in `default` mode on accounts that fetch feature flags. It cannot prompt: without a host or `--permission-prompt-tool`, anything that would prompt is denied and the run continues (listed in `permission_denials`). `--permission-prompts none` also tells Claude not to retry. `dontAsk` denies anything not pre-allowed. `--dangerously-skip-permissions` = `bypassPermissions`. | verified (docs H, P) |
| 4b | A fork does not inherit the base's permission mode, `--allowedTools` or `--tools`. T6, forked without flags, came up in `default` with all 43 tools. Docs: `-p --resume` starts "in the permission mode a new `claude -p` run would start in" (the plan-mode exception is disabled by `--fork-session`), and session grants don't carry into a `--fork-session` process. Pass the flags on every fork. | verified (local T6; docs S) |
| 4c | Not restored on resume either: `--mcp-config`, `--settings`, `--plugin-dir`, `--fallback-model`, `--add-dir`. The system prompt (incl. `--append-system-prompt`) is recorded at the first request and reused on resume/fork until compaction. Later flag text is ignored. | verified (docs S, C) |
| 4d | The model is restored on resume. `--model` on the fork overrides it (T7 ran haiku on a sonnet-5 base). | verified (docs S; local T7) |
| 5a | Without `--bare`, `-p` loads installed plugins, skills, agents, hooks, MCP and CLAUDE.md like an interactive session. T6 init listed plugin `spire@reliquary` 0.2.2, `spire:*` agents (athanor, adept, …) and `spire:*` skills. | verified (docs H; local T6) |
| 5b | `--bare` skips all that discovery and requires `ANTHROPIC_API_KEY` (no OAuth). Context then has to come from `--append-system-prompt[-file]`, `--settings`, `--agents`, `--plugin-dir`, `--mcp-config`. | verified (docs H, `--help`) |
| 5c | `--model` (alias or full id), `--agents <json or file>`, `--agent`, `--append-system-prompt[-file]`, `--settings`, `--max-budget-usd`, `--max-turns`, `--json-schema` all exist in 2.1.283. | verified (`--help`; docs C) |
| 5d | `--model haiku --permission-mode plan` ran on `claude-sonnet-5` (T1-T5). The same flags with `dontAsk` ran on `claude-haiku-4-5-20251001` (T7). User `settings.json` has no model key. Plan mode apparently swaps the model. The docs fetched don't explain it. | observed (local test); cause unverified |
| 6a | The nested `claude -p` inherits `CLAUDECODE=1` and `CLAUDE_CODE_CHILD_SESSION=1`. No recursion guard blocked it. `-p` sessions launched this way are still persisted (only nested *interactive* TUIs are excluded from `--resume`). | verified (docs E; local: `env` shows both, runs succeeded and persisted) |
| 6b | It is a separate process with its own Agent-depth budget (`subagent_stats.max_depth` 0 in its result; `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` default 3 applies per session). It does not count against the parent's Agent depth or concurrency caps. | depth separation inferred from per-process `subagent_stats` and docs E; not tested with a deep parent |
| 6c | Parent task notifications, `ListAgents` and `TaskStop` don't see it. The orchestrator must run it via Bash in the foreground (Bash timeout max 10 min) or background, then poll the output file or `--output-format json` result. `--bg` cannot combine with `-p`. | `--bg`/`-p` conflict verified (docs H); notification invisibility assumed (not a tracked Agent) |
| 6d | Transcripts land in `~/.claude/projects/<cwd with non-alnum -> '-'>/<session-id>.jsonl`, one file per fork. Each fork file holds the copied base history under its own `sessionId`. 30-day retention. | verified (docs S; local listing) |
| 6e | The nested process inherited the Desktop host's env (`CLAUDE_CODE_MESSAGING_SOCKET`, `CLAUDE_CODE_ENTRYPOINT=claude-desktop`, OAuth-refresh vars). T6's init showed Desktop-only tools (Artifact, ReportFindings, PushNotification) and a `messaging_socket_path`. Nested sessions may talk to the host app. Side effects unknown. | observed (local T6); implications unverified |
| 7 | Windows: worked from Git Bash with forward-slash paths. The project dir name is derived from the Windows path (`C--Users-g4b-…`). `CLAUDE_CODE_GIT_BASH_PATH` exists if bash isn't on PATH. There's no `python` on PATH here (use `node` to parse JSON). The CLI on PATH (2.1.283) lags the host (2.1.299). | verified (local; docs E) |

## Test log

cwd: `C:\Users\g4b\AppData\Local\Temp\claude\G--dev-projects-reliquary\42c87f82-…\scratchpad\forktest` (empty). Flags unless noted: `--model haiku --tools "" --permission-mode plan --output-format json`. 7 invocations, total ~$0.13 (cumulative-total arithmetic per 3d).

| T | Command | session_id | Result | cache_create / cache_read | Model |
|---|---|---|---|---|---|
| 1 | base: "Memorize ZEBRA-7731, reply OK" | `433df7b7` | OK | 8661 / 5989 | sonnet-5 |
| 2 | `--resume base --fork-session`: recall + memorize FORK-A-111 (parallel with T3) | `c3fbf072` | ZEBRA-7731 | 343 / 14650 | sonnet-5 |
| 3 | same, FORK-B-222 (parallel with T2) | `7ccea6b5` | ZEBRA-7731 | 346 / 14650 | sonnet-5 |
| 4 | `--resume forkA` (no fork): list all tokens, include FORK-B if known | `c3fbf072` (same) | ZEBRA-7731, FORK-A-111 | 109 / 14993 | sonnet-5 |
| 5 | `--resume base` (no fork), same question, after T2-T4 | `433df7b7` (same) | ZEBRA-7731 | 102 / 14650 | sonnet-5 |
| 6 | `--resume forkA --fork-session --model haiku --output-format stream-json --verbose`, **no** `--tools`/mode | `20a04357` | DONE; init: mode `default`, 43 tools, spire loaded | 17474 / 0 | haiku-4-5 |
| 7 | `--resume base --fork-session`, `--permission-mode dontAsk` instead of plan | `b8e6b9cd` | ZEBRA-7731 | 7213 / 4293 | haiku-4-5 |

What it shows: (a) forks see the base (T2, T3, T7); (b) forks are isolated from each other (T4 doesn't know FORK-B); (c) the base is unaffected (T5 knows only ZEBRA); (d) cache reuse depends on matching flags (T2/T3 vs T6/T7).

## Caveats and gaps

- Tiny contexts only. Behavior with a large trained base (100k+ tokens, compaction mid-fork) and with tool-using forks that write files was not tested. Parallel forks writing the same worktree would collide. Use `--worktree` or separate dirs.
- The plan-mode model swap (5d) is unexplained. Avoid `plan` for forks, or check `modelUsage` on each run.
- The 6b/6c claims about depth and notifications are inferred, not tested from inside an Agent-spawned subagent with a deep stack.
- The env inheritance from the Desktop host (6e) needs a look before relying on nested runs. Consider `--bare` + API key, or scrubbing `CLAUDE_CODE_MESSAGING_*` vars.
- Budget: 5 web pages fetched (headless, cli-reference, sessions, permission-modes, env-vars, the last two partially). Not read: Agent SDK sessions/cost-tracking pages and the prompt-caching page (exact TTL rules).

## Follow-up 2026-10-16

Model: `claude-opus-5-5`. Coordinator follow-up on the open points above. The original text is kept; where it was wrong, this section corrects it (see F3c on 6e and F2 on 5d). Same scratch folder. 8 invocations plus 1 nested child, about $0.35 in client-side estimates. Extra sources: PC = https://code.claude.com/docs/en/prompt-caching, MC = https://code.claude.com/docs/en/model-config, CT = https://code.claude.com/docs/en/agent-sdk/cost-tracking, E = env-vars (as above).

| # | Claim | Status |
|---|---|---|
| F1a | A `claude -p` launched from this subagent's Bash can spawn subagents with the Agent tool (`--tools "Task,Bash" --permission-mode dontAsk`). The subagent replied PONG. `subagent_stats`: spawned 1, `max_depth` 1, refused 0. | verified (local D1) |
| F1b | A second-level nested `claude -p` (launched by D1's Bash) works too: L2 returned `L2` with its own session id. No recursion guard, no error. | verified (local D1) |
| F1c | Depth is counted per process, starting from that process's main conversation. With the default limit, the nested run went two subagent layers down (spawned 2, `max_depth` 2, `spawned_by_subagents` 1, refused 0). That run was itself nested at least two levels under the Desktop host (host, then this subagent, then Bash). The host's depth is not passed down: there is no depth env var among the inherited ones. | verified (local D3; env listing) |
| F1d | Hitting the limit produces no error message. With `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1`, the layer-1 subagent simply had no Agent/Task tool. It answered "I don't have a Task/Agent tool available", and `refused.depth_limit` stayed 0. Docs: default 3, "set `1` to turn nesting off". | verified (local D2; docs E) |
| F2a | Reproduced. `--model haiku --permission-mode plan`: `system/init.model` reports the haiku model, but the assistant messages and `modelUsage` show Sonnet. On 2.1.283 it ran on `claude-sonnet-5` (init `claude-haiku-4-5-20251001`). On 2.1.299 it ran on `claude-sonnet-5-5` (init `claude-haiku-5-5`). With `dontAsk`, haiku runs as asked (T7). The debug log only shows `dispatching to firstParty model=claude-sonnet-5`, with no reason given. | verified (local M1, M2, T7) |
| F2b | Explanation: plan mode upgrades a Haiku session to Sonnet. MC, in the `availableModels` section: "A Haiku session that would normally upgrade to Sonnet in plan mode likewise uses the newest permitted Sonnet". The behavior is only implied there, not documented as a rule. It is not `opusplan`, and no env override is involved: there is no `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_*_MODEL`, `CLAUDE_CODE_SUBAGENT_MODEL` or `ANTHROPIC_SMALL_FAST_MODEL` in the inherited env, and no `model` in the user settings.json. Model-relevant inherited values: `CLAUDE_EFFORT=medium`, `CLAUDE_CODE_SIMPLE=0`. | docs (indirect, MC) + local env check; exact rule unverified |
| F2c | Practical point: `init.model` is not the model that ran. Read `modelUsage` or `assistant.message.model` instead. Aliases also depend on the 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 needs v2.1.284 or later). | verified (local; docs MC) |
| F3a | Inherited env vars that point the nested run at the Desktop host (names only): `CLAUDE_CODE_MESSAGING_SOCKET`, `CLAUDE_CODE_MESSAGING_TOKEN`, `CLAUDE_CODE_HOST_SESSION_ID`, `CLAUDE_CODE_ENTRYPOINT`, `CLAUDE_CODE_DESKTOP_APP_VERSION`, `CLAUDE_CODE_SDK_HAS_HOST_AUTH_REFRESH`, `CLAUDE_CODE_TERMINAL_MCP_TOOLS`, `CLAUDE_CODE_REPORT_FINDINGS`, `CLAUDE_CODE_SESSION_ID`, `CLAUDE_AGENT_SDK_VERSION`, `CLAUDE_CODE_ENABLE_ASK_USER_QUESTION_TOOL`, `CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING`, `CLAUDE_CODE_EXECPATH`, `CLAUDE_PID`, plus `CLAUDECODE`, `CLAUDE_CODE_CHILD_SESSION`, `AI_AGENT`. | verified (local env listing); each var's role unverified |
| F3b | Removing the first twelve of these with `env -u` drops the Artifact, ArtifactComments and ArtifactData tools (35 to 32 non-MCP tools). ReportFindings, PushNotification and the other built-ins stay. The 8 `mcp__claude_ai_Claude_Docs__*` tools also stay: they are a claude.ai account connector, not inherited. Auth (OAuth) still worked. Which single var gates the Artifact tools was not isolated. | verified (local E1 vs T6) |
| F3c | Correction to 6e: `messaging_socket_path` in `system/init` is the nested process's own pipe, not the host's. It was different in every run (`cc-msg-8e28...` in T6, `cc-msg-155d...` in E1) and never equal to the host's `CLAUDE_CODE_MESSAGING_SOCKET` (`cc-msg-f3c5...`). So there is no evidence that the nested run is wired to the host's channel, but there is also no proof that it isn't. Nothing was sent over the channel. | verified (local); "not wired" unverified |
| F3d | `--bare` removes all of it: 4 tools (Bash, Edit, PowerShell, Read), 0 MCP, no socket. It refuses OAuth, though (`Not logged in · Please run /login`, `is_error` true), so it needs `ANTHROPIC_API_KEY` (docs H). `plugins` was still listed in bare `init`, which looks odd. | verified (local E2; docs H) |
| F4a | The 1 h TTL is Claude Code's 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 m. Over the plan limit, the main conversation drops to 5 m. A `claude -p --resume --fork-session` run is a main conversation, which matches the 1 h writes we saw. In-process Agent-tool forks and subagents are in the "everything else" bucket and get 5 m by default. | verified (docs PC, CT; local `ephemeral_1h` in T1-T7) |
| F4b | It is configurable: `CLAUDE_CODE_PROMPT_CACHE_TTL` or the `promptCacheTtl` setting (main), `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` or `subagentPromptCacheTtl` (everything else), each `5m` or `1h`, v2.1.242 or later. `ENABLE_PROMPT_CACHING_1H=1` sets both; `FORCE_PROMPT_CACHING_5M=1` overrides everything. | verified (docs PC) |
| F4c | Cache hits refresh the TTL: "Each request that hits the cache resets the timer". So forks spaced under the TTL keep the base prefix warm for later forks. | verified (docs PC); not tested over time |
| F4d | Cache scope: "Sessions you run in parallel in the same directory build matching prefixes and read each other's cache". Different cwd or a different git-status snapshot changes the prefix. Run all forks from the base's cwd. | verified (docs PC); cross-cwd fork not tested |
| F4e | Cost accounting: on resume or fork, `total_cost_usd`/`modelUsage` include the restored session totals (v2.1.277 or later). Per-fork cost = fork result minus base total. Don't sum results. `--max-budget-usd` counts only the call's own spend. | verified (docs CT, C) |
| F5a | They are separate installs. PATH has `C:\Users\g4b\.local\bin\claude.exe` (native installer, 2.1.283, dated 2026-09-26). The Desktop host bundles its own `C:\Users\g4b\AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude-code\2.1.299\f0584be0fbaf\claude.exe` (2.1.299, dated 2026-10-15), reachable as `$CLAUDE_CODE_EXECPATH`. | verified (local) |
| F5b | With 2.1.299 the results hold, except that the aliases resolve to newer models (F2c). A 2.1.299 fork of the 2.1.283 base worked (recalled ZEBRA-7731, new id). But it had `cache_read` 0 and 15020 created, because plan mode now ran on `claude-sonnet-5-5`, while the base was on `claude-sonnet-5`. A Claude Code upgrade also changes the prompt (PC, "Upgrading Claude Code"). Pin one binary and a full model id for the base and all its forks. | verified (local V1; docs PC) |

### Follow-up test log

| T | Command (cwd forktest) | Result |
|---|---|---|
| M1 | 2.1.283 `--model haiku --tools "" --permission-mode plan`, stream-json, `--debug-file` | init haiku-4-5, ran sonnet-5 |
| M2 | same on 2.1.299 | init haiku-5-5, ran sonnet-5-5 |
| D1 | `--tools "Task,Bash" --allowedTools "Task" "Bash(claude -p *)" --permission-mode dontAsk`: spawn subagent, then run nested `claude -p` | SUB=PONG; L2=L2; max_depth 1 |
| D2 | `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1`, subagent asked to spawn a sub-subagent | layer-1 has no Agent tool; refused 0 |
| D3 | same as D2 with the default depth | DEEP; spawned 2, max_depth 2 |
| E1 | `env -u` (12 Desktop vars), default tools, dontAsk | 32 built-ins + 8 MCP; Artifact tools gone; own socket |
| E2 | `--bare`, same | 4 tools, no socket; "Not logged in" |
| V1 | 2.1.299 `--resume base --fork-session`, T2 flags | ZEBRA-7731; cache 15020 created / 0 read (model changed) |

### Remaining gaps

- The single env var that gates the Desktop Artifact tools, and whether the nested pipe can reach the host, were not isolated.
- The plan-mode Haiku-to-Sonnet upgrade is documented only by implication.
- TTL refresh and the cross-cwd fork cache behavior come from docs only.