Skip to main content
Claude Code предоставляет инструменты отслеживания задач по умолчанию только на моделях, перечисленных в разделе Доступность моделей. Более новые модели отслеживают многошаговую работу без письменного списка задач, поэтому на них вам не нужно ничего из этой страницы, чтобы Claude работал с многошаговыми задачами. В сеансе, который имеет инструменты отслеживания задач, Claude ведет письменный список задач, обновляя статус каждого элемента по мере работы. Вы видите каждое изменение в потоке сообщений как структурированный вызов инструмента. Подключите сеанс только когда ваше приложение читает эти вызовы инструментов, будь то для логирования активности задач или для отображения собственного индикатора прогресса.

Доступность моделей

The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn’t recognize, they aren’t available unless you opt in:
  • TodoWrite
  • TaskCreate
  • TaskGet
  • TaskUpdate
  • TaskList
Wherever the tools are available, Claude Code provides the four Task tools, or TodoWrite instead when you set CLAUDE_CODE_ENABLE_TASKS=0.This default set applies in Claude Code v2.1.268 and later, which the TypeScript Agent SDK bundles from v0.3.268.
На модели, которая не имеет инструментов по умолчанию, если вы не подключите сеанс, вы не увидите блоков tool_use для них в потоке сообщений. Agent SDK применяет эти значения по умолчанию через двоичный файл Claude Code, который он включает. Если вы указываете pathToClaudeCodeExecutable (TypeScript) или cli_path (Python) на вашу собственную установку Claude Code, вы получаете те инструменты, которые предоставляет эта установка, в соответствии с её собственными значениями по умолчанию. Чтобы увидеть точный набор в работающем сеансе, проверьте, какие инструменты доступны. Чтобы подключить сеанс, выполните одно из следующих действий:
  • Назовите один из инструментов в опции allowedTools (TypeScript) или allowed_tools (Python)
  • Перечислите инструменты в опции tools, которая ограничивает встроенные инструменты сеанса только теми, которые она называет. Включите нужные вам инструменты вместе с другими встроенными инструментами, которые вы используете
  • Установите CLAUDE_CODE_ENABLE_TODO_TOOLS=1 в опции env, как это делают примеры на этой странице. В TypeScript env заменяет окружение подпроцесса, поэтому распределите ...process.env для сохранения унаследованных переменных. В Python env объединяется с унаследованным окружением

Жизненный цикл задач

Claude перемещает каждую задачу через предсказуемый жизненный цикл:
  1. Созданы: Claude добавляет задачу как pending когда выявляет задачу
  2. Активированы: Claude устанавливает задачу в in_progress когда начинает работу
  3. Завершены: Claude отмечает её завершённой когда задача успешно завершается
  4. Удалены: Claude удаляет задачу, которая ей больше не нужна, установив status: "deleted" в вызове TaskUpdate

Когда Claude создаёт задачи

В сеансе, который имеет инструменты отслеживания задач, Claude создаёт задачи для большинства многошаговой работы, такой как:
  • Сложные многошаговые задачи, требующие трёх или более отдельных действий
  • Списки задач, предоставленные пользователем, когда упоминаются несколько элементов
  • Более длительные операции, которые выигрывают от отслеживания прогресса
  • Явные запросы, когда пользователи просят организовать задачи
Claude может пропустить задачи для очень коротких или одношаговых запросов.

Примеры

Перед запуском этих примеров установите Claude Agent SDK, следуя краткому руководству. Каждый пример на этой странице использует одну и ту же настройку разрешений и поведение выхода:
  • Режим разрешений: примеры подсказок просят Claude выполнить реальную работу над проектом, поэтому каждый пример устанавливает permissionMode: "acceptEdits" (TypeScript) или permission_mode="acceptEdits" (Python) для автоматического одобрения редактирования файлов, которое производит работа. Смотрите Режимы разрешений для альтернатив.
  • Лимит ходов: каждый пример работает до завершения агентом и выдачи его финального сообщения результата. Если сеанс сначала достигает лимита ходов, то сообщение результата имеет подтип error_max_turns. Проверьте subtype, чтобы обнаружить это завершение.
  • Обработка ошибок: эти примеры используют однократные вызовы query(). После выдачи результата error_max_turns, query() выбрасывает ошибку, которая включает Reached maximum number of turns. Каждый пример оборачивает свой цикл в блок try для чистого выхода при возникновении этого события. Смотрите Обработка результата для подтипов результатов.
Системные сообщения задач, SDKTaskNotificationMessage (TypeScript) или TaskNotificationMessage (Python) среди них, сообщают о фоновых задачах, таких как фоновые команды и подагенты. В потоке сообщений вы видите активность задач как блоки tool_use в сообщениях помощника.

Мониторинг изменений задач

Следующий пример наблюдает за потоком помощника для блоков tool_use TaskCreate и TaskUpdate и выводит строку + с предметом каждой новой задачи и строку обновления с ID задачи каждого изменения статуса и новым статусом. Используйте эту форму когда вы хотите логирование активности задач вместо отображаемого дисплея. Строки + не включают назначенные ID, поэтому этот логирование не может сопоставить обновления обратно их созданиям. Чтобы сохранить это соответствие, захватите ID как это делает Отображение прогресса в реальном времени. Потоковый ввод tool_use — это необработанная форма, которую выдала модель. Claude Code исправляет некоторые близкие, но неправильные имена ключей перед выполнением, сопоставляя id или task_id с taskId и active_form с activeForm, но это исправление не отражается в потоке. Читайте поля ввода TaskUpdate защитно, как это делают оба примера на этой странице, а не предполагайте, что каноническое имя всегда присутствует.

Отображение прогресса в реальном времени

Следующий пример наблюдает за потоком помощника для блоков tool_use TaskCreate и TaskUpdate и ведёт карту задач, индексированную по ID задачи в классе TaskTracker, переотображая сводку прогресса при каждом изменении. Сводка подсчитывает завершённые и выполняемые задачи и показывает метку activeForm каждого активного элемента вместо его subject. Используйте эту форму когда ваше приложение ведёт дисплей прогресса вместо логирования каждого события. Назначенный ID задачи отсутствует во вводе TaskCreate. Claude Code доставляет структурированный вывод каждого инструмента в сообщение пользователя, которое несёт его блок tool_result, в поле tool_use_result. Для TaskCreate, этот объект задокументирован для TypeScript как TaskCreateOutput в разделе Типы вывода инструментов, и в Python поле является простым dict той же формы. Трекер сопоставляет каждый блок tool_result с его вызовом tool_use по tool_use_id и читает task.id из tool_use_result сопоставленного сообщения. Claude может прочитать список обратно с помощью TaskList и полные детали одной задачи с помощью TaskGet.