Pular para o conteúdo principal
Ao trabalhar em uma tarefa, Claude às vezes precisa verificar com os usuários. Pode precisar de permissão antes de excluir arquivos ou precisar perguntar qual banco de dados usar para um novo projeto. Seu aplicativo precisa apresentar essas solicitações aos usuários para que Claude possa continuar com sua entrada. Claude solicita entrada do usuário em duas situações: quando precisa de permissão para usar uma ferramenta (como excluir arquivos ou executar comandos) e quando tem perguntas de esclarecimento (por meio da ferramenta AskUserQuestion). Ambas acionam seu callback canUseTool, que pausa a execução até que você retorne uma resposta. Isso é diferente dos turnos de conversa normais, onde Claude termina e aguarda sua próxima mensagem. Para perguntas de esclarecimento, Claude gera as perguntas e opções. Seu papel é apresentá-las aos usuários e retornar suas seleções. Você não pode adicionar suas próprias perguntas a este fluxo; se precisar perguntar algo aos usuários, faça isso separadamente na lógica do seu aplicativo. O callback pode permanecer pendente indefinidamente. A execução permanece pausada até que seu callback retorne, e o SDK apenas cancela a espera quando a própria consulta é cancelada. Se um usuário puder levar mais tempo para responder do que seu processo pode razoavelmente permanecer em execução, retorne a decisão do hook defer, que permite que o processo saia e retome mais tarde a partir da sessão persistida. Este guia mostra como detectar cada tipo de solicitação e responder apropriadamente.

Detectar quando Claude precisa de entrada

Passe um callback canUseTool nas opções de sua consulta. O callback é acionado sempre que Claude precisa de entrada do usuário, recebendo o nome da ferramenta e a entrada como argumentos:
O callback é acionado em dois casos:
  1. Ferramenta precisa de aprovação: Claude quer usar uma ferramenta que não é aprovada automaticamente por uma regra de permissão ou modo de permissão. Verifique tool_name para a ferramenta (por exemplo, "Bash", "Write").
  2. Claude faz uma pergunta: Claude chama a ferramenta AskUserQuestion. Verifique se tool_name == "AskUserQuestion" para tratá-la diferentemente. Se você especificar um array tools, inclua AskUserQuestion para que isso funcione. Veja Lidar com perguntas de esclarecimento para detalhes.
O callback nunca é acionado para ferramentas aprovadas automaticamente. Qualquer aprovação anterior no fluxo de avaliação de permissões, uma regra de permissão ou um modo como acceptEdits ou bypassPermissions, resolve a chamada antes que canUseTool seja consultado. Se você listar uma ferramenta diretamente em allowed_tools, uma verificação canUseTool para essa ferramenta nunca é executada a menos que uma regra de pergunta ou modo plan redirecione a chamada de volta para um prompt. Para lógica que deve se aplicar a cada chamada de ferramenta, use um hook PreToolUse, que é executado antes do resto do fluxo e pode permitir, negar ou modificar solicitações.AskUserQuestion, ferramentas MCP marcadas como requiresUserInteraction, e ferramentas de conector que sua organização configurou como ask chegam ao callback mesmo quando uma regra de permissão corresponde. No modo dontAsk essas chamadas são negadas em vez disso, sem invocar o callback.
Você também pode usar o hook PermissionRequest para enviar notificações externas (Slack, email, push) quando Claude está aguardando aprovação.

Lidar com solicitações de aprovação de ferramentas

Depois de passar um callback canUseTool nas opções de sua consulta, ele é acionado quando Claude quer usar uma ferramenta que nada anterior no fluxo de permissão aprovou. Seu callback recebe três argumentos: O objeto input contém parâmetros específicos da ferramenta. Exemplos comuns: Veja a referência do SDK para esquemas de entrada completos: Python | TypeScript. Você pode exibir essas informações ao usuário para que ele possa decidir se permite ou rejeita a ação, e então retornar a resposta apropriada. O exemplo a seguir pede ao Claude para criar e excluir um arquivo de teste. Quando Claude tenta cada operação, o callback imprime a solicitação de ferramenta no terminal e solicita aprovação s/n.
Em Python, can_use_tool requer modo de streaming. Quando você passa um fluxo de mensagens finito através de query(prompt=generator) ou ClaudeSDKClient.connect(prompt=async_iterable), o SDK fecha o fluxo de entrada após a última mensagem, antes que o callback de permissão possa ser invocado, a menos que um hook registrado ou servidor MCP em processo o mantenha aberto. O exemplo acima o mantém aberto com um hook PreToolUse que retorna {"continue_": True}. Conectar sem prompt e enviar mensagens através de ClaudeSDKClient.query() mantém o fluxo aberto por si só e não precisa de hook.
Este exemplo usa um fluxo s/n onde qualquer entrada diferente de s é tratada como uma negação. Na prática, você pode construir uma interface de usuário mais rica que permite aos usuários modificar a solicitação, fornecer feedback ou redirecionar Claude completamente. Veja Responder a solicitações de ferramentas para todas as maneiras que você pode responder.

