Nested Claude Code

Spawn full Claude Code child processes from a parent session. Each child gets its own context window, tool access, and session — unlike Task-tool subagents which are lighter but cannot nest and share a process.

When to use this vs Task-tool subagents:

Need	Use
Quick subtask, result fits in a message	Task tool (Agent tool)
Long-running autonomous work (5+ min)	This pattern (subprocess)
Child needs to spawn its own subagents	This pattern (subprocess)
Parallel fan-out of N independent tasks	This pattern (subprocess)
Work that may exceed 600s Bash timeout	This pattern (background)

---

The spawning command

Every nested invocation requires these flags. Missing any one causes failures.

env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT claude \
    -p "Your prompt here" \
    --dangerously-skip-permissions \
    < /dev/null \
    2>&1

Flag	Why it's required
env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT	Claude Code sets these env vars on startup. When inherited by a child claude -p process, they can cause the child to hang silently — the process starts but never connects to the API (open issue). Unsetting them prevents this.
-p "..."	Non-interactive mode. The prompt is the child's sole instruction.
--dangerously-skip-permissions	No TTY exists for permission prompts in -p mode. Without this, the child hangs waiting for confirmation.
< /dev/null	Critical for Level 2+ nesting. Claude Code's Bash tool connects stdin via a unix socket. Without this redirect, grandchild processes hang indefinitely at 0% CPU. Always include it — it's harmless at Level 1 and required at Level 2+.

Optional flags

Add these based on your needs:

env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT claude \
    -p "Your prompt here" \
    --dangerously-skip-permissions \
    --output-format json \
    --append-system-prompt "Additional instructions appended to system prompt" \
    --agent my-agent-name \
    --name "_nest:my-task" \
    < /dev/null \
    2>&1

