Skip to main content
Claude Code fornece as ferramentas de rastreamento de tarefas por padrão apenas nos modelos listados em Disponibilidade de modelos. Modelos mais novos rastreiam trabalho com múltiplas etapas sem uma lista de tarefas escrita, portanto nesses você não precisa de nada nesta página para Claude trabalhar através de tarefas com múltiplas etapas. Em uma sessão que possui as ferramentas de rastreamento de tarefas, Claude mantém uma lista de tarefas escrita, atualizando o status de cada item conforme trabalha. Você vê cada mudança no fluxo de mensagens como uma chamada de ferramenta estruturada. Opte por uma sessão apenas quando sua aplicação lê essas chamadas de ferramentas, seja para registrar atividade de tarefas ou para renderizar sua própria exibição de progresso.

Disponibilidade de modelos

As seguintes ferramentas estão disponíveis por padrão apenas em Claude Opus 4.7, Claude Sonnet 4.6, Claude Haiku 4.5 e modelos anteriores. Em todos os outros modelos, incluindo IDs de modelo que Claude Code não reconhece, elas não estão disponíveis a menos que você opte por usá-las:
  • TodoWrite
  • TaskCreate
  • TaskGet
  • TaskUpdate
  • TaskList
Onde quer que as ferramentas estejam disponíveis, Claude Code fornece as quatro ferramentas Task, ou TodoWrite em vez disso quando você define CLAUDE_CODE_ENABLE_TASKS=0.Este conjunto padrão se aplica em Claude Code v2.1.268 e posterior, que o TypeScript Agent SDK agrupa a partir de v0.3.268.
Em um modelo que não possui as ferramentas por padrão, a menos que você opte por uma sessão, você não vê blocos tool_use para elas no fluxo de mensagens. O Agent SDK aplica esses padrões através do binário Claude Code que ele agrupa. Se você apontar pathToClaudeCodeExecutable (TypeScript) ou cli_path (Python) para sua própria instalação do Claude Code, você obtém quaisquer ferramentas que essa instalação fornece, sob seus próprios padrões. Para ver o conjunto exato em uma sessão em execução, verifique quais ferramentas estão disponíveis. Para optar por uma sessão, faça um dos seguintes:
  • Nomeie uma das ferramentas na opção allowedTools (TypeScript) ou allowed_tools (Python)
  • Liste as ferramentas na opção tools, que restringe as ferramentas integradas da sessão àquelas que ela nomeia. Inclua as ferramentas que você deseja junto com as outras ferramentas integradas que você usa
  • Defina CLAUDE_CODE_ENABLE_TODO_TOOLS=1 na opção env, como os exemplos nesta página fazem. No TypeScript, env substitui o ambiente do subprocesso, então espalhe ...process.env para manter variáveis herdadas. No Python, env é mesclado no topo do ambiente herdado

Ciclo de vida das tarefas

Claude move cada tarefa através de um ciclo de vida previsível:
  1. Criada: Claude adiciona a tarefa como pending quando identifica uma tarefa
  2. Ativada: Claude define a tarefa como in_progress quando inicia o trabalho
  3. Concluída: Claude marca como concluída quando a tarefa termina com sucesso
  4. Removida: Claude deleta uma tarefa que não precisa mais definindo status: "deleted" em uma chamada TaskUpdate

Quando Claude cria tarefas

Em uma sessão que possui as ferramentas de rastreamento de tarefas, Claude cria tarefas para a maioria dos trabalhos com múltiplas etapas, como:
  • Tarefas complexas com múltiplas etapas que exigem três ou mais ações distintas
  • Listas de tarefas fornecidas pelo usuário quando vários itens são mencionados
  • Operações mais longas que se beneficiam do rastreamento de progresso
  • Solicitações explícitas quando os usuários pedem organização de tarefas
Claude pode pular tarefas para solicitações muito curtas ou de uma única etapa.

Exemplos

Antes de executar estes exemplos, instale o Claude Agent SDK seguindo o guia de início rápido. Cada exemplo nesta página compartilha a mesma configuração de permissões e comportamento de saída:
  • Modo de permissão: os exemplos de prompt pedem ao Claude para fazer trabalho real em um projeto, então cada exemplo define permissionMode: "acceptEdits" (TypeScript) ou permission_mode="acceptEdits" (Python) para aprovar automaticamente as edições de arquivo que o trabalho produz. Veja Modos de permissão para as alternativas.
  • Limite de turnos: cada exemplo é executado até que o agente termine e produza sua mensagem de resultado final. Se uma sessão atingir seu limite de turnos primeiro, essa mensagem de resultado terá o subtipo error_max_turns. Verifique subtype para detectar esse encerramento.
  • Tratamento de erros: estes exemplos usam chamadas query() de um único disparo. Após produzir um resultado error_max_turns, query() lança um erro que inclui Reached maximum number of turns. Cada exemplo envolve seu loop em um bloco try para sair corretamente quando isso acontece. Veja Lidar com o resultado para os subtipos de resultado.
As mensagens do sistema de tarefas, SDKTaskNotificationMessage (TypeScript) ou TaskNotificationMessage (Python) entre elas, relatam tarefas em segundo plano, como comandos em segundo plano e suagentes. No fluxo de mensagens, você vê atividade de tarefas como blocos tool_use nas mensagens do assistente.

Monitorar mudanças de tarefas

O exemplo a seguir observa o fluxo do assistente para blocos tool_use TaskCreate e TaskUpdate e imprime uma linha + com o assunto de cada nova tarefa e uma linha de atualização com o ID da tarefa e o novo status de cada mudança de status. Use esta forma quando você deseja um registro de atividade de tarefas em vez de uma exibição renderizada. As linhas + não incluem os IDs atribuídos, então este registro não pode corresponder atualizações de volta às suas criações. Para manter essa correlação, capture os IDs como Exibir progresso em tempo real faz. A entrada tool_use transmitida é a forma bruta que o modelo emitiu. Claude Code repara alguns nomes de chave próximos mas incorretos antes da execução, mapeando id ou task_id para taskId e active_form para activeForm, mas esse reparo não é refletido no fluxo. Leia os campos de entrada de TaskUpdate defensivamente, como ambos os exemplos nesta página fazem, em vez de assumir que o nome canônico está sempre presente.

Exibir progresso em tempo real

O exemplo a seguir observa o fluxo do assistente para blocos tool_use TaskCreate e TaskUpdate e mantém um mapa de tarefas codificadas por ID de tarefa em uma classe TaskTracker, renderizando novamente um resumo de progresso a cada mudança. O resumo conta tarefas concluídas e em progresso e mostra o rótulo activeForm de cada item ativo no lugar de seu subject. Use esta forma quando sua aplicação mantém uma exibição de progresso em vez de registrar cada evento. O ID de tarefa atribuído não está na entrada de TaskCreate. Claude Code entrega a saída estruturada de cada ferramenta na mensagem do usuário que carrega seu bloco tool_result, no campo tool_use_result. Para TaskCreate, esse objeto é documentado para TypeScript como TaskCreateOutput em Tipos de Saída de Ferramenta, e em Python o campo é um dict simples da mesma forma. O rastreador emparelha cada bloco tool_result com sua chamada tool_use por tool_use_id e lê task.id da mensagem emparelhada tool_use_result. Claude pode ler a lista de volta com TaskList e os detalhes completos de uma tarefa com TaskGet.