Planning with Task Tools

What You’ll Learn

Complex work needs both an approved approach and a live execution checklist. They are related, but they are not the same mechanism:

• Plan mode lets Claude explore without editing source files and present an approach for approval.
• TaskCreate, TaskGet, TaskList, and TaskUpdate track the work after it has been broken down.

By the end, you will know how to use both without confusing planning permission with task status.

The Current Task System

As of Claude Code v2.1.142, structured Task tools replace TodoWrite by default:

Tool	Purpose
TaskCreate	Create one task and receive its ID
TaskUpdate	Change status, details, owner, or dependencies
TaskGet	Read the full record for one task
TaskList	Read a snapshot of all current tasks

TodoWrite is a legacy compatibility path and is disabled by default in current interactive sessions. New tutorials and integrations should use the Task tools.

A task normally moves through this lifecycle:

pending → in_progress → completed

If a task is no longer needed, TaskUpdate can set its status to deleted.

Plan, Execute, Verify

PLAN
  Explore the repository with read-only tools
  Identify scope, risks, and dependencies
  Present the plan for approval
       ↓ approved
EXECUTE
  Create tasks with TaskCreate
  Move one active task to in_progress
  Update the list as facts change
       ↓ implementation complete
VERIFY
  Run the relevant tests and checks
  Inspect the final diff
  Mark tasks completed only with evidence

The task list is not proof by itself. A task should become completed only after its acceptance condition has actually been checked.

Enter Plan Mode Correctly

Start in Plan mode from the CLI:

claude --permission-mode plan

During an interactive CLI session, press Shift+Tab to cycle to Plan mode, or prefix a single prompt with /plan.

In Plan mode Claude can read files and run read-only shell commands to understand the codebase, but it does not edit your source files. Non-read-only shell commands still require approval. When Claude presents a plan, you can approve it, keep planning, or edit the plan before execution.

Plan mode does not mean that every read requires approval. Use the documented --permission-mode plan startup form shown above.

A Planning-First Prompt

/plan Add a notification system to this application.

Before proposing the implementation:
1. Inspect the existing architecture and tests.
2. Identify database, API, UI, migration, and rollout work.
3. Make dependencies and verification criteria explicit.
4. Do not change files until I approve the plan.

After approval, ask Claude to track execution:

Create a structured task list from the approved plan. Keep exactly one task
in progress unless independent work is deliberately parallelized. For every
task, include a concrete completion check and update the status as work proceeds.

Claude may conceptually make calls like these:

{"tool": "TaskCreate", "subject": "Add notification schema", "description": "Add migration and verify rollback"}
{"tool": "TaskUpdate", "taskId": "1", "status": "in_progress"}
{"tool": "TaskUpdate", "taskId": "1", "status": "completed"}
{"tool": "TaskList"}

The actual task ID comes from the TaskCreate result; do not invent IDs in an SDK integration.

What Good Planning Changes

Without a planning checkpoint	With Plan mode + Task tools
Editing begins before scope is understood	Read-only exploration comes first
Related changes are forgotten	Work is decomposed with acceptance checks
Progress is described only in prose	Task status remains visible
“Done” means Claude stopped editing	“Done” means verification passed

Next Session

In Session 4, we’ll explore subagents and context isolation. Session 7 will extend this task list into a dependency graph.

Official sources

• Tools reference
• Choose a permission mode
• Migrate from TodoWrite to Task tools

Last verified: 2026-07-20.