Flag	Purpose
--output-format json	Structured output with result, session_id, total_cost_usd, duration_ms, num_turns. Use for collecting results programmatically.
--output-format stream-json	Real-time NDJSON stream. Use when you need live visibility into tool calls and progress.
--append-system-prompt "..."	Inject additional system instructions while preserving Claude Code's built-in defaults. Use --system-prompt only if you want to replace ALL defaults (rarely correct).
--agent <name>	Run as a specific agent defined in .claude/agents/*.md. The agent's markdown body becomes the session's system prompt.
--name "label"	Display name for the session (shown in /resume picker). Use _nest: prefix for child sessions — enables cleanup by prefix. Stored as {"type":"custom-title","customTitle":"label"} in JSONL.
--no-session-persistence	Don't save session to disk. Use sparingly — non-persisted sessions cannot be forked or resumed. Prefer --name "_nest:label" + periodic cleanup instead.
--json-schema '{"type":"object",...}'	Validate child's final response against a JSON Schema. Use with --output-format json. Structured data lands in the structured_output field (not result).
--resume <session-id>	Continue a previous session with its full context. Use for multi-phase workflows where a child needs to pick up where it left off.
--resume <session-id> --fork-session	Targeted context-preserving fork. Fork a specific session by UUID. The child gets the target session's post-compaction state. Preferred over --continue --fork-session when you know the session ID (avoids CWD ambiguity).
--continue --fork-session	Context-preserving fork (most recent session). Fork the most recent session in the CWD's project. ⚠️ Must cd to the correct project directory first — resolves against child's CWD, not parent session.

---

Parallel execution

To run N children concurrently, launch each as a background Bash command. Two patterns:

Pattern A: Background Bash commands (simple, up to ~5 children)

Launch each child with run_in_background: true on the Bash tool. This returns immediately and gives you a task ID for polling.

Do NOT use & (shell backgrounding) inside the command. The Bash tool's run_in_background: true already runs the entire command in a background subprocess. Adding & inside causes the shell to exit immediately after spawning the claude process, which orphans it and breaks any output pipes — the parent sees "completed (exit code 0)" instantly while the claude process runs as an orphan with no captured output.

Bash(command: "env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT claude -p '...' --dangerously-skip-permissions --output-format json < /dev/null 2>&1 | tee /tmp/child-1-output.json",
     run_in_background: true,
     description: "Child 1: research topic A")

Bash(command: "env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT claude -p '...' --dangerously-skip-permissions --output-format json < /dev/null 2>&1 | tee /tmp/child-2-output.json",
     run_in_background: true,
     description: "Child 2: research topic B")

Launch all Bash calls in a single message (multiple tool calls in one response) — they execute concurrently.

Pattern B: Shell script for N children (more than 5, or dynamic)

Write a wrapper script that spawns all children and waits:

#!/bin/bash
set -e
PIDS=()
OUTPUT_DIR="/tmp/nested-claude-$$"
mkdir -p "$OUTPUT_DIR"

PROMPTS=(
    "Research topic A. Write findings to a file."
    "Research topic B. Write findings to a file."
    "Research topic C. Write findings to a file."
)

for i in "${!PROMPTS[@]}"; do
    env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT claude \
        -p "${PROMPTS[$i]}" \
        --dangerously-skip-permissions \
        --output-format json \
        < /dev/null \
        > "$OUTPUT_DIR/child-$i.json" 2>&1 &
    PIDS+=($!)
    echo "Spawned child $i (PID: ${PIDS[-1]})"
done

echo "Waiting for ${#PIDS[@]} children..."
FAILED=0
for i in "${!PIDS[@]}"; do
    wait "${PIDS[$i]}" || ((FAILED++))
    echo "Child $i finished (exit code: $?)"
done

echo "All children complete. $FAILED failures."
echo "Results in: $OUTPUT_DIR/"

Run this script via the Bash tool with run_in_background: true since it will take a while.

Concurrency limits

• There is no hard limit on concurrent claude -p subprocesses.
• Practical limit is your API rate limit and machine resources (each child is a separate process).
• 5-10 concurrent children is a reasonable default. Beyond that, you may hit API rate limits or machine resource contention.
• The Agent tool (in-process subagents) has practical concurrency limits but no hardcoded cap — monitor for degradation at high parallelism. The built-in /batch skill uses 5-30 as its working range.

No budget or iteration constraints by default

Do not add --max-turns, token limits, cost caps, or iteration ceilings unless a calling skill or the user explicitly says to. Artificial limits cut off children making progress.

---

Monitoring and result collection

A child Claude Code instance typically runs for 5-30 minutes depending on task complexity.

For background children (Pattern A)

Each background Bash call returns a task ID and output file path. You will receive a <task-notification> automatically when each child completes — prefer notifications over polling with TaskOutput (notifications arrive without consuming a tool call; TaskOutput blocks a turn waiting for output and is unavailable to subagents). When launching multiple children in parallel, each generates its own notification.

Initial spot check: If the child uses shared state files (e.g., spec.json, progress.txt), do an early read of those files (~1-2 minutes after launch) to verify the child got started properly — writing to the correct paths, reading the right inputs, not immediately erroring out. This catches misconfigured prompts or missing files early, before you've waited the full runtime for nothing.

To check progress mid-run, Read the output file path or the child's artifact files directly:

Read("/tmp/child-1-output.json")

Introspecting child sessions with /find-claude

Child sessions are full Claude Code sessions with their own .jsonl files. The JSONL is updated in real-time — every tool call, response, and message is appended as it happens, not buffered until exit. This means you can introspect a running child mid-execution.

Use /find-claude to:

• Find child sessions by name (--name "_nest:my-task" → grep for customTitle)
• Find child sessions by branch (children inherit the parent's git branch)
• Trace what a child did — tool calls, file writes, CWD, errors
• Debug path resolution issues (e.g., worktree vs main checkout CWD mismatches)
• Extract session IDs for --resume continuation

Quick patterns (no /find-claude needed):

# Watch a running child's activity (live tail)
tail -f ~/.claude/projects/<project>/<session-id>.jsonl | grep '"type":"assistant"'

# Check what CWD a child is using
head -1 ~/.claude/projects/<project>/<session-id>.jsonl | jq -r '.cwd'

# Find all _nest: sessions for this project
grep -l '"customTitle":"_nest:' ~/.claude/projects/<project>/*.jsonl

# Find what files a child wrote to
grep -o '"file_path":"/[^"]*"' ~/.claude/projects/<project>/<session-id>.jsonl | sort -u

See /find-claude "Forensic investigation" section for the full recipe reference (debugging tool calls, tracing path resolution, finding errors, inspecting ship review runs).

For script-spawned children (Pattern B)

The script waits internally. You will receive a <task-notification> when the script's background task completes. After the notification, read all output files from the output directory.

Structured output parsing

With --output-format json, the child's final output is a JSON object:

{
    "type": "result",
    "subtype": "success",
    "result": "The child's final text response",
    "session_id": "abc-123-...",
    "total_cost_usd": 0.42,
    "duration_ms": 180000,
    "num_turns": 12
}

Extract result for the child's text findings. Use session_id with --resume if you need to continue the session. Use subtype to detect exit reason (see exit detection table below).

When using --json-schema, the validated structured data is in structured_output (not result, which will be empty):

# Text result (no schema)
jq -r '.result'

# Structured output (with --json-schema)
jq '.structured_output'

How results return to the parent

Foreground children (Bash tool without run_in_background) return their stdout directly as the Bash tool result. The parent reads it inline — no files needed. This is the simplest pattern for children that return a summary, topic map, or structured finding.

Truncation threshold: The Bash tool persists output to a file above ~80-100KB. Above this, the parent gets a 2KB preview + file path ("Output too large. Full output saved to: /path"). For most use cases (summaries, structured results) this won't trigger. For verbose children, use file-based IPC or keep output concise.

Background children (run_in_background: true) write output to a task file. You receive a <task-notification> when the child exits. Read the output file path after the notification arrives.

Execution mode	Result delivery	When to use
Foreground, small output (<80KB)	stdout → Bash tool result (inline)	Default for simple tasks
Foreground, large output (>80KB)	Auto-persisted to file, 2KB preview inline	Verbose children
Background	<task-notification> on exit, then Read output file	Long-running children
Any, with structured artifacts	File-based IPC (child writes to known path)	Persistence, multi-file output, parallel children

File-based IPC (for complex, persistent, or large output)

For tasks where children produce structured artifacts, have each child write to a designated output file:

Prompt: "Research X. Write your findings to /tmp/research/topic-a.md. Include a ## Summary section at the top."

The parent reads these files after all children complete. This is more reliable than parsing stdout because:

• Files persist even if the child crashes partway through
• Structured formats (markdown, JSON) are easier to aggregate than free-form text
• Multiple files can be written (findings, evidence, recommendations)
• Files preserve full fidelity. When a child writes findings to a file, the parent (or next child) reads them verbatim. When results flow through stdout → parent context → LLM reasoning instead, the information passes through LLM summarization at each boundary — meanings shift, details erode, and errors compound. In multi-agent chains this "broken telephone" effect is measurable. Files bypass it entirely.

Output location strategy

When your examples use /tmp, that signals throwaway output. If the child's work product matters beyond this session, use a project-relative path instead.

Output type	Where	Why
Throwaway (logs, scratch, intermediate)	/tmp/nested-claude-$$/<child-id>/	Auto-cleaned, no project clutter, $$ prevents collisions between runs
Pass-scoped (parallel results, iteration artifacts)	<project-dir>/<pass-id>/ (e.g., output/2026-03-20-batch1/)	Scope to a pass identifier to prevent collisions between repeated runs; preserved for auditability
Deliverables the parent or user needs after the session	Project-relative path (e.g., reports/, output/)	Survives session, findable, version-controllable
Source code modifications	Dedicated directory or git worktree per child	Prevents merge conflicts between parallel children (see "Concurrent source code edits" below)

---

Completion detection

Two approaches depending on the use case:

Approach 1: Exit-based (simple, recommended)

Wait for the child process to exit. Read its output file. No sentinel strings needed.

Approach 2: Sentinel + cross-verification (for iteration loops)

If you're building an iteration loop where children update shared state:

1. Child outputs a specific sentinel string when done (e.g., TASK COMPLETE)
2. Parent greps for sentinel in output: grep -q "TASK COMPLETE" "$OUTPUT_FILE"
3. Parent cross-verifies against the state file (e.g., check that all items are marked done)
4. If sentinel found but state disagrees, re-run — the child lied

Always cross-verify. LLMs can output false completion signals.

---

What children inherit and don't

Inherited (automatic, no action needed):

• Environment variables from the parent shell — inherited by the child process, but with a critical limitation: settings.json env key overrides command-line values. If ~/.claude/settings.json (or project/managed settings) defines a key in "env": {}, that value overrides any command-line env var of the same name. This means common vars like CLAUDE_REPORTS_DIR (often in settings.json) CANNOT be overridden on children. Novel env vars not in any settings.json (e.g., CLAUDE_FANOUT_DEPTH) propagate correctly. For overridable configuration, use prompt text as the primary mechanism — tell the child where to write in the -p prompt. Use env vars only for novel keys you control.
• Project-level CLAUDE.md / AGENTS.md
• .claude/settings.local.json and ~/.claude/settings.json
• MCP server configurations (unless --strict-mcp-config is used)
• Git context (branch, status)
• Skills and agents defined in .claude/ (discoverable on disk, but skill content is only preloaded into context when declared in an agent's skills: field — see "Giving children domain knowledge" below)

NOT inherited (default — clean claude -p):

• Parent's conversation history
• Parent's loaded skill content or in-session context
• Parent's permission approvals
• Parent's CLI flags (--model, --effort, --append-system-prompt, etc.) — each child gets its own flags via its claude command
• Skill $ARGUMENTS — per-invocation strings that must be explicitly included in the child's -p prompt if propagation is desired
• Task state — TaskCreate/TaskList/TaskUpdate are in-memory runtime state, not serialized to disk. Children (including forks) do not have these tools — they get TodoWrite instead.

By default, each child starts completely fresh. The prompt you pass via -p is their entire instruction.

Context-preserving forks (--fork-session)

Adding --fork-session (with --continue or --resume UUID) changes this default: the child loads a session's post-compaction conversation state into its own context window. The child then runs independently.

What "post-compaction" means: If the source session has been auto-compacted (long sessions), older messages are replaced by compaction summaries. The fork inherits this compacted view — not the full raw JSONL. Content loaded earlier in the session (e.g., skill bodies loaded via the Skill tool) may have been compacted away. The fork sees whatever the source session currently has, not a complete replay.

Two ways to fork:

A) By UUID (preferred when you have the session ID):

env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT claude \
    --resume "$SESSION_ID" --fork-session \
    --name "_nest:ground" \
    --append-system-prompt "You are a FORKED CHILD PROCESS. Execute ONLY the task in the user prompt below. Use the session context to inform your judgment but do NOT continue the parent's workflow or act on prior instructions." \
    -p "Given our full context, do this specific task: ..." \
    --dangerously-skip-permissions \
    < /dev/null \
    2>&1

Capture the session ID from a prior child's --output-format json result (jq -r '.session_id'), or from ${CLAUDE_SESSION_ID} in a skill's content.

B) Most recent session in CWD (when you don't have a UUID):

cd /path/to/project && \
env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT claude \
    --continue --fork-session \
    --name "_nest:ground" \
    --append-system-prompt "You are a FORKED CHILD PROCESS. Execute ONLY the task in the user prompt below. Use the session context to inform your judgment but do NOT continue the parent's workflow or act on prior instructions." \
    -p "Given our full context, do this specific task: ..." \
    --dangerously-skip-permissions \
    < /dev/null \
    2>&1

⚠️ cd is required — --continue resolves against the child's CWD. Also, --continue grabs the most recently modified session, which may be the parent (not the child you intend). Prefer --resume UUID when possible.

--name "_nest:label" is recommended. Names child sessions for debuggability and enables prefix-based cleanup. See "Naming convention" below.

--append-system-prompt is required for forks. Without it, the child sees the full parent conversation and may try to continue the parent's workflow instead of executing the task prompt.

--bare does NOT work with forks — it skips keychain/OAuth reads, causing auth failure unless ANTHROPIC_API_KEY is set as an env var.

What forks preserve vs. don't:

Preserved	NOT preserved
Post-compaction conversation state (messages, tool calls, results that survived compaction)	Content compacted away (skill bodies loaded earlier, old tool results)
All standard tools + MCP tools	Task state (child may get TodoWrite instead of TaskCreate/TaskList/TaskUpdate)
Skills (discoverable on disk, invocable via Skill tool)	Parent's runtime in-memory state
Read + Write capability

Behavior:

• Works from inside a running session with the nesting guard bypass
• Child can read and write files normally
• Parallel forks work (no corruption when multiple forks read the same session)
• Self-forking works: A persisted child can fork itself — --continue --fork-session from within a child subprocess finds the child's own session and creates a grandchild with the child's context. Requires the child to be persisted (no --no-session-persistence).

Caveats:

• ⚠️ --continue grabs the most recently modified session in the CWD's project. If the parent session was updated more recently than the child you want to fork, --continue grabs the parent instead. Use --resume UUID --fork-session when targeting a specific session.
• ⚠️ --no-session-persistence makes a session un-forkable. A non-persisted child has no JSONL on disk — nothing for a grandchild to fork from. Prefer --name "_nest:label" (persisted, named, cleanable) over --no-session-persistence for any child that might be forked later.
• ⚠️ $CLAUDE_SESSION_ID is empty at runtime inside claude -p processes. It only works as a skill substitution variable (${CLAUDE_SESSION_ID} in SKILL.md content). To get a child's session ID, use --output-format json and extract session_id from the result.
• ⚠️ Token cost scales with session size. The post-compaction session state counts against the child's context window. Long sessions with many tool results can consume most of the child's context before it starts its task.
• ⚠️ Tasks may not survive. The child may not be able to see the parent's task list or create tasks the parent can see. Use file-based coordination or stdout for communicating results back.

When to use forks vs. clean children:

Situation	Use
Task is self-contained, doesn't need prior context	Clean claude -p (default)
Child needs to know WHY decisions were made	Fork (--resume UUID --fork-session or --continue --fork-session)
Child needs accumulated session knowledge (constraints discovered, options ruled out)	Fork
Many parallel children doing independent work	Clean (forks are expensive per-child)
Multi-level fork chain (child forks itself to spawn grandchild)	Fork with --name "_nest:label" (persisted, forkable). Capture child's session_id from JSON output for targeted grandchild forks.

Naming convention for nested sessions

Name all nested children with the _nest: prefix:

--name "_nest:ground"
--name "_nest:research-fanout-3"
--name "_nest:implement-iter-7"

The _nest: prefix signals "ephemeral child session" — created by an automated process, not a human. Benefits:

• Debuggability — identifiable in the /resume picker when investigating issues
• Cleanup — deletable by prefix: for f in ~/.claude/projects/*/*.jsonl; do grep -q '"customTitle":"_nest:' "$f" 2>/dev/null && rm "$f"; done
• Forkable — persisted sessions can be forked by UUID, enabling multi-level chains
• Indexed cleanly — the /find-claude indexer can filter or prune _nest: sessions during search

