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 callbackcanUseTool 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:
- Ferramenta precisa de aprovação: Claude quer usar uma ferramenta que não é aprovada automaticamente por regras de permissão ou modos. Verifique
tool_namepara a ferramenta (por exemplo,"Bash","Write"). - Claude faz uma pergunta: Claude chama a ferramenta
AskUserQuestion. Verifique setool_name == "AskUserQuestion"para tratá-la diferentemente. Se você especificar um arraytools, incluaAskUserQuestionpara que isso funcione. Veja Lidar com perguntas de esclarecimento para detalhes.
Para permitir ou negar automaticamente ferramentas sem solicitar aos usuários, use hooks em vez disso. Os hooks são executados antes de
canUseTool e podem permitir, negar ou modificar solicitações com base em sua própria lógica. 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 callbackcanUseTool nas opções de sua consulta, ele é acionado quando Claude quer usar uma ferramenta que não é aprovada automaticamente. Seu callback recebe três argumentos:
| Argumento | Descrição |
|---|---|
toolName | O nome da ferramenta que Claude quer usar (por exemplo, "Bash", "Write", "Edit") |
input | Os parâmetros que Claude está passando para a ferramenta. O conteúdo varia por ferramenta. |
options (TS) / context (Python) | Contexto adicional incluindo suggestions opcional (entradas PermissionUpdate propostas para evitar re-solicitação) e um sinal de cancelamento. Em TypeScript, signal é um AbortSignal; em Python, o campo de sinal é reservado para uso futuro. Veja ToolPermissionContext para Python. |
input contém parâmetros específicos da ferramenta. Exemplos comuns:
| Ferramenta | Campos de entrada |
|---|---|
Bash | command, description, timeout |
Write | file_path, content |
Edit | file_path, old_string, new_string |
Read | file_path, offset, limit |
Em Python,
can_use_tool requer modo de streaming e um hook PreToolUse que retorna {"continue_": True} para manter o fluxo aberto. Sem este hook, o fluxo fecha antes que o callback de permissão possa ser invocado.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:| Resposta | Python | TypeScript |
|---|---|---|
| Permitir | PermissionResultAllow(updated_input=...) | { behavior: "allow", updatedInput } |
| Negar | PermissionResultDeny(message=...) | { behavior: "deny", message } |
- 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
- Aprovar
- Aprovar com alterações
- Aprovar e lembrar
- Rejeitar
- Sugerir alternativa
- Redirecionar completamente
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 ferramentaAskUserQuestion. 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.
Os passos a seguir mostram como lidar com perguntas de esclarecimento:
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:Detecte AskUserQuestion
Em seu callback, verifique se
toolName é igual a AskUserQuestion para tratá-lo diferentemente de outras ferramentas:Analise a entrada da pergunta
A entrada contém as perguntas do Claude em um array Veja Formato de pergunta para descrições completas de campos.
questions. Cada pergunta tem uma question (o texto a exibir), options (as escolhas) e multiSelect (se múltiplas seleções são permitidas):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.
Retorne respostas ao Claude
Construa o objeto
Para perguntas de seleção múltipla, passe um array de labels ou junte-os com
answers como um registro onde cada chave é o texto question e cada valor é o label da opção selecionada:| Do objeto de pergunta | Use como |
|---|---|
Campo question (por exemplo, "How should I format the output?") | Chave |
Campo label da opção selecionada (por exemplo, "Summary") | Valor |
", ". 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 arrayquestions. Cada pergunta tem estes campos:
| Campo | Descrição |
|---|---|
question | O texto completo da pergunta a exibir |
header | Rótulo curto para a pergunta (máximo 12 caracteres) |
options | Array de 2-4 escolhas, cada uma com label e description. TypeScript: opcionalmente preview (veja abaixo) |
multiSelect | Se true, os usuários podem selecionar múltiplas opções |
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.
previewFormat | preview contém |
|---|---|
| não definido (padrão) | Campo está ausente. Claude não gera visualizações. |
"markdown" | Arte ASCII e blocos de código cercados |
"html" | Um fragmento <div> estilizado (o SDK rejeita <script>, <style> e <!DOCTYPE> antes que seu callback seja executado) |
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.
Formato de resposta
Retorne um objetoanswers mapeando cada campo question da pergunta para o label da opção selecionada:
| Campo | Descrição |
|---|---|
questions | Passe o array de perguntas original (obrigatório para processamento de ferramentas) |
answers | Objeto onde as chaves são texto de pergunta e os valores são labels selecionados |
response | Resposta freeform opcional que o usuário digitou em vez de responder às perguntas estruturadas |
", ". 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”)
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:- Rotear a solicitação: O callback
canUseToolverifica se o nome da ferramenta é"AskUserQuestion"e roteia para um manipulador dedicado - Exibir perguntas: O manipulador percorre o array
questionse imprime cada pergunta com opções numeradas - 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”)
- Mapear respostas: O código verifica se a entrada é numérica (usa o label da opção) ou texto livre (usa o texto diretamente)
- Retornar ao Claude: A resposta inclui tanto o array
questionsoriginal quanto o mapeamentoanswers
Limitações
- Subagentes:
AskUserQuestionnão está disponível em subagentes gerados por meio da ferramenta Agent - Limites de perguntas: cada chamada
AskUserQuestionsuporta 1-4 perguntas com 2-4 opções cada
Outras maneiras de obter entrada do usuário
O callbackcanUseTool 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
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
canUseTool integrado.
Recursos relacionados
- Configurar permissões: configurar modos e regras de permissão
- Controlar execução com hooks: executar código personalizado em pontos-chave do ciclo de vida do agente
- Referência do SDK TypeScript: documentação completa da API canUseTool