Preguntas Interactivas

Las herramientas de Planu están diseñadas para actuar de forma autónoma por defecto. Cuando una herramienta no puede continuar sin la entrada del usuario — porque una acción es irreversible, ambigua o está bloqueada por una política — devuelve un InteractiveQuestion[] en lugar de bloquear la llamada o hacer una suposición silenciosa.

Por qué las Herramientas Devuelven Preguntas

El diseño autopilot-first significa que las herramientas eligen el valor por defecto más seguro y continúan cuando sea posible. Pero algunas decisiones deben ser explícitas:

• Acciones destructivas. Desplegar a producción, eliminar una spec, sobrescribir contenido bloqueado.
• Entradas ambiguas. Múltiples specs coinciden con un término de búsqueda; la herramienta no puede elegir por ti.
• Puertas de política. Aprobar una spec con 0 criterios que pasan requiere confirmación explícita.

En lugar de lanzar un error o quedarse colgada, la herramienta devuelve un array de preguntas estructuradas. El LLM recibe este array en la respuesta de la herramienta, transmite cada pregunta al usuario vía AskUserQuestion, recopila las respuestas y vuelve a invocar la herramienta con las respuestas suministradas como argumentos.

Sin I/O bloqueante

Las herramientas nunca bloquean en la entrada del usuario. La llamada siempre devuelve inmediatamente — ya sea con un resultado o con InteractiveQuestion[]. Esto hace que las herramientas sean seguras de usar en pipelines asíncronos y bucles de agente.

El Tipo InteractiveQuestion

{
  "id": "confirm-target-env",
  "question": "¿A qué entorno debe desplegarse esto?",
  "type": "choice",
  "options": ["staging", "production"],
  "default": "staging"
}

Campo	Tipo	Descripción
id	string	Identificador único — usado para hacer coincidir respuestas con preguntas en la re-invocación
question	string	Texto de la pregunta legible por humanos
type	enum	choice / multiChoice / text / confirm
options	string[]	Opciones válidas para tipos choice y multiChoice
default	any	Valor preseleccionado — usado en modo autónomo
required	boolean	Si es false, la herramienta puede continuar con el default si el usuario omite la respuesta

Tipos de Preguntas

Tipo	Comportamiento
choice	Selección única de una lista options fija
multiChoice	Selecciones múltiples de una lista options fija
text	Entrada de texto libre — validada contra pattern si se proporciona
confirm	Booleano sí/no — se mapea a true / false

Cómo el LLM Transmite las Preguntas

1. El LLM invoca la herramienta (ej. update_status("SPEC-NNN", "approved"))
2. La herramienta detecta una condición de puerta (0 criterios que pasan)
3. La herramienta devuelve { interactiveQuestions: [ { id: "confirm-low-criteria", ... } ] }
4. El LLM lee el array
5. El LLM llama a AskUserQuestion con el texto de la pregunta
6. El usuario responde "sí"
7. El LLM re-invoca: update_status("SPEC-NNN", "approved", { answers: { "confirm-low-criteria": true } })
8. La herramienta supera la puerta

En Claude Code, el mecanismo de transmisión es la herramienta integrada AskUserQuestion. En otros hosts, el patrón es el mismo pero el mecanismo de transmisión difiere (ej. un endpoint HTTP o un campo de entrada de UI de chat).

Cuándo Esperar Preguntas

Herramienta	Cuándo devuelve preguntas
create_spec	Cuando el título coincide con una spec existente (verificación de duplicados)
update_status(approved)	Cuando check_readiness devuelve 0 criterios que pasan
update_status(done)	Cuando validate encuentra criterios de aceptación no cumplidos
deploy_spec	Cuando el entorno objetivo es production
delete_spec	Siempre — la eliminación es irreversible
lock_spec	Cuando la spec está en estado draft (inusual bloquear temprano)

Modo Autónomo y Preguntas

En Modo Autónomo, Planu usa el campo default de cada pregunta en lugar de transmitirla al usuario. Esto permite ejecuciones de pipeline completamente desatendidas. Si una pregunta no tiene default y required es true, el modo autónomo bloqueará la transición y mostrará la pregunta al operador.

---

Ver también

• Transiciones de Estado Automáticas — transiciones que desencadenan preguntas
• Modo Autónomo — cómo el modo autónomo maneja preguntas usando valores por defecto