> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Perguntas Interativas (ask_user)

> A IA pergunta e você decide num menu navegável: 1 a 6 perguntas, single ou multi-select e opção livre, com as respostas voltando ao modelo no mesmo turno.

Quando o modelo precisa de uma decisão sua — qual abordagem seguir, qual alvo usar, confirmar um plano — em vez de escrever *"me diga A ou B"* em texto solto, ele chama a ferramenta **`ask_user`** (`@ask`). Você responde num **overlay interativo** (Bubble Tea, o mesmo motor do command palette) e as seleções voltam estruturadas ao modelo **no mesmo turno**. É o equivalente ao `AskUserQuestion` do Claude Code.

***

## Onde funciona

| Modo                 | Disponível             | Observação                                                                                                                                                                                                                                                              |
| :------------------- | :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Agent** (`/agent`) | ✅                      | Junto das demais tools (nativo ou via XML)                                                                                                                                                                                                                              |
| **Coder** (`/coder`) | ✅                      | Idem, sob a mesma política de segurança                                                                                                                                                                                                                                 |
| **Chat**             | ✅ (exceção controlada) | Chat é tool-less por design; abre exceção **apenas** para `ask_user`, a [consulta read-only à knowledge base](/pt/features/knowledge-base), o [`@graphview`](/pt/features/graphview) e a [memória/perfil](/pt/features/bootstrap-memory) — nunca para tools de execução |

***

## A interface

Cada chamada traz de 1 a 6 perguntas. Para cada pergunta:

* um **cabeçalho** curto e o **texto** da pergunta;
* uma lista de **opções** (rótulo + descrição);
* **single-select** (radio `(•)`) ou **multi-select** (checkbox `[x]`);
* uma linha **"Other"** para digitar uma resposta livre.

### Controles

| Tecla     | Ação                                                                   |
| :-------- | :--------------------------------------------------------------------- |
| `↑` / `↓` | Move o cursor                                                          |
| `espaço`  | Marca/desmarca (multi) · marca o radio (single) · foca o campo "Other" |
| `enter`   | Confirma a pergunta e avança (finaliza após a última)                  |
| `esc`     | Volta à pergunta anterior · cancela na primeira                        |
| digitar   | Preenche o campo "Other" (quando focado)                               |

```text theme={"system"}
[1/2] Banco de dados
Qual banco devo usar?

❯ (•) Postgres   Relacional, ACID
  ( ) SQLite     Embarcado, zero-config
  [+] Other (digite uma resposta)…

↑/↓ mover · espaço/enter selecionar · esc voltar/cancelar
```

***

## Single vs múltipla escolha

Quem decide é o **modelo**, por pergunta, através do campo `multiSelect`:

* `multiSelect: false` (ou omitido) → escolha única (radios).
* `multiSelect: true` → múltipla escolha (checkboxes `[x]`); o `espaço` marca/desmarca vários e o `enter` confirma o conjunto.

Para induzir múltipla escolha, basta pedir: *"me pergunte, permitindo múltipla escolha, quais ambientes…"*.

***

## Exceção no modo chat

O modo chat é **tool-less por design** — ele nunca executa tools. As exceções sancionadas são quatro, todas inofensivas por construção: o `ask_user` (interativa), a [consulta read-only à knowledge base](/pt/features/knowledge-base) (`/config chat knowledge`), o [`@graphview`](/pt/features/graphview) (renderização única, `/config chat graphview`) e a [memória/perfil](/pt/features/bootstrap-memory) (`/config chat memory` — persiste fatos duráveis que você revela, no mesmo turno). Quando habilitadas, o chat oferece **exclusivamente** essas ferramentas (nenhuma de leitura de arquivos/escrita/execução).

Funciona com qualquer provider:

* **Providers com tools nativas** (Claude por API key, OpenAI…): turno de decisão estruturado.
* **Providers sem tools nativas** (ex.: Claude em modo OAuth): turno de decisão via XML, com o formato injetado e o markup suprimido antes de chegar à tela.

Em ambos os casos, depois que você responde, o **mesmo spinner do prompt** do turno normal aparece enquanto a IA elabora a resposta final.

### Ligar/desligar

A exceção do chat vem **ligada por padrão** e pode ser controlada em runtime:

```bash theme={"system"}
/config chat                 # status: modo (native/XML) e se está ativo
/config chat ask on          # ativa
/config chat ask off         # desativa (chat volta 100% sem tools)
/config chat ask toggle      # inverte
```

Para um padrão permanente, defina no `.env`:

```bash theme={"system"}
CHATCLI_CHAT_ASK=true   # (padrão) ou false para desligar
```

<Note>
  Com a exceção ligada, cada turno de chat passa por um turno de decisão **buffered** (necessário para detectar/suprimir a chamada antes de exibi-la). Se preferir o streaming token-a-token no dia a dia, use `/config chat ask off`.
</Note>

***

## Contextos não-interativos

Em execução desassistida (gateway/daemon), pipe ou one-shot (`-p`) **não há terminal** para o overlay. Nesses casos o `ask_user` **não trava**: retorna a **primeira opção** de cada pergunta como fallback determinístico, deixando claro que foi auto-selecionado, e o fluxo segue.

***

## Resultado para o modelo

A resposta volta como um resumo legível seguido de um bloco JSON canônico, para que tanto modelos fracos quanto fortes interpretem sem ambiguidade:

```text theme={"system"}
User answered:
- Banco de dados → Postgres
- Ambientes → staging, prod

{"answers":[
  {"header":"Banco de dados","selected":["Postgres"],"other":""},
  {"header":"Ambientes","selected":["staging","prod"],"other":""}
]}
```

Cancelar (Esc) não é erro: o modelo recebe um aviso de que você não respondeu e segue com defaults razoáveis ou pergunta de novo em texto.

***

## Veja também

* [Tool Use Nativo](/pt/features/native-tool-use) — como as chamadas estruturadas funcionam
* [Modo Agente](/pt/core-concepts/agent-mode)
* [Modo Coder](/pt/core-concepts/coder-mode)