Claude Code Subagents in Practice: Fork Flag, Cache Leak, Worktree Trap

Parallel subagents are useful only when their work can be partitioned. Claude Code subagents run with their own context windows and return a result to the parent. That isolates a focused task, but it does not make overlapping writes safe or make a cache hit automatic.

This guide focuses on the current documented behavior: forked subagents can share the parent context and prompt cache, while writers that touch the same repository need separate worktrees. Measure the result on your installed version before increasing fanout.

How subagents actually share (or don't share) cache

A subagent is not a shared shell session. It receives the task you dispatch, works independently, and reports back. Keep the parent responsible for integration and give each subagent a narrow, testable outcome. The custom subagent documentation is the right place to define persistent role instructions and tool limits.

Forked subagents are a different execution mode. Current Claude Code documentation says a fork inherits the full parent conversation and shares its prompt cache. A named subagent has its own context and cache. That distinction is a useful reason to compare both approaches against the same small task before assuming one is cheaper or better informed.

Getting more agents per cap

As of August 6, 2026, the Claude Code documentation describes the version-gated fork behavior below. Confirm the current documentation and the installed CLI version together before treating an environment setting as required.

The relevant environment variable is CLAUDE_CODE_FORK_SUBAGENT. Claude Code documents it as optional on versions 2.1.117 through 2.1.160; from 2.1.161, forked subagents are enabled by default. Set it to 1 only when you want to force-enable the behavior on a supported build:

export CLAUDE_CODE_FORK_SUBAGENT=1

Check claude --version before troubleshooting a difference in behavior. Version-gated features are easy to misdiagnose when the environment has multiple launchers. If a scheduled process needs a setting, place it in that process's explicit environment rather than assuming an interactive shell profile is loaded.

Run a small A/B experiment before a high-volume fanout. Keep the parent prompt, task shape, and model constant; record the number of subagents, elapsed time, input and cached-input usage where available, success rate, and conflicts found during integration. A fork that reduces repeated context without improving the actual task result is not automatically the right choice.

Do not publish a generic token or cost multiplier from one run as a capacity guarantee. Context size, tools, model, task quality, and the current product version all change the outcome. The useful proof is your own comparable trace.

Tool-heavy research needs measurement

Tool-heavy, long-running research tasks deserve their own measurement pass. A broad tool surface and a changing stream of fetched material can make a subagent difficult to reproduce and difficult to audit. That does not prove a cache failure by itself; it means the execution trace needs to decide.

For a mechanical web check, do not use an agent at all. For a judgment task over web material, gather the evidence deterministically where possible and ask a focused subagent to assess a bounded batch. Pick one of these patterns:

• Focused subagent. Give it the minimum tools and a clear evidence format.
• Inline review. Keep a small, sequential investigation in the parent when dispatch overhead is larger than the work.
• No model in the loop. For a check such as whether a URL returns 200, use a deterministic request rather than an agent.

When you genuinely need model judgment over web data, keep the evidence set small enough to inspect, record its source URLs, and use a single decision prompt with an explicit output schema. That gives the parent something verifiable to integrate.

Parallel forks that write files

The cache traps cost money. This one costs correctness.

Several writers in one checkout share index and branch state. Give each writer a separate Git worktree before launching it. Claude Code's worktree documentation supports claude --worktree <name> and custom subagents with isolation: worktree; both create isolated working directories backed by the same repository.

For a manual Git setup, pre-stage explicit branches before anything fires:

for i in 6 7 8 9 10; do
  git -C ~/repos/my-shared-repo worktree add ~/fork-$i-repo feat/branch-$i 2>/dev/null \
    || git -C ~/repos/my-shared-repo worktree add ~/fork-$i-repo -b feat/branch-$i
done

A worktree is a separate directory with its own checked-out branch. Point each writer at its assigned path and limit its changes to explicitly owned files. The parent or named integrator merges only after every worker reports its verification output.

After integration, run the repository's relevant test, typecheck, or build on the merged state. A clean merge does not prove that the combined behavior is correct. If the scope cannot be made disjoint, serialize the edits instead.

You only need this when forks share git scope. A single fork, or forks working on fully separate repos, do not need worktree isolation. The moment two or more forks touch the same repo, pre-stage. The same pre-staged-worktree rule keeps a fleet of interactive CLI agents driven from tmux from clobbering each other's commits when two sessions share one repo.

A reliable fanout shape

The reliable shape is simple: parallel writers, each with one owned file set and one isolated worktree. A parent gives every worker an acceptance criterion, collects the exact changed paths and test output, then integrates once.

The principle is not a trick specific to any agent product. Assign disjoint scope up front. One file set per agent, one worktree per writer, zero ambiguous ownership. When the work overlaps, parallelism manufactures integration work.

When NOT to fan out

Fanout is not the default answer. Skip it when:

• The work is sequential. If step B needs step A's output, agents cannot run in parallel. Forcing it just adds coordination overhead.
• The job is web-heavy with no judgment. That is a Python script, not a subagent fleet. See the cache leak above.
• The scope is small. Three files do not need a worktree fleet. Just do it in one context.
• You cannot make scope disjoint. If every agent has to touch the same files, serialize. Overlapping writers fight, and you pay in cherry-picks.

The honest summary: parallel subagents are a force multiplier when scope is clean and integration is explicit. Confirm the fork behavior on your version, use narrowly scoped agents, measure the run, and give every parallel writer its own worktree. Those controls keep a fanout inspectable instead of merely busy.

Related

• Claude Code in India: How I Actually Run It Daily
• Claude Code Fast Mode on Opus 4.7: What It Means for a Solo Operator in India
• Claude Code 2.1 Ships Subagent Forking: Five Tripwires
• The Codex Bridge: Routing GPT-5.5 and Opus in One India Stack
• Build a Custom MCP Server in Python

Sources

• Subagents, Claude Code Docs
• Git worktrees, Claude Code Docs
• Create custom subagents, Claude Code Docs