BrainBank
AI Classroom/KnowledgeClaude Code Deep Dive

TaskUpdateTool: Update Task

8/2/2026, 3:46:42 PM · Source

AI-translated on 8/2/2026, 3:47:25 PM · by Qwen3.6 35B (fast, default)

#claude-code#knowledge#tooling#state-machine#task-system#dependency-management

TaskUpdateTool is the primary write entry point of the Claude Code task system, responsible for modifying all mutable fields of a task object, advancing state transitions, and maintaining dependencies; it serves as the core state machine engine for the entire task workflow.

It Is the Primary Write Entry Point for the Task System

TaskUpdateTool is responsible for modifying the task object itself.
If TaskCreateTool creates nodes, then TaskUpdateTool is the core tool that actually advances the task flow.

Key Source Code

It supports a wide variety of updatable fields:

const inputSchema = z.strictObject({
  taskId: z.string(),
  subject: z.string().optional(),
  description: z.string().optional(),
  activeForm: z.string().optional(),
  status: TaskUpdateStatusSchema.optional(),
  addBlocks: z.array(z.string()).optional(),
  addBlockedBy: z.array(z.string()).optional(),
  owner: z.string().optional(),
  metadata: z.record(z.string(), z.unknown()).optional(),
})

This shows that it's not just about "changing status," but rather the central entry point for maintaining the entire task object.

Call Chain

Model advances task or adjusts dependencies > TaskUpdateTool > Updates status / owner / metadata / dependency > Triggers hooks and validation alerts as needed

Summary

TaskUpdateTool is the tool in Claude Code's official task system that most closely resembles a "state machine executor."

Learning map

🗺️ TaskUpdateTool Learning Roadmap

🟢 Phase 1: Understand the Context

  1. Review the overall architecture of Claude Code's task system
  2. Understand the division of responsibilities between TaskCreateTool (creating nodes) and TaskUpdateTool (advancing the main chain)
  3. Clarify the core concept of "Tasks as Directed Acyclic Graphs"

🔵 Phase 2: Master Field Capabilities

  1. Understand the meaning and function of each field in the inputSchema:
    • subject / description — Description updates
    • activeForm — Switching activation forms
    • status — State machine advancement (core)
    • addBlocks / addBlockedBy — Adding/removing dependencies
    • owner / metadata — Ownership and extension information
  2. Distinguish the capability boundaries between TaskUpdateTool and TaskCreateTool

🟡 Phase 3: Track the Call Chain

  1. Understand the trigger flow: model inference → adjust dependencies/status → TaskUpdateTool → hooks & validation reminders
  2. Learn the valid transition paths for task states (which states can transform into one another)
  3. Learn best practices for custom metadata extensions

🟠 Phase 4: Practical Implementation and Troubleshooting

  1. Actually invoke TaskUpdateTool to update task status
  2. Add/remove blocking dependencies between tasks, verifying that DCR executes correctly
  3. Record task decision logs in metadata

Get hands-on — step by step

Step 1: View Current Task List

Run Claude Code (or your tool environment) first to list the existing task checklist, confirming the taskId to be updated.

Step 2: Call TaskUpdateTool — Modify Status

Use TaskUpdateTool, passing the target taskId and status field:

  • taskId: "<your task ID>"
  • status: "In Progress" (or another valid status) Observe whether the status change succeeds.

Step 3: Call TaskUpdateTool — Add/Remove Dependencies

Add dependencies via the addBlockedBy field (array), marking the current task as blocked by upstream tasks, or passing blocking status downstream:

  • taskId: "<your task ID>"
  • addBlockedBy: ["upstream-task-1", "upstream-task-2"]

Step 4: Call TaskUpdateTool — Update Description and Ownership

Modify multiple fields at once. For example, simultaneously update the description, owner, and metadata:

  • taskId: "<your task ID>"
  • description: "Updated task description"
  • owner: "<new owner ID>"
  • metadata: {"updatedBy": "manual", "reason": "requirement change"}

Step 5: Verify Call Chain Trigger Results

  1. Confirm whether hooks were triggered correctly (check logs or notifications)
  2. Check that dependency alerts execute as expected
  3. Use the list command to confirm that the final status, dependencies, and owner are all consistent with expectations

Top 3 sources

  1. 1
    Claude Code Tasks 官方文档

    Claude Code 任务系统的官方参考，包含 TaskUpdateTool 在内的所有任务管理工具的使用说明。

    https://docs.anthropic.com/en/docs/claude-code/tasks

  2. 2
    Anthropic Claude Code GitHub

    Claude Code 开源仓库，可查看所有工具的源码实现与 TaskUpdateTool 的输入 Schema。

    https://github.com/anthropics/claude-code

  3. 3
    Task-Oriented AI Workflow Patterns

    Anthropic 官方提示库与教程，涵盖任务流编排、状态管理与多工具协作的最佳实践。

    https://docs.anthropic.com/en/docs/claude-code/prompt-library

Links are AI-suggested — worth a quick sanity check before diving in.