Prefer --name "_nest:..." over --no-session-persistence. Named sessions are findable, forkable, and cleanable. Non-persisted sessions are none of these.

Critical distinction from Task-tool subagents: Task/Agent tool subagents (spawned via the Agent tool within a session) do NOT inherit parent shell environment variables — they run in fresh, isolated shells. Only nested subprocesses (claude -p) inherit env vars. However, env var inheritance is NOT fully reliable — settings.json env values override command-line values for matching keys. Use prompt text as the primary mechanism for directing child behavior (it's Priority 1 in skill resolution hierarchies and cannot be clobbered). Use novel env vars (not in any settings.json) for custom cross-level signaling (e.g., depth counters).

Process cleanup safety (never kill what you didn't spawn)

Never kill all claude processes indiscriminately. Other users, other agents, and other sessions may have their own child processes running concurrently on the same machine. A blanket pkill -f claude or killall claude will destroy their work.

Only kill processes that you specifically spawned:

• Track PIDs from your own spawn calls and kill only those PIDs
• If using run_in_background: true, use the task ID to manage the process
• Never use pattern-based kills (pkill, killall) against claude processes

If you need to clean up stuck children, kill by the specific PIDs you captured at spawn time — not by process name.

---

Giving children domain knowledge

Children discover skill and agent files from .claude/ on disk, but that doesn't mean skills are loaded into their context. There are three mechanisms for giving children domain knowledge, each suited to different situations:

Mechanism 1: --agent with preloaded skills (structured, reusable)

Run the child as a specific agent. The agent's markdown body becomes the system prompt, and any skills: in the agent's frontmatter are injected into the child's context at spawn time.

env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT claude \
    --agent security-reviewer \
    -p "Review the auth changes in src/auth.ts" \
    --dangerously-skip-permissions \
    < /dev/null 2>&1

Where the agent file declares its skills explicitly:

# .claude/agents/security-reviewer.md
---
name: security-reviewer
skills:
  - security-checklist
  - repo-context
tools: Read, Grep, Glob
---
You are a security reviewer. Evaluate changes against your loaded skill standards.

Critical rule: Children do not inherit skills from the parent. The agent definition must list every skill the child needs. If the parent has write-docs loaded and the child needs it, the child's agent must declare skills: [write-docs].

Mechanism 2: --append-system-prompt (lightweight, no files needed)

For one-off children that need specific guidance but don't warrant a full agent definition:

env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT claude \
    -p "Review src/auth.ts for vulnerabilities" \
    --append-system-prompt "Focus on OWASP top 10. Check for SQL injection, XSS, and CSRF. Return findings as JSON." \
    --dangerously-skip-permissions \
    < /dev/null 2>&1

This preserves Claude Code's built-in defaults and adds your instructions on top. Less structured than skills, but no file creation needed.

Mechanism 3: File-based context (large or dynamic context)

Write context to a known path; instruct the child to read it in the prompt. Already covered in "File-based IPC" above. Best for large context (>10KB), context that changes between children, or context shared across children with different roles.

When the child needs the parent's judgment (not just data): Write a "brief" — a synthesis of what the parent learned during the session, what the user cares about, what evolved. This is different from copying a file or passing raw data. The parent reflects on what it knows and distills it into actionable guidance. A brief captures judgment calls ("inotify over NFS is a dealbreaker, not just a consideration") that raw data doesn't convey.

When to use which

Situation	Mechanism
Multiple children need the same role + domain skills	--agent with skills: — define once, reuse across spawns
One-off child needs a few extra instructions	--append-system-prompt — inline, no files
Context is large, dynamic, or per-child	File-based — write to disk, child reads it
Children need different skills for the same task	Multiple agent files, each with their own skills: list
Parent has quality standards (validation checklist, stance rules) child must enforce	Embed the key checks directly in the child's prompt. Skills are NOT inherited — if the parent loaded a skill with quality gates, the child won't have them unless given explicitly.

Headless mode for loaded skills (mandatory)

Children run non-interactively — there is no human to answer prompts, confirm decisions, or select options. Many skills have interactive gates by default (e.g., /research pauses for rubric confirmation, /spec presents routing options, /analyze may ask clarifying questions).

When a child loads any skill that supports a headless/non-interactive mode, it must use that mode. Without it, the skill will try to prompt a human who isn't there — the child will either hang, waste turns waiting for input, or produce degraded output.

How to signal headless mode:

Method	How
In the -p prompt	Include --headless in the skill invocation: "Load /research --headless and investigate..."
In --append-system-prompt	"When loading skills, always pass --headless."
In an agent's body	Add to the agent's markdown: "You are running non-interactively. When invoking skills, always use --headless mode."

The --headless flag is the standard convention across skills for signaling non-interactive execution. Skills that support it will auto-confirm interactive gates, auto-select routing decisions, and skip follow-up prompts — while preserving all quality gates (validation, evidence standards, etc.).

If a skill does not have a headless mode, it may still work — many skills have no interactive gates. But if the child gets stuck waiting for input that never comes, the symptom is wasted turns or empty output. The fix is to either add --headless support to that skill or work around the interactive step in the prompt.

---

Nesting depth

Level 0: Your interactive session
  |-- Level 1: env -u ... claude -p "..."     (child subprocess)
  |     |-- Level 2: Task tool subagent       (in-process, CANNOT nest further)
  |     |-- Level 2: env -u ... claude -p     (grandchild subprocess, CAN nest further)
  |           |-- Level 3: ...                (same pattern, unlimited depth)

• Subprocess path (env -u ... claude -p): unlimited depth. Each level applies the same guard pattern.
• Task-tool path: single level only. Subagents spawned via the Task tool cannot spawn further subagents. This is a hard platform constraint.
• There is no hard depth limit beyond the env var check.
• At every level, include env -u, --dangerously-skip-permissions, and < /dev/null.

---

Environment variables for isolation

When running multiple children concurrently in the same directory, they share filesystem state. For stronger isolation:

Variable	Purpose	Example
CLAUDE_CONFIG_DIR	Separate config per instance	/tmp/claude-config-$$-$i
CLAUDE_CODE_TMPDIR	Separate temp files per instance	/tmp/claude-tmp-$$-$i
ANTHROPIC_MODEL	Per-instance model selection	claude-sonnet-4-6
MCP_TIMEOUT	Predictable MCP connection timeout	30000
MCP_TOOL_TIMEOUT	Predictable tool execution timeout	60000

Example with isolation:

CLAUDE_CONFIG_DIR="/tmp/claude-config-$$-$i" \
CLAUDE_CODE_TMPDIR="/tmp/claude-tmp-$$-$i" \
env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT claude \
    -p "..." \
    --dangerously-skip-permissions \
    --name "_nest:isolated-$i" \
    < /dev/null \
    2>&1

Most use cases don't need this level of isolation. Use it when children might conflict on config or temp files.

Concurrent source code edits

When parallel children read the same codebase but write to separate output files (research, review, analysis), no special isolation is needed — this is the common case.

When parallel children need to edit the same source files, they will create conflicts. If two children might edit the same file, don't run them in parallel without isolation. Two mitigations:

1. Serialize — run children sequentially instead of in parallel when their edit scopes overlap. Simplest approach; no infrastructure needed.
2. Git worktrees — each child gets its own worktree, edits in isolation, parent merges results:

# Create a worktree per child
git worktree add "/tmp/worktree-child-$i" HEAD

# Spawn child in its own worktree
env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT claude \
    -p "Edit src/auth.ts to fix the session bug. Work in $(pwd)." \
    --dangerously-skip-permissions \
    < /dev/null 2>&1

# After all children finish, merge worktree changes back
cd /path/to/main/repo
git merge --no-ff "/tmp/worktree-child-$i"
git worktree remove "/tmp/worktree-child-$i"

---

Crafting good child prompts

Each child has zero context from the parent by default (unless using --fork-session). The prompt must be self-contained. If the prompt is incomplete, the child will silently fabricate what's missing — it cannot ask you for clarification. The most damaging gaps: missing goals (child executes the wrong task), missing constraints (child takes a wrong approach), and missing inputs (child fabricates file paths, API shapes, or prior findings).

Context briefing audit (do this before every spawn)

Explicitly briefing children on every artifact and instruction they need is the single biggest determinant of whether a child succeeds or fails. The mechanics of spawning are easy to get right; the context handoff is where orchestrators consistently fail.

Children cannot ask for help. When they're missing a file path, a skill, a constraint, or a prior decision, they don't stop — they fabricate plausible-sounding substitutes and proceed confidently. You won't know until you read the output and discover the child invented a file that doesn't exist, re-derived a decision you already made, or ignored a constraint it was never told about.

Before writing the -p prompt, answer these six questions. If you can't answer all six, the prompt isn't ready.

1. What files must the child read? List each with its absolute path and a one-line description of what it contains.
2. What skills should the child load? Name each explicitly, with --headless if running non-interactively.
3. What decisions have already been made that the child must not revisit? (tech choices, scope boundaries, rejected approaches)
4. What prior work exists that the child should build on, not redo? (research reports, specs, earlier child outputs)
5. Where should the child write its output? (exact path, format, structure)
6. What does "done" look like? (completion criteria, sentinel strings, state file updates)

Then include every answer in the prompt. Use the table below as a mapping guide:

Context type	What to include in the prompt	Example
Key source files	Absolute path + what it contains	"Read the spec at /home/user/project/SPEC.md — it defines the user stories and acceptance criteria"
Skills to load	Skill name + headless flag	"Load /research --headless for the investigation methodology"
State/progress files	Path + format + what the child should do with it	"Read spec.json at /home/user/project/tmp/ship/spec.json to find incomplete stories. Update each story's status field when done."
Prior findings	Path to artifact or inline summary	"A prior analysis found a session fixation bug (see /tmp/research/auth-findings.md). Build on these findings — do not re-investigate."
Decisions and constraints	Inline in the prompt	"We chose PostgreSQL over Redis for session storage. The user requires streaming responses. Do not modify the auth module."
Output location and format	Exact path + structure expectations	"Write findings to /tmp/output/review.md as markdown with a ## Summary section at the top."

Include:

• The full task description
• Any file paths to read
• Output format expectations — ask children to cite what they read or verified vs. what they inferred, so you can evaluate reliability when synthesizing across children (information degrades at agent boundaries; citations let you verify)
• Where to put results — stdout is sufficient for small results (<80KB); specify a file path for large or persistent output
• What "done" means
• What to do if stuck
• Headless flags for any skills the child will load (see "Headless mode for loaded skills" above)

Avoid:

• Referencing "the previous conversation" or "what we discussed"
• Assuming the child knows anything not in its prompt
• Vague instructions like "continue the work" without specifying what work
• First-person context that causes misattribution. If your prompt includes context from the parent session, reframe it to third-person. A child that reads "I analyzed the auth flow and found a session fixation bug" may believe it performed that analysis. Write instead: "A prior analysis found a session fixation bug in the auth flow" — this gives the child the fact without the false ownership.
• Long multi-step prompts where later steps are cleanup. Children may complete the primary task (the "real work") and skip later steps — especially cleanup, logging, and verification. Prefer: give the child the core task only; have the parent handle verification and cleanup after the child exits (see pattern 5: Delegate + validate).

Template:

You are performing [task type] on [subject].

## Task
[Clear, specific objective]

## Context
[Any background the child needs — file paths, constraints, prior findings]

## Output
Write your findings to [file path].
Format: [markdown/json/etc]
Include a ## Summary section at the top with key findings.
For each finding, note whether you verified it directly (read source code, ran a command, checked docs) or inferred it. This helps downstream synthesis.

## Constraints
- Do not modify any source files
- Focus only on [scope]
- If blocked, write what you found so far and note the blocker
- When loading skills, use --headless mode (you are running non-interactively)

---

Example: Parallel research (5 instances)

Spin up 5 Claude Code instances to research 5 different topics simultaneously:

# Launch all 5 in parallel (single message with multiple Bash tool calls)

Bash(command: "mkdir -p /tmp/research && env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT claude -p 'Research how React Server Components handle streaming. Write a comprehensive analysis to /tmp/research/rsc-streaming.md with a ## Summary at the top.' --dangerously-skip-permissions --output-format json --name "_nest:research" < /dev/null > /tmp/research/rsc-streaming-meta.json 2>&1",
     run_in_background: true,
     description: "Research: RSC streaming")

Bash(command: "env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT claude -p 'Research how Next.js App Router caching works. Write findings to /tmp/research/nextjs-caching.md with a ## Summary at the top.' --dangerously-skip-permissions --output-format json --name "_nest:research" < /dev/null > /tmp/research/nextjs-caching-meta.json 2>&1",
     run_in_background: true,
     description: "Research: Next.js caching")

Bash(command: "env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT claude -p 'Research Remix loader patterns and how they compare to Next.js. Write findings to /tmp/research/remix-loaders.md with a ## Summary at the top.' --dangerously-skip-permissions --output-format json --name "_nest:research" < /dev/null > /tmp/research/remix-loaders-meta.json 2>&1",
     run_in_background: true,
     description: "Research: Remix loaders")

Bash(command: "env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT claude -p 'Research TanStack Router architecture and its approach to type-safe routing. Write findings to /tmp/research/tanstack-router.md with a ## Summary at the top.' --dangerously-skip-permissions --output-format json --name "_nest:research" < /dev/null > /tmp/research/tanstack-router-meta.json 2>&1",
     run_in_background: true,
     description: "Research: TanStack Router")

Bash(command: "env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT claude -p 'Research Astro Islands architecture and partial hydration. Write findings to /tmp/research/astro-islands.md with a ## Summary at the top.' --dangerously-skip-permissions --output-format json --name "_nest:research" < /dev/null > /tmp/research/astro-islands-meta.json 2>&1",
     run_in_background: true,
     description: "Research: Astro Islands")

After launching, wait for <task-notification> for each child, then read and synthesize:

# Read all results
Read("/tmp/research/rsc-streaming.md")
Read("/tmp/research/nextjs-caching.md")
Read("/tmp/research/remix-loaders.md")
Read("/tmp/research/tanstack-router.md")
Read("/tmp/research/astro-islands.md")

# Read metadata for cost/duration tracking
Bash(command: "for f in /tmp/research/*-meta.json; do echo '---'; basename $f; jq '{cost: .total_cost_usd, duration_ms: .duration_ms, turns: .num_turns}' $f; done")

---

Parent-child interaction model

A child spawned with env -u ... claude -p is fundamentally fire-and-read: the parent sends a prompt, the child runs autonomously, the parent reads results after exit. There is no built-in real-time bidirectional communication.

What does NOT exist

• No callback from child to parent. A child cannot send a message to the parent mid-execution.
• No permission escalation. With --dangerously-skip-permissions (required), all permissions are auto-approved. The child cannot ask the parent "should I do this?"
• No pause/resume signal. The parent cannot pause a running child. The child cannot pause itself and wait for parent input.
• No progress events. The parent gets no "child is 50% done" notification (unless the child writes to a file the parent happens to read).
• No shared memory or message queue. Communication is via stdout return (foreground) or file-based IPC.

What the parent sees when a child gets stuck

The child has no way to signal "I'm stuck" in real-time. It keeps going until it completes or exhausts its context, then exits. The parent discovers what happened after the fact:

Exit reason	How parent detects it	JSON subtype field
Natural completion	Process exits 0	"success"
Crash / error	Process exits non-zero	"error_during_execution"
Child wrote "I'm stuck"	Parent reads output file after exit	Grep output for blocker keywords

Seven interaction patterns (from simplest to most capable)

1. Fire-and-forget (default, recommended for most use cases)

Parent launches child → child runs to completion → parent reads output

No interaction during execution. This is what the parallel research example uses.

2. Shared state file (for iteration loops)

Load: references/iteration-loop-pattern.md — full operational details for building an iteration loop with this pattern.

Parent writes state file → child reads, works, updates state file → parent reads after exit

The child writes progress to a known file path (e.g., spec.json, progress.txt). The parent reads this after the child exits and decides what to do next. This is the pattern /implement uses — each iteration is a fresh child that reads spec.json to find the next incomplete story.

3. Terminate and resume (for responding to stuck children)

Parent launches child → child exits (stuck or done) →
  parent reads output, extracts session_id →
  parent launches: claude -p --resume <session_id> "Here's how to get unstuck: ..."

The resumed session has the child's full prior context. This is the only way to "respond" to a child mid-workflow. Limitation: MCP server state is lost on resume (new process = new server).

4. Stream-json monitoring (for real-time visibility)

With --output-format stream-json, the child emits NDJSON lines in real-time:

{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Read","input":{"file_path":"src/auth.ts"}}]}}
{"type":"result","subtype":"success","result":"Final answer","total_cost_usd":0.42}

A wrapper script can parse this stream to detect tool calls, errors, or keywords as they happen. The parent Claude Code instance cannot easily consume this live (it's waiting on the Bash tool), but an external script can watch and write status to a file the parent polls.

5. Delegate + validate (for quality-controlled heavy work)

Parent writes brief + dispatches child → child does heavy work (bulk merge, large writes) →
  child exits → parent reads output → parent validates against quality standards →
  parent corrects/synthesizes → parent handles cleanup

The child does the context-heavy lifting (reading many files, writing large outputs). The parent retains quality control — it reads the child's output and validates against standards the child may not have (loaded skills, conversation context, user intent). The parent also handles cleanup steps the child might skip. Use when the child's work product needs to meet quality standards the parent enforces.

6. Custom MCP server (most powerful, requires building infrastructure)

Parent starts custom MCP server → passes it via --mcp-config →
  child calls mcp__parent__requestInput → MCP server blocks waiting for response →
  parent (or human via webhook/UI) responds → server unblocks → child continues

This is the only pattern enabling true mid-execution interaction. The child calls an MCP tool, the server intentionally blocks (waits on a webhook, file watch, or queue), and resumes when it gets a response. The child's session stays alive throughout.

Requires building the MCP server yourself — Claude Code does not provide this out of the box. Use --mcp-config to register it and optionally --strict-mcp-config to ensure the child only sees your server's tools.

env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT claude \
    -p "Do the task. If you need human input, call mcp__parent__requestInput." \
    --mcp-config '{"mcpServers":{"parent":{"command":"node","args":["./my-mcp-server.js"]}}}' \
    --dangerously-skip-permissions \
    < /dev/null 2>&1

7. Context-preserving delegation (for tasks that need the parent's context)

Parent forks session (cd to project dir first) →
  child starts with parent's post-compaction context →
  child executes task with accumulated decisions/findings →
  child returns results via stdout (or writes to file for large output) →
  parent reads results from Bash tool output

Uses --continue --fork-session (see "Context-preserving forks" above). The child has the parent's post-compaction conversation state — decisions, findings, and constraints that survived compaction. Best for high-value single delegations where context loss is more expensive than the token cost.

Limitation: The child cannot modify the parent's task list or inject messages into the parent's conversation. Results flow back via stdout (foreground) or files.

Choosing a pattern

Situation	Pattern
Independent tasks, just need results	1. Fire-and-forget
Multi-step workflow, children build on prior work	2. Shared state file
Child might get stuck and needs guidance	3. Terminate and resume
Need to watch what children are doing	4. Stream-json monitoring
Child does heavy work, parent must ensure quality	5. Delegate + validate
Child needs human approval mid-task	6. Custom MCP server
Child needs parent's full accumulated context	7. Context-preserving delegation

---

Common errors and fixes

Error	Cause	Fix
"Claude Code cannot be launched inside another Claude Code session"	Missing env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT	Add the env guard
Child process hangs at 0% CPU, no output	Missing < /dev/null (Level 2+)	Add < /dev/null to the command
Child hangs waiting for permission	Missing --dangerously-skip-permissions	Add the flag
"command not found: claude"	Claude CLI not on PATH	Check which claude or use full path
Bash tool times out (600s)	Child takes longer than 10 minutes	Use run_in_background: true
Children write conflicting files	Shared output paths	Use unique paths per child (include $$ or index)
Child appears to complete instantly with 0-byte output	Used & inside a run_in_background: true Bash command (double-backgrounding). The shell exits after &, orphaning the claude process and breaking output pipes.	Remove & from the command. The Bash tool's run_in_background: true already handles backgrounding. The claude command must be the foreground process inside that shell.