Claude Code の fork() の使いどき — 並列エージェント設計の判断基準 #AI - Qiita
@DevMasatoman

When to use fork() in Claude Code — Criteria for parallel agent design

  • ClaudeCode
  • AI
  • Personal Development
  • Agent
0
Posted at 2026-11-12

'I want to run subagents in parallel in Claude Code, but should I use fork() or a regular fresh agent?' — This is a point where you get stuck when trying to automate agent design.

Conclusion first.Use fork() when 'the parent context is needed and you don't want the child's output to be fed back into the parent context'.

Environment of this article

  • Claude Code (Agent SDK)
  • subagent_type: "fork" / "general-purpose"
  • Observed behavior in automated design (content-executor)

Actual behavior of fork()

Agents started with fork() inherit all the context from the parent session.

Important is cache sharing. Since fork() starts from the same context as the parent, prompt caching works directly. Even in sessions with heavy context, child agents using fork() can run at low cost from the start.

Parent session (context 50,000 tokens) └── fork() → Child inherits the same 50,000 token cache Input cost = processed at the cost of cache hit (about 1/10 of input price)

On the other hand,fresh agent starts with a zero context. You need to write all the background of the task, content of files, and constraints into the prompt and pass them over.

Criteria for choosing between fork() and fresh agent

Conditions fork() fresh agent
Parent context is needed ✅ ❌ (Write into prompt)
Don't want the child's raw logs to be added to the parent context ✅ ✅
Independent perspective / different model is needed ❌ ✅
Lightweight single-task ❌（Overloaded） ✅
Parallel research / investigation ✅ ✅
Derivative tasks after reading context ✅ △（Need reload）

Conditions for choosing fork():

  1. Want the parent's current context to be used by the child agent
  2. Don't want the child's task results (tool call raw logs, etc.) to be added to the parent context
  3. Want to investigate several independent questions in parallel

Conditions for choosing a fresh agent:

  • Want to use a different model (fork keeps the same model as parent)
  • Need an 'objective third-party' view without context
  • When the parent's context is too heavy and inheritance would be counterproductive

Implementation example (parallel check)

// Design example to execute parallel checks using fork() Agent({ subagent_type: "fork"", prompt: "Exaggeration check: ...", run_in_background: "true" }) Agent({ subagent_type: "fork", prompt: "Target Suitability Check: ...", run_in_background: true }) Agent({ subagent_type: "fork", prompt: "CTA Duplicate Check: ...", run_in_background: true }) // Wait for each check to complete, only receiving the results
content-executor (main body) ├── fork(Exaggeration Check) ─┐ ├── fork(Target Suitability Check) ─┤ Parallel execution └── fork(Internal Link Existence Check) ─┘ ↓ Only receive the judgment results (do not inherit raw logs)

This allows us to execute parallel checks at low cost without contaminating the parent context.

Summary

  • fork() = Context inheritance + Cache sharing. Used for deriving heavy sessions.
  • fresh agent = Start from zero. Used for clean judgments and when using different models.
  • If you don't want to return the child's raw logs to the parent context, use either with run_in_background: true

Comparison table of judgment criteria and detailed implementation patterns for actual automation design are also included in the original article → https://www.masatoman.net/articles/claude-code-fork-subagent-guide-2026?utm_source=qiita&utm_medium=referral&utm_campaign=dist-syndication&utm_content=claude-code-fork-subagent-guide-2026