What it is

Sub-agent task spawning is how the agent splits one job into several that run on their own. The harness exposes a single Agent tool; calling it with a subagent_type selects a named specialist, but calling it without one — while the fork experiment is active — takes a different path entirely (claude-code/src/tools/AgentTool/AgentTool.tsx:323). That path is an implicit fork: instead of briefing a fresh specialist that has its own system prompt, the harness spins up a worker that inherits the parent's full conversation context and system prompt. The FORK_AGENT definition declares tools: ['*'] and model: 'inherit', so the child's tool pool and model match the parent's exactly (claude-code/src/tools/AgentTool/forkSubagent.ts:60-71). Each spawned worker then runs in isolation — a private git worktree on the filesystem, or a delegated remote environment — and reports back asynchronously rather than blocking the parent. This page reads that spawn-and-isolate machinery: the scribe who copies his whole desk, gives each helper a private room with a doorway to the shared library, and keeps working while their lamps burn.

How it works

When the Agent tool is invoked, the harness computes the effective agent type as subagent_type ?? (fork enabled ? undefined : general-purpose); if that resolves to undefined, isForkPath becomes true (claude-code/src/tools/AgentTool/AgentTool.tsx:323). The fork path first guards against recursion. A fork child keeps the Agent tool in its pool (so its tool definitions stay cache-identical to the parent's), which means a fork attempt from inside a fork must be rejected at call time — detected either via querySource or by scanning the message history with isInForkChild, throwing "Fork is not available inside a forked worker" (claude-code/src/tools/AgentTool/AgentTool.tsx:332). The fork experiment itself is gated behind isForkSubagentEnabled(), which is also off in coordinator and non-interactive sessions (claude-code/src/tools/AgentTool/forkSubagent.ts:32-38).

The fork is assembled by buildForkedMessages, which clones the parent's assistant message with every content block intact — thinking, text, and each tool_use — then constructs a single user message carrying one tool_result per tool_use, all filled with the identical placeholder text Fork started — processing in background (claude-code/src/tools/AgentTool/forkSubagent.ts:107-169; the constant at claude-code/src/tools/AgentTool/forkSubagent.ts:93). A per-child directive and a boilerplate "you are a forked worker process" message enforce the rules: ignore the parent's "default to forking" instruction, do not spawn sub-agents, do not converse — execute directly (claude-code/src/tools/AgentTool/forkSubagent.ts:171-198).

Isolation comes next. A worktree run creates a separate git checkout and symlinks heavy shared directories (like node_modules) back to the main repository so each worktree does not duplicate them on disk (claude-code/src/utils/worktree.ts:102-138). When isolation is remote instead, the harness checks eligibility and delegates the entire run to a remote (CCR) environment, returning early (claude-code/src/tools/AgentTool/AgentTool.tsx:435-480).

Finally, spawns run async. With the fork experiment on, all spawns are forced async for one unified <task-notification> interaction model — not only forks (claude-code/src/tools/AgentTool/AgentTool.tsx:555-557). registerAsyncAgent builds the task state; if a parent abort controller is supplied it wraps it via createChildAbortController so cancellation cascades, otherwise it makes a fresh one (claude-code/src/tasks/LocalAgentTask/LocalAgentTask.tsx:466-515, with the child wiring at claude-code/src/tasks/LocalAgentTask/LocalAgentTask.tsx:486). The work then runs through runAsyncAgentLifecycle, an async generator that streams the child's messages, updating progress and appending to retained tasks as it goes (claude-code/src/tools/AgentTool/agentToolUtils.ts:508-686). On completion it enqueues a notification: XML carrying the task id, status, and summary, plus — if a worktree was used — its path and branch (claude-code/src/tasks/LocalAgentTask/LocalAgentTask.tsx:197-256).

Why it matters

Three design choices in this machinery are worth dwelling on.

First, the identical placeholders. Every fork child receives byte-identical tool_result text (claude-code/src/tools/AgentTool/forkSubagent.ts:93) inside a cloned-but-identical parent message (claude-code/src/tools/AgentTool/forkSubagent.ts:107-169). Because the shared prefix is bit-for-bit the same across children, the model's prompt cache can be reused across all of them — the scribe's "even the ink marks line up" copies are not just tidy, they make the filing office's cached paperwork reusable in every room.

Second, isolation that does not cost disk. A worktree is a real, separate working copy, so children can edit files without trampling the parent or each other; symlinking node_modules and similar directories keeps that cheap (claude-code/src/utils/worktree.ts:102-138). And cleanup is conservative: the worktree is removed only when no git changes are detected; if the child left changes behind, the worktree persists so the work is not lost (claude-code/src/tools/AgentTool/AgentTool.tsx:667-678) — the desk with edits on it is left untouched, only the empty desk gets cleared.

Third, the abort wiring is deliberately asymmetric. In-process teammates spawned under a supervisor inherit the parent's abort controller via createChildAbortController, so a parent cancel cascades down to them (claude-code/src/tasks/LocalAgentTask/LocalAgentTask.tsx:486). But background agents spawned from the main loop are intentionally not linked to the parent's controller — so when the user presses ESC to cancel the main thread, the background work survives; it is killed only by the explicit chat:killAgents (claude-code/src/tools/AgentTool/AgentTool.tsx:694-696). That is the bell that stops the main desk but never reaches the side rooms. Combined with forcing all spawns async (claude-code/src/tools/AgentTool/AgentTool.tsx:555-557) and the task-notification handoff (claude-code/src/tasks/LocalAgentTask/LocalAgentTask.tsx:197-256), the result is a fan-out where the parent never blocks, children cannot accidentally recurse (claude-code/src/tools/AgentTool/AgentTool.tsx:332), and finished work returns as a tidy, locatable note.

Read the source

• The fork decision and recursion guard: claude-code/src/tools/AgentTool/AgentTool.tsx:323, claude-code/src/tools/AgentTool/AgentTool.tsx:332; the experiment gate at claude-code/src/tools/AgentTool/forkSubagent.ts:32-38.
• The fork agent definition and message construction: claude-code/src/tools/AgentTool/forkSubagent.ts:60-71, claude-code/src/tools/AgentTool/forkSubagent.ts:93, claude-code/src/tools/AgentTool/forkSubagent.ts:107-169, claude-code/src/tools/AgentTool/forkSubagent.ts:171-198.
• Isolation — worktree symlinks, remote delegation, conditional cleanup: claude-code/src/utils/worktree.ts:102-138, claude-code/src/tools/AgentTool/AgentTool.tsx:435-480, claude-code/src/tools/AgentTool/AgentTool.tsx:667-678.
• Async lifecycle, abort cascade, and notification: claude-code/src/tools/AgentTool/AgentTool.tsx:555-557, claude-code/src/tasks/LocalAgentTask/LocalAgentTask.tsx:466-515, claude-code/src/tasks/LocalAgentTask/LocalAgentTask.tsx:486, claude-code/src/tools/AgentTool/agentToolUtils.ts:508-686, claude-code/src/tasks/LocalAgentTask/LocalAgentTask.tsx:197-256, claude-code/src/tools/AgentTool/AgentTool.tsx:694-696.