Todo / 任务工具门控 · Claude Code 源码笔记

1. 两套系统#

	TodoWrite（v1）	Task 四件套（v2）
工具	`TodoWrite`	`TaskCreate` / `Get` / `Update` / `List`
数据	`todos: [{id,status,subject}]`，按 agentId 存 appState	磁盘任务文件：taskId、status、owner、`blocks` / `blockedBy`
2.1.233 `isEnabled`	`!isTodoV2Enabled() && isTodoToolsEnabled()`	`isTodoV2Enabled() && isTodoToolsEnabled()`

版本	事实
0.2.93	CHANGELOG：Todo 列表。v1 引入。
1.0.0	bundle 只有 TodoWrite，无 TaskCreate / TaskList。
2.1.16	CHANGELOG：new task management system，含 dependency tracking。v2 引入。
2.1.19	`CLAUDE_CODE_ENABLE_TASKS`；changelog：设 `false` 暂时保留旧系统。
2.1.88	`ENABLE_TASKS` 为真则强制 v2，否则交互走 v2、非交互走 v1。`TodoWrite.isEnabled = !isTodoV2Enabled()`。
2.1.229–232	`ENABLE_TASKS !== false`，默认全会话 v2；`ENABLE_TASKS=0` 回退 v1。2.1.232 叠 `tengu_vellum_ash`。
2.1.233	叠加 `isTodoToolsEnabled()`。`vellum_ash` 消失，`rosy_wren` 出现。定义仍在 bundle 里。

// 2.1.88 TodoWriteTool
isEnabled() { return !isTodoV2Enabled() }

// 2.1.88 utils/tasks.ts
export function isTodoV2Enabled(): boolean {
  if (isEnvTruthy(process.env.CLAUDE_CODE_ENABLE_TASKS)) return true
  return !getIsNonInteractiveSession()
}

// 2.1.233
function isTodoV2Enabled() {
  return V.CLAUDE_CODE_ENABLE_TASKS !== false
}

官方 tools-reference：未门控模型（如 Opus 4.7）默认给 Task 四件套；TodoWrite 要在已有任务工具的会话里设 ENABLE_TASKS=0。

2. 2.1.233 模型门控#

2.1.233（2026-08-14）：Opus 4.8、Sonnet 5、Fable 5、Mythos 5 及同家族更新模型上，Task 四件套和 TodoWrite 默认都不提供。

字符串	2.1.229	2.1.231	2.1.232	2.1.233
`CLAUDE_CODE_ENABLE_TODO_TOOLS`	0	0	0	2
`tengu_rosy_wren`	0	0	0	1
`tengu_vellum_ash`	—	—	1	0

2.1.229–232 没有模型家族表，也没有 ENABLE_TODO_TOOLS / rosy_wren。2.1.233 对 claude-opus-5 的 capture：20 个工具，无 Task 四件套、无 TodoWrite。

3. 门控机制#

3.1 模型表

const TASK_TRACKING_GATED_FAMILIES = [
  ["opus",   [4, 8]],
  ["sonnet", [5]],
  ["fable",  [5]],
  ["mythos", [5]],
]

// modelMeetsFamilyMin(id, table)：claude-<family>-<ver> 逐位比较，整体 >=
// isUngatedForTaskTracking(id) = !modelMeetsFamilyMin(id, TASK_TRACKING_GATED_FAMILIES)

3.2 三层

isBgOrTakeover()              // 后台会话 / bgTakeover
todoToolsOptIn()              // SDK / 宿主 opt-in
getMainLoopCanonicalModel()

isTodoV2Enabled()             // ENABLE_TASKS !== false
isTodoToolsEnabled()          // 后台 / SDK / 老模型 / env / rosy_wren
isTaskListToolsEnabled()      // isTodoV2Enabled && isTodoToolsEnabled

函数	管什么	为真时
`isTodoV2Enabled`	v1 / v2 互斥	Task 系列候选；TodoWrite 候选关掉
`isTodoToolsEnabled`	模型 + 场景 + 逃生门	这套任务追踪工具允许出现
`isTaskListToolsEnabled`	Task 四件套 `isEnabled`	两扇门都开

TodoWrite 的 isEnabled 是 !isTodoV2Enabled() && isTodoToolsEnabled()。

3.3 挂载点

工具	2.1.232	2.1.233
TaskCreate / Get / Update / List	`isTodoV2Enabled() && !tengu_vellum_ash`	`isTaskListToolsEnabled()`
TodoWrite	`!isTodoV2Enabled() && !tengu_vellum_ash`	`!isTodoV2Enabled() && isTodoToolsEnabled()`

定义、schema、prompt 都还在 bundle 里——isEnabled() === false 时对模型不可见。

4. 官方说明#

tools-reference · Task tool availability：

Those models keep track of multi-step work without a written checklist, and the tools’ definitions and reminders take up context, so Claude Code leaves them out. Without them, Claude adds nothing to the task list while it works.

这些模型能跟住多步工作，不需要书面清单；工具的定义和提醒会占上下文，所以 Claude Code 把它们拿掉。没有这些工具时，Claude 工作时不会往任务列表里写任何东西。

Agent SDK · Todo tracking：

Claude tracks multi-step work without a written todo list, and Claude Code leaves the task-tracking tools out of sessions by default. You don’t need anything on this page for Claude to work through multi-step tasks on those models.

在这些模型上，Claude 不靠书面 todo 列表就能跟住多步工作，Claude Code 默认不把任务追踪工具放进会话。这些模型上走完多步任务，不需要本页的任何内容。

代码两处一起停：工具 isEnabled 为 false，task_reminder 先查 isTaskListToolsEnabled()。

例外：后台 / bgTakeover 始终给；SDK todoToolsOptIn()；未进门控表的模型走 v1/v2 互斥。逃生门：env + rosy_wren。

ENABLE_TODO_TOOLS=1

env 只把 isTodoToolsEnabled() 短路为 true。Task 四件套还要 v2 开着；TodoWrite 还要 ENABLE_TASKS=0。

场景	TASKS	TODO_TOOLS	TodoWrite	Task 系列
老模型默认	未设	未设	✗	✓
老模型回退 v1	0	未设	✓	✗
新模型默认	未设	未设	✗	✗
新模型 + env	未设	1	✗	✓
新模型 + env + 回退 v1	0	1	✓	✗

5. 可借鉴点#

isEnabled() 动态门控，比编译期裁剪灵活
claude-<family>-<ver> 逐位比较
v1 / v2 互斥 + env 回退
后台/无人值守先于模型家族表
env（用户）+ GrowthBook（厂商）两扇逃生门