# Commands and configuration

[Documentation index](README.md) · [Authoring guide](authoring-questions.md) · [Security and privacy](security-and-privacy.md)

## `ask_rich_questions`

The model-facing tool opens a form from explicit structured input. It is the preferred interface when the agent knows in advance that a decision needs full prompts, context, recommendations, caveats, or option-level tradeoffs. It supports `radio`, `checkbox`, and `text` questions; see [Authoring questions](authoring-questions.md) for the schema.

The tool is intentionally TUI-only. In another Pi mode it returns an error result with `details.cancelled: true` and does not try to create a custom component. A cancelled interactive form likewise returns cancellation rather than partial submitted answers.

## `/rich-questions`

Run `/rich-questions` after a completed assistant response. The command finds the latest completed assistant message with text, asks a model to extract all answerable questions in order, validates the returned JSON against the same tool schema, opens the form, and sends the completed result into a new agent turn.

In an empty session, the command offers a demo. Accepting sends `demo pi-rich-questions` as a normal user message so the active agent can demonstrate the tool; declining shows a usage hint.

Available subcommands:

```text
/rich-questions config
/rich-questions reset
```

`config` reopens model selection. `reset` stores session-model/low-thinking behavior immediately.

## First-run extraction setup

The first extraction asks you to choose:

- **Session model with low extraction thinking (recommended).** The model is resolved dynamically from the current session. Pi clamps `low` to the closest supported level; this mode does not copy the session's current thinking level.
- **Dedicated extraction model.** The searchable picker lists Pi's currently authenticated models by provider, model ID, and name. After choosing a model, choose one of the thinking levels that model supports. `low` is initially listed first and recommended for speed and lower cost.

Preferences are versioned JSON stored at `pi-rich-questions.json` in Pi's global agent directory—`~/.pi/agent` by default or the directory selected by `PI_CODING_AGENT_DIR`. The file is written with user-only permissions where the platform honors POSIX modes. Pi continues to own provider credentials; this extension does not write API keys to its settings file.

## Authentication, environment, and fallback

Models come from Pi's model registry, so login state, API keys, headers, and provider environment handling follow Pi's configuration. The dedicated picker only lists models Pi reports as available after refreshing the registry.

For a dedicated model, the command resolves and tries its credentials first. Session-model credentials are resolved lazily only if the configured model is missing, unauthenticated, throws, or returns structurally unusable JSON. The retry uses the current session model and the **session's current thinking setting**. If the configured and session attempt would be identical, it is not duplicated.

For session-model mode, the command tries the current authenticated session model with clamped low thinking. If no usable extraction attempt exists—or every attempt fails—it opens one optional multiline text question containing the **complete original assistant message**. This broad fallback favors preserving content over guessing structure.

## Extraction validation

The extraction system prompt requires a JSON object matching the public question schema and tells the model to preserve wording, explanations, recommendations, constraints, and options. Responses may be plain JSON or a JSON fenced block. TypeBox structural validation rejects malformed question types, missing required fields, malformed options, and other incompatible output.

When extracted question fields are all short, the command appends the complete original assistant message to that question's context as an additional safeguard. A valid `questions: []` result reports that no questions were found.

## Cost, latency, and privacy

`ask_rich_questions` itself only renders supplied questions. `/rich-questions` sends the latest completed assistant text to the chosen extraction provider, which adds latency and may incur provider cost. Lower thinking is recommended for extraction, but pricing and retention depend on your provider and account.

Do not run extraction over sensitive assistant content unless that provider is appropriate for the data. The completed answers return to the active Pi conversation and its model. Read [Security and privacy](security-and-privacy.md) for the full data-flow guidance.