> ## 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/context/knowledge-base), o [`@graphview`](/pt/tools/graphview), a [memória/perfil](/pt/context/bootstrap-memory) e o [`context_pull`](/pt/context/prefix-curation) — 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 cinco, todas inofensivas por construção: o `ask_user` (interativa), a [consulta read-only à knowledge base](/pt/context/knowledge-base) (`/config chat knowledge`), o [`@graphview`](/pt/tools/graphview) (renderização única, `/config chat graphview`), o [`context_pull`](/pt/context/prefix-curation) (recuperação read-only do material curado para fora do prefixo, `/config chat pull`) e a [memória](/pt/context/bootstrap-memory) (`/config chat memory` — persiste fatos duráveis que você revela no mesmo turno **e** carrega o caminho de pull que permite ao chat honrar o modo de memória `index`: digest compacto, recall sob demanda, blocos proativos de auto-recall/session-recall/card do grafo). 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/agents/native-tool-use) — como as chamadas estruturadas funcionam
* [Modo Agente](/pt/usage/agent-mode)
* [Modo Coder](/pt/usage/coder-mode)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.