BrainBank
AI Classroom/Best PracticesClaude Code Deep Dive

Task Create Tool: Create a task

8/2/2026, 3:32:11 PM · Source

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

#claude-code#best-practices#tool-architecture#task-management#task-object

This article explains how TaskCreateTool in Claude Code transforms todo items from simple text into formal runtime task objects containing status, dependencies, and metadata, revealing its internal call chain and key source code.

It upgrades a to-do item into a formal task object

TaskCreateTool doesn't simply insert a line of text into a list; it creates a work item as a formal task object:

  • Has an id
  • Has a subject
  • Has a description
  • Has a status
  • Can be updated, blocked, or assigned later

This shows that Claude Code's task system is no longer just a presentation-layer feature, but a true runtime object system.

Key Source Code

const taskId = await createTask(getTaskListId(), {
  subject,
  description,
  activeForm,
  status: 'pending',
  owner: undefined,
  blocks: [],
  blockedBy: [],
  metadata,
})

It then executes a hook:

const generator = executeTaskCreatedHooks(...)

Call Chain

Model extracts formal task > TaskCreateTool > createTask writes to storage > Execute task hooks > UI expands task view

Summary

TaskCreateTool represents the step in Claude Code that turns a "to-do text" into a "formal task object."

Learning map

Learning Path: Mastering the Task System in Claude Code

Phase One — Conceptual Understanding (15 min)

  • Understand the difference between todo text and formal task objects
  • Understand task attributes: subject, description, status, owner, blocks
  • Understand the concept and purpose of the task hook mechanism

Phase Two — Source Code Review (30 min)

  • Read the complete implementation code of TaskCreateTool
  • Trace the call chain: createTask → write to storage → hook execution
  • Analyze how the UI consumes task objects and renders views

Phase Three — Hands-on Practice (60 min)

  • Use Claude Code to execute a complex task creation workflow
  • Observe the complete lifecycle of a task from creation to rendering
  • Experiment with updating tasks and transitioning their states via API or CLI

Phase Four — Advanced Extensions (Optional)

  • Customize the behavior of taskCreatedHooks
  • Integrate external systems into the task lifecycle

Get hands-on — step by step

  1. Install and launch Claude Code: open a terminal, run the claude command to enter the interactive interface.
  2. Try submitting a requirement that needs multi-step decomposition—for example, ask the model to generate a project structure diagram—and observe how it automatically breaks sub-tasks into formal tasks.
  3. View detailed information for a created task; compare the data structure differences between a plain text to-do item and an actual task object (id, status, blocks, etc.).
  4. Update the status of an existing task—for example, ask Claude Code to mark a task as completed or adjust its priority.
  5. Read the TaskCreateTool source file: navigate into the project directory and use cat to view src/TaskCreateTool.ts (or the equivalent path), paying close attention to the two key calls—createTask and executeTaskCreatedHooks.
  6. In your development environment, manually construct a task object via an API (e.g., through MCP or the SDK) and test whether Claude Code can consume it correctly.

Top 3 sources

  1. 1
    Anthropic Claude Code 官方文档

    Claude Code 的权威参考文档，涵盖工具链、任务系统和工作流配置。

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

  2. 2
    Anthropic API 文档

    完整的 Claude API 引用，包括消息格式、参数和工具调用规范。

    https://docs.anthropic.com/en/docs

  3. 3
    Anthropic Claude Code GitHub 仓库

    Claude Code 相关工具的开源仓库，可深入查看 TaskCreateTool 等内置工具的实现源码。

    https://github.com/anthropics/anthropic-tools

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