Claude Code forked subagent 机制说明

makoMakoGo 于 2026-04-30 发布

TL;DR

结论

CLAUDE_CODE_FORK_SUBAGENT=1 启用的是 forked subagent：子 agent 从当前主会话分叉出去，继承主会话已有上下文，而不是像普通 named subagent 那样从 fresh context 开始。

它适合当前上下文很重要、重新 briefing 成本高的并行任务。fork 的中间工具调用留在子上下文里，主会话只收到最终结果。

启用方式

写入 ~/.claude/settings.json：

{
  "env": {
    "CLAUDE_CODE_FORK_SUBAGENT": "1"
  }
}

使用方式

直接在 Claude Code 里运行：

/fork draft unit tests for the parser changes so far

/fork 后面的内容就是 forked subagent 的 directive。fork 会在后台运行，你可以继续在主对话工作；完成后它会把结果回传到主对话。

Background task 开关

配置行为
CLAUDE_CODE_FORK_SUBAGENT=1fork 默认后台运行；主对话可以继续交互，fork 完成后把结果回传到主对话
CLAUDE_CODE_FORK_SUBAGENT=1 + CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1禁用 background task 功能；fork/subagent 以前台同步方式运行，主对话会等它完成后才继续

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 禁用的是 background task 能力本身，包括自动后台化和 Ctrl+B 后台化。官方文档把 foreground subagent 定义为 blocking：它会阻塞主对话直到完成；权限提示和澄清问题会透传到当前终端。

主对话生命周期与社区反馈

background fork/subagent 是异步任务。主对话在委派完成后可以进入 idle 状态，不需要持续心跳轮询；后台任务完成后通过 <task-notification> / 结果消息回到主对话。

社区反馈与这个模型一致，但也暴露出边界问题：

启用后的行为变化

启用 CLAUDE_CODE_FORK_SUBAGENT=1 后有三点变化：

  1. Claude 原本会使用 general-purpose subagent 的场景，会改为 forked subagent。
  2. 所有 subagent spawn 默认后台运行。需要同步运行时可设置 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1。
  3. /fork 变成启动 forked subagent，不再是 /branch 的别名。

如果需要原来的分支对话功能，明确使用：

/branch

forked subagent 与 named subagent 的区别

项Forked subagentNamed subagent
上下文继承主会话完整 historyfresh context，只收到传入 prompt
system prompt / tools与主会话相同来自 subagent definition
model与主会话相同来自 subagent model 配置或继承主会话
中间工具调用留在 fork 子上下文留在 subagent 子上下文
回主对话最终结果最终结果
prompt cache共享主会话 cache prefix独立 cache

Explore、Plan、自定义 named subagent 仍按 named subagent 路径运行。fork 替代的是未指定具体 subagent_type、原本会落到 general-purpose 的默认路径。

使用判断

适合 fork：

适合 named subagent：

限制

资料来源

调研日期：2026-04-30。

主要依据：Claude Code 官方文档、Claude Code changelog v2.1.117 / v2.1.121、GitHub issues #28570 / #39335 / #42621 / #34916。