Responder a solicitações de ferramentas

Seu callback retorna um de dois tipos de resposta: Ao permitir, a ferramenta executa com a entrada que Claude solicitou, a menos que você retorne uma entrada modificada, updatedInput em TypeScript ou updated_input em Python. Antes da v2.1.207, Claude Code rejeitava um resultado de permissão que omitia updatedInput e negava a chamada de ferramenta com um erro de validação. Ao negar, forneça uma mensagem explicando por quê. Claude vê esta mensagem e pode ajustar sua abordagem.
Além de permitir ou negar, você pode modificar a entrada da ferramenta ou fornecer contexto que ajude Claude a ajustar sua abordagem:
  • Aprovar: deixe a ferramenta executar conforme Claude solicitou
  • Aprovar com alterações: modifique a entrada antes da execução (por exemplo, sanitize caminhos, adicione restrições)
  • Aprovar e lembrar: repita uma regra de permissão sugerida para que chamadas correspondentes ignorem o prompt na próxima vez
  • Rejeitar: bloqueie a ferramenta e diga ao Claude por quê
  • Sugerir alternativa: bloqueie mas guie Claude para o que o usuário quer em vez disso
  • Redirecionar completamente: use entrada de streaming para enviar ao Claude uma instrução completamente nova
O usuário aprova a ação como está. Passe a input do seu callback inalterada e a ferramenta executa exatamente como Claude solicitou.

Lidar com perguntas de esclarecimento

Quando Claude precisa de mais direção em uma tarefa com múltiplas abordagens válidas, ele chama a ferramenta AskUserQuestion. Isso aciona seu callback canUseTool com toolName definido como AskUserQuestion. A entrada contém as perguntas do Claude como opções de múltipla escolha, que você exibe ao usuário e retorna suas seleções.
Perguntas de esclarecimento são especialmente comuns no modo plan, onde Claude explora a base de código e faz perguntas antes de propor um plano. Isso torna o modo plan ideal para fluxos de trabalho interativos onde você quer que Claude reúna requisitos antes de fazer alterações.
Os passos a seguir mostram como lidar com perguntas de esclarecimento:
1

Passe um callback canUseTool

Passe um callback canUseTool nas opções de sua consulta. Por padrão, AskUserQuestion está disponível. Se você especificar um array tools para restringir as capacidades do Claude (por exemplo, um agente somente leitura com apenas Read, Glob e Grep), inclua AskUserQuestion nesse array. Caso contrário, Claude não será capaz de fazer perguntas de esclarecimento:
2

Detecte AskUserQuestion

Em seu callback, verifique se toolName é igual a AskUserQuestion para tratá-lo diferentemente de outras ferramentas:
3

Analise a entrada da pergunta

A entrada contém as perguntas do Claude em um array questions. Cada pergunta tem uma question (o texto a exibir), options (as escolhas) e multiSelect (se múltiplas seleções são permitidas):
Veja Formato de pergunta para descrições completas de campos.
4

Colete respostas do usuário

Apresente as perguntas ao usuário e colete suas seleções. Como você faz isso depende de seu aplicativo: um prompt de terminal, um formulário web, um diálogo móvel, etc.
5

Retorne respostas ao Claude

Construa o objeto answers como um registro onde cada chave é o texto question e cada valor é o label da opção selecionada:Para perguntas de seleção múltipla, passe um array de labels ou junte-os com ", ". Se você suportar entrada de texto livre, use o texto personalizado do usuário como o valor.

Formato de pergunta

A entrada contém as perguntas geradas pelo Claude em um array questions. Cada pergunta tem estes campos: A estrutura que seu callback recebe:

Visualizações de opção (TypeScript)

