What is the difference between a fork and a normal subagent, in one sentence?
A fork inherits the whole conversation (same system prompt, tools, model and message history), while a normal subagent starts blank with only the task message, CLAUDE.md, git status and preloaded skills. What they share is that intermediate tool calls stay out of the main conversation and only the final result comes back.
I use claude -p in CI. Will my bill go up after upgrading?
The release notes do not quantify fork cost, so there is no firm answer. From v2.1.302, claude -p can use forks by default, Claude may choose one when delegating, and a fork carries the whole history. The DEV Community write-up says the effect can go either way and advises measuring a few runs. Compare token usage before and after the upgrade using the usage in --output-format json or OpenTelemetry, then decide whether to set CLAUDE_CODE_FORK_SUBAGENT=0.
I set autoCompactWindow in a subagent's frontmatter and it seems to do nothing. Why?
Check in order: write a plain integer, since 200k is read as 200 and falls out of range; the range is 100000 to 1000000 and the value must be below the window the subagent would otherwise inherit; CLAUDE_CODE_AUTO_COMPACT_WINDOW, if set, overrides the field; and it has no effect when the whole session runs as the subagent via --agent or the agent setting. Finally, run claude --debug and search the log for invalid autoCompactWindow to see whether it was ignored.
I'm not an engineer. How should I think about this?
Think of a subagent as an assistant you ask to do one task. A normal subagent gets a task sheet and starts from zero; a fork reads the whole conversation record up to now before starting. The latter needs no re-explaining, but it has a lot to read. This default changed in automated workflows, so if you watch costs, ask the engineers to compare usage once after the upgrade.
Most people picture a subagent as "a clean context to do one thing." Fork subagents deliberately do not work that way: the official docs describe a fork as a subagent that inherits the entire conversation so far instead of starting fresh, which drops the input isolation subagents otherwise provide in exchange for not having to re-explain the background. v2.1.302, released October 16, 2026, turned forks on by default in claude -p, the Agent SDK, the desktop app and VS Code, so this trade-off now happens automatically in more places.
Per the official subagent docs, a normal subagent starts with only its own system prompt, the task message, CLAUDE.md files, git status and any preloaded skills, and cannot see your conversation history. A fork sees the same system prompt, tools, model and message history as the main session, and it gets exactly the main conversation's tool pool, which means it skips the two filters that narrow tools for normal subagents. Output styles work the same way: the docs say they do not reach a normal subagent "except in a fork."
What they share is how output comes back: a fork's own tool calls stay out of your conversation and only its final result returns, so the main context stays clean.
The docs' advice: use a fork when any other subagent would need too much background to be useful, or when you want to try several approaches in parallel from the same starting point. There are two ways to start one: have Claude request the fork subagent type through the Agent tool (when fork mode is on), or run /subtask <task> at any time, for example /subtask draft unit tests for the parser changes so far. /subtask needs v2.1.212 or later; from v2.1.161 through v2.1.211 the command was called /fork. With agent view turned off, /fork starts the forked subagent; otherwise /fork copies the whole session into a new background session.
To observe them, the panel below the prompt lists the main session and each fork: ↑/↓ move between rows, Enter opens a fork's transcript and lets you send follow-ups, x stops a running fork or dismisses its row, and Esc returns focus to the prompt. When a fork finishes, its result arrives as a message in the main conversation; successful rows disappear right away, and failed or stopped rows stay for 30 seconds.
From the v2.1.302 notes: fork subagents (subagent_type: "fork") are now on by default in claude -p, the Agent SDK, the desktop app and VS Code, as they already are in the terminal; CLAUDE_CODE_FORK_SUBAGENT=0 turns them off, and claude mcp serve never offers them. The same release changed background behavior: the desktop app and VS Code now always run the main conversation's subagents in the background rather than letting Claude choose, and a subagent's own Agent calls in claude -p, the SDK, the desktop app and VS Code now run in the foreground by default.
One inconsistency to flag: the official subagent docs page I read still says fork mode is off in -p and the Agent SDK unless you turn it on. That is most likely the docs lagging behind v2.1.302, but I could not confirm it, so trust a test on your own version, and set CLAUDE_CODE_FORK_SUBAGENT explicitly if it matters.
The release notes say nothing about how forks affect cost, and the docs page I read (cut off partway through the fork section) does not discuss prompt caching for forks. A DEV Community write-up says it can raise or lower headless spend and advises measuring a few runs before deciding. My inference, not documentation: a normal subagent saves tokens through isolation, while a fork brings the whole history in as input, and the longer the conversation, the larger that input, but it saves the cost of the orchestrator writing a brief and the subagent rediscovering the background. Which side wins depends on your conversation length and the kind of task.
Since v2.1.296, a subagent's frontmatter and --agents definitions accept autoCompactWindow, which makes that subagent compact early, at a token count between 100000 and 1000000. The official docs' rules are easy to trip on:
---
name: log-reader
description: Reads long log files and reports the errors it finds
autoCompactWindow: 200000
---200k is read as 200, which is out of range, and the subagent behaves as if the field were absent. To check whether a value was ignored, run claude --debug and search the debug log for invalid autoCompactWindow.CLAUDE_CODE_AUTO_COMPACT_WINDOW is set to a positive integer, the subagent uses that variable's window and the field has no effect.--agent or the agent setting.This is my recommendation, not official policy: use a normal subagent when the task is self-contained, you want isolation, or the background can be stated briefly; use a fork when it needs a lot of the existing discussion to be done right, or when you want to try several approaches from the same starting point; and in automation, after upgrading to v2.1.302, measure one round of token usage before deciding whether to set CLAUDE_CODE_FORK_SUBAGENT=0.