AskUserQuestion). Ambas activan su callback canUseTool, que pausa la ejecución hasta que devuelva una respuesta. Esto es diferente de los turnos de conversación normales donde Claude termina y espera su próximo mensaje.
Para preguntas aclaratorias, Claude genera las preguntas y opciones. Su función es presentarlas a los usuarios y devolver sus selecciones. No puede agregar sus propias preguntas a este flujo; si necesita preguntarle algo a los usuarios usted mismo, hágalo por separado en la lógica de su aplicación.
El callback puede permanecer pendiente indefinidamente. La ejecución permanece pausada hasta que su callback regrese, y el SDK solo cancela la espera cuando la consulta misma se cancela. Si un usuario podría tardar más en responder de lo que su proceso puede razonablemente mantenerse ejecutando, devuelva la decisión del hook defer, que permite que el proceso salga y se reanude más tarde desde la sesión persistida.
Esta guía le muestra cómo detectar cada tipo de solicitud y responder apropiadamente.
Detectar cuándo Claude necesita entrada
Pase un callbackcanUseTool en sus opciones de consulta. El callback se activa cada vez que Claude necesita entrada del usuario, recibiendo el nombre de la herramienta y la entrada como argumentos:
- La herramienta necesita aprobación: Claude quiere usar una herramienta que no está aprobada automáticamente por una regla de permisos o modo de permisos. Verifique
tool_namepara la herramienta (por ejemplo,"Bash","Write"). - Claude hace una pregunta: Claude llama a la herramienta
AskUserQuestion. Verifique sitool_name == "AskUserQuestion"para manejarlo de manera diferente. Si especifica un arraytools, incluyaAskUserQuestionpara que esto funcione. Vea Manejar preguntas aclaratorias para más detalles.
PermissionRequest para enviar notificaciones externas (Slack, correo electrónico, push) cuando Claude está esperando aprobación.
Manejar solicitudes de aprobación de herramientas
Una vez que haya pasado un callbackcanUseTool en sus opciones de consulta, se activa cuando Claude quiere usar una herramienta que nada anterior en el flujo de permisos ha aprobado. Su callback recibe tres argumentos:
El objeto
input contiene parámetros específicos de la herramienta. Ejemplos comunes:
Vea la referencia del SDK para esquemas de entrada completos: Python | TypeScript.
Puede mostrar esta información al usuario para que pueda decidir si permitir o rechazar la acción, luego devolver la respuesta apropiada.
El siguiente ejemplo le pide a Claude que cree y elimine un archivo de prueba. Cuando Claude intenta cada operación, el callback imprime la solicitud de herramienta en la terminal y solicita aprobación s/n.
En Python,
can_use_tool requiere modo de flujo. Cuando pasa un flujo de mensajes finito a través de query(prompt=generator) o ClaudeSDKClient.connect(prompt=async_iterable), el SDK cierra el flujo de entrada después del último mensaje, antes de que se pueda invocar el callback de permiso, a menos que un hook registrado o un servidor MCP en proceso lo mantenga abierto. El ejemplo anterior lo mantiene abierto con un hook PreToolUse que devuelve {"continue_": True}. Conectarse sin un aviso y enviar mensajes a través de ClaudeSDKClient.query() mantiene el flujo abierto por sí solo y no necesita ningún hook.y se trata como una denegación. En la práctica, podría construir una interfaz de usuario más rica que permita a los usuarios modificar la solicitud, proporcionar retroalimentación o redirigir a Claude completamente. Vea Responder a solicitudes de herramientas para todas las formas en que puede responder.
Responder a solicitudes de herramientas
Su callback devuelve uno de dos tipos de respuesta:
Al permitir, la herramienta se ejecuta con la entrada que Claude solicitó a menos que devuelva una entrada modificada,
updatedInput en TypeScript o updated_input en Python. Antes de v2.1.207, Claude Code rechazaba un resultado de permiso que omitía updatedInput y denegaba la llamada de herramienta con un error de validación.
Al denegar, proporcione un mensaje explicando por qué. Claude ve este mensaje y puede ajustar su enfoque.
- Aprobar: permitir que la herramienta se ejecute como Claude solicitó
- Aprobar con cambios: modificar la entrada antes de la ejecución (por ejemplo, desinfectar rutas, agregar restricciones)
- Aprobar y recordar: devolver una regla de permiso sugerida para que las llamadas coincidentes omitan el aviso la próxima vez
- Rechazar: bloquear la herramienta y decirle a Claude por qué
- Sugerir alternativa: bloquear pero guiar a Claude hacia lo que el usuario quiere en su lugar
- Redirigir completamente: usar entrada de flujo para enviar a Claude una instrucción completamente nueva
- Aprobar
- Aprobar con cambios
- Aprobar y recordar
- Rechazar
- Sugerir alternativa
- Redirigir completamente
El usuario aprueba la acción tal como está. Pase la
input de su callback sin cambios y la herramienta se ejecuta exactamente como Claude solicitó.Manejar preguntas aclaratorias
Cuando Claude necesita más dirección en una tarea con múltiples enfoques válidos, llama a la herramientaAskUserQuestion. Esto activa su callback canUseTool con toolName establecido en AskUserQuestion. La entrada contiene las preguntas de Claude como opciones de opción múltiple, que muestra al usuario y devuelve sus selecciones.
Los siguientes pasos muestran cómo manejar preguntas aclaratorias:
1
Pasar un callback canUseTool
Pase un callback
canUseTool en sus opciones de consulta. De forma predeterminada, AskUserQuestion está disponible. Si especifica un array tools para restringir las capacidades de Claude (por ejemplo, un agente de solo lectura con solo Read, Glob y Grep), incluya AskUserQuestion en ese array. De lo contrario, Claude no podrá hacer preguntas aclaratorias:2
Detectar AskUserQuestion
En su callback, verifique si
toolName es igual a AskUserQuestion para manejarlo de manera diferente a otras herramientas:3
Analizar la entrada de la pregunta
La entrada contiene las preguntas de Claude en un array Vea Formato de pregunta para descripciones completas de campos.
questions. Cada pregunta tiene una question (el texto a mostrar), options (las opciones) y multiSelect (si se permiten múltiples selecciones):4
Recopilar respuestas del usuario
Presente las preguntas al usuario y recopile sus selecciones. Cómo lo hace depende de su aplicación: un indicador de terminal, un formulario web, un diálogo móvil, etc.
5
Devolver respuestas a Claude
Construya el objeto
answers como un registro donde cada clave es el texto question y cada valor es la label de la opción seleccionada:Para preguntas de selección múltiple, pase un array de etiquetas o únalas con
", ". Si admite entrada de texto libre, use el texto personalizado del usuario como valor.Formato de pregunta
La entrada contiene las preguntas generadas por Claude en un arrayquestions. Cada pregunta tiene estos campos:
La estructura que su callback recibe:
Vistas previas de opciones (TypeScript)
toolConfig.askUserQuestion.previewFormat agrega un campo preview a cada opción para que su aplicación pueda mostrar una maqueta visual junto a la etiqueta. Sin esta configuración, Claude no genera vistas previas y el campo está ausente.
El formato se aplica a todas las preguntas en la sesión. Claude incluye
preview en opciones donde una comparación visual ayuda (opciones de diseño, esquemas de color) y la omite donde no lo haría (confirmaciones sí/no, opciones de solo texto). Verifique undefined antes de renderizar.
Formato de respuesta
Devuelva un objetoanswers que asigne cada campo question de la pregunta a la label de la opción seleccionada:
Para preguntas de selección múltiple, pase un array de etiquetas o únalas con
", ". Para entrada de texto libre por pregunta, como una opción “Otro”, coloque el texto del usuario en answers[question] como se muestra en Admitir entrada de texto libre. Establezca response solo cuando su interfaz de usuario permita al usuario descartar la tarjeta de pregunta y escribir una respuesta general que no sea una respuesta a ninguna pregunta específica. Cuando response está establecido, Claude recibe “El usuario respondió: …” en lugar de la lista de respuestas por pregunta.
Admitir entrada de texto libre
Las opciones predefinidas de Claude no siempre cubrirán lo que los usuarios quieren. Para permitir que los usuarios escriban su propia respuesta:- Muestre una opción “Otro” adicional después de las opciones de Claude que acepte entrada de texto
- Use el texto personalizado del usuario como valor de respuesta (no la palabra “Otro”)
Ejemplo completo
Claude hace preguntas aclaratorias cuando necesita entrada del usuario para proceder. Por ejemplo, cuando se le pide que ayude a decidir sobre una pila de tecnología para una aplicación móvil, Claude podría preguntar sobre multiplataforma vs nativo, preferencias de backend o plataformas objetivo. Estas preguntas ayudan a Claude a tomar decisiones que coincidan con las preferencias del usuario en lugar de adivinar. Este ejemplo maneja esas preguntas en una aplicación de terminal. Esto es lo que sucede en cada paso:- Enrutar la solicitud: El callback
canUseToolverifica si el nombre de la herramienta es"AskUserQuestion"y enruta a un manejador dedicado - Mostrar preguntas: El manejador recorre el array
questionse imprime cada pregunta con opciones numeradas - Recopilar entrada: El usuario puede ingresar un número para seleccionar una opción, o escribir texto libre directamente (por ejemplo, “jquery”, “i don’t know”)
- Asignar respuestas: El código verifica si la entrada es numérica (usa la etiqueta de la opción) o texto libre (usa el texto directamente)
- Devolver a Claude: La respuesta incluye tanto el array
questionsoriginal como el mapeoanswers
ask.ts y ejecútela con npx tsx ask.ts, o guarde la versión de Python como ask.py y ejecútela con python ask.py.
Limitaciones
- Subagentes:
AskUserQuestionno está disponible actualmente en subagentes generados a través de la herramienta Agent - Límites de preguntas: cada llamada
AskUserQuestionadmite 1-4 preguntas con 2-4 opciones cada una
Otras formas de obtener entrada del usuario
El callbackcanUseTool y la herramienta AskUserQuestion cubren la mayoría de escenarios de aprobación y aclaración, pero el SDK ofrece otras formas de obtener entrada de los usuarios:
Entrada de flujo
Use entrada de flujo cuando necesite:- Interrumpir el agente a mitad de tarea: enviar una señal de cancelación o cambiar de dirección mientras Claude está trabajando
- Proporcionar contexto adicional: agregar información que Claude necesita sin esperar a que la solicite
- Construir interfaces de chat: permitir que los usuarios envíen mensajes de seguimiento durante operaciones de larga duración
Herramientas personalizadas
Use herramientas personalizadas cuando necesite:- Recopilar entrada estructurada: construir formularios, asistentes o flujos de trabajo de varios pasos que vayan más allá del formato de opción múltiple de
AskUserQuestion - Integrar sistemas de aprobación externos: conectarse a plataformas de tickets, flujo de trabajo o aprobación existentes
- Implementar interacciones específicas del dominio: crear herramientas adaptadas a las necesidades de su aplicación, como interfaces de revisión de código o listas de verificación de implementación
canUseTool integrado.
Recursos relacionados
- Configurar permisos: configurar modos y reglas de permisos
- Controlar la ejecución con hooks: ejecutar código personalizado en puntos clave del ciclo de vida del agente
- Referencia del SDK de TypeScript: documentación completa de la API canUseTool