toolConfig.askUserQuestion.previewFormat adiciona um campo preview a cada opção para que seu aplicativo possa mostrar uma simulação visual ao lado do rótulo. Sem esta configuração, Claude não gera visualizações e o campo está ausente. O formato se aplica a todas as perguntas na sessão. Claude inclui preview em opções onde uma comparação visual ajuda (escolhas de layout, esquemas de cores) e a omite onde não ajudaria (confirmações sim/não, escolhas apenas de texto). Verifique se há undefined antes de renderizar.
Uma opção com uma visualização HTML:

Formato de resposta

Retorne um objeto answers mapeando cada campo question da pergunta para o label da opção selecionada: Para perguntas de seleção múltipla, passe um array de labels ou junte-os com ", ". Para entrada de texto livre por pergunta, como uma opção “Outro”, coloque o texto do usuário em answers[question] conforme mostrado em Suporte para entrada de texto livre. Defina response apenas quando sua interface do usuário permitir que o usuário descarte o cartão de pergunta e digite uma resposta geral que não seja uma resposta a nenhuma pergunta específica. Quando response é definido, Claude recebe “O usuário respondeu: …” em vez da lista de resposta por pergunta.

Suporte para entrada de texto livre

As opções predefinidas do Claude nem sempre cobrirão o que os usuários querem. Para permitir que os usuários digitem sua própria resposta:
  • Exiba uma escolha “Outro” adicional após as opções do Claude que aceita entrada de texto
  • Use o texto personalizado do usuário como o valor da resposta (não a palavra “Outro”)
Veja o exemplo completo abaixo para uma implementação completa.

Exemplo completo

Claude faz perguntas de esclarecimento quando precisa de entrada do usuário para prosseguir. Por exemplo, quando solicitado a ajudar a decidir sobre uma pilha de tecnologia para um aplicativo móvel, Claude pode perguntar sobre cross-platform vs nativo, preferências de backend ou plataformas alvo. Essas perguntas ajudam Claude a tomar decisões que correspondem às preferências do usuário em vez de adivinhar. Este exemplo lida com essas perguntas em um aplicativo de terminal. Aqui está o que acontece em cada etapa:
  1. Rotear a solicitação: O callback canUseTool verifica se o nome da ferramenta é "AskUserQuestion" e roteia para um manipulador dedicado
  2. Exibir perguntas: O manipulador percorre o array questions e imprime cada pergunta com opções numeradas
  3. Coletar entrada: O usuário pode inserir um número para selecionar uma opção ou digitar texto livre diretamente (por exemplo, “jquery”, “não sei”)
  4. Mapear respostas: O código verifica se a entrada é numérica (usa o label da opção) ou texto livre (usa o texto diretamente)
  5. Retornar ao Claude: A resposta inclui tanto o array questions original quanto o mapeamento answers
Salve a versão TypeScript como ask.ts e execute-a com npx tsx ask.ts, ou salve a versão Python como ask.py e execute-a com python ask.py.

Limitações

  • Subagentes: AskUserQuestion não está disponível em subagentes gerados por meio da ferramenta Agent
  • Limites de perguntas: cada chamada AskUserQuestion suporta 1-4 perguntas com 2-4 opções cada

Outras maneiras de obter entrada do usuário

O callback canUseTool e a ferramenta AskUserQuestion cobrem a maioria dos cenários de aprovação e esclarecimento, mas o SDK oferece outras maneiras de obter entrada dos usuários:

Entrada de streaming

Use entrada de streaming quando você precisar:
  • Interromper o agente no meio da tarefa: enviar um sinal de cancelamento ou mudar de direção enquanto Claude está trabalhando
  • Fornecer contexto adicional: adicionar informações que Claude precisa sem esperar que ele pergunte
  • Construir interfaces de chat: permitir que os usuários enviem mensagens de acompanhamento durante operações de longa duração
A entrada de streaming é ideal para interfaces conversacionais onde os usuários interagem com o agente durante toda a execução, não apenas em pontos de aprovação.

Ferramentas personalizadas

Use ferramentas personalizadas quando você precisar:
  • Coletar entrada estruturada: construir formulários, assistentes ou fluxos de trabalho de várias etapas que vão além do formato de múltipla escolha do AskUserQuestion
  • Integrar sistemas de aprovação externos: conectar a plataformas de ticketing, fluxo de trabalho ou aprovação existentes
  • Implementar interações específicas do domínio: criar ferramentas adaptadas às necessidades do seu aplicativo, como interfaces de revisão de código ou listas de verificação de implantação
As ferramentas personalizadas lhe dão controle total sobre a interação, mas requerem mais trabalho de implementação do que usar o callback canUseTool integrado.