docs: Document Agent questions behavior

src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx

@@ -46,6 +46,7 @@ You can control how much autonomy the Agent has when performing different types
 * Create plans
 * Execute commands
 * Interact with running commands (via [Full Terminal Use](/agent-platform/capabilities/full-terminal-use/))
+* Ask clarifying questions (via [Agent questions](/agent-platform/local-agents/interacting-with-agents/agent-questions/))
 
 <div align="center">![Fine-tuning agent control: This permissions panel lets users customize how much autonomy the Agent has when applying code diffs, reading files, creating plans, and executing commands.](../../../../assets/agent-platform/agent-permissions-with-full-terminal-use.png)</div>
 
@@ -59,6 +60,18 @@ For **Apply code diffs**, `Agent decides` currently behaves the same as `Always
 When all Agent permissions are set to **Always allow**, the Agent gains full autonomy (“YOLO mode”); however, any denylist rules will still override these settings.
 :::
 
+### Ask questions
+
+The **Ask questions** permission controls whether the Agent can pause a conversation to ask you clarifying questions before continuing.
+
+The available settings are:
+
+* **Never ask** - The Agent does not pause for clarifying questions and continues with its best judgment.
+* **Ask unless auto-approve** - The Agent can ask during normal conversations, but questions are skipped while auto-approve is on.
+* **Always ask** - The Agent can pause for your answer even when auto-approve is on.
+
+For the full user flow, see [Agent questions](/agent-platform/local-agents/interacting-with-agents/agent-questions/).
+
 ### Command allowlist
 
 The Agent lets you define an allowlist of commands that run automatically without confirmation. It’s empty by default, but users often add read-only commands such as:

src/content/docs/agent-platform/local-agents/interacting-with-agents/agent-questions.mdx

@@ -0,0 +1,56 @@
+---
+title: Agent questions
+description: >-
+  Learn how Warp's Agent questions and AskUserQuestion tool pause conversations
+  for clarifying input, how answers work, and how to control the behavior.
+---
+
+Agent questions are clarifying prompts that let Warp's Agent pause a conversation and ask for your input before continuing. In tool-call history, API traces, or source code, this behavior may appear as `AskUserQuestion`, `ask_user_question`, or user-question handling; in Warp, it appears as an **Agent questions** card.
+
+Use this page to understand when the Agent asks questions, what kinds of answers are supported, and how Agent Profile permissions change the behavior.
+
+## Key features
+
+* **Multiple-choice questions** - The Agent presents options for you to choose from instead of asking an open-ended freeform question.
+* **Single-select and multi-select answers** - Some questions accept one answer, while others let you select all options that apply.
+* **Other answers** - When the Agent enables an **Other** option, you can type your own answer and submit it from the card.
+* **Multiple questions** - A single card can contain multiple questions, with navigation controls for moving between them.
+* **Skip support** - You can skip questions. The Agent receives the skipped state and continues with its best judgment.
+* **Permission controls** - Agent Profiles include an **Ask questions** permission that controls whether the Agent pauses for your answer.
+
+## How it works
+
+When the Agent needs a decision from you before it can continue confidently, it can call the `ask_user_question` tool. Warp renders that tool call as an **Agent questions** card inside the conversation.
+
+Each question has a fixed list of options. The Agent can mark a question as single-select or multi-select, recommend one option for a single-select question, and allow an **Other** answer. Warp sends your selected options, any **Other** answer text, or the skipped status back to the Agent so it can continue with your response in mind.
+
+The Agent should only ask questions when the task cannot be completed safely or accurately without additional input. If you skip a question, the Agent should not ask the same question again; it should continue using the context it already has.
+
+## Answering Agent questions
+
+When an **Agent questions** card appears, choose the option or options that best match your intent.
+
+1. Select one or more options in the card. Multi-select questions show “select all that apply” next to the question text.
+2. If **Other** appears and none of the listed options fit, click **Other**, enter your answer, and press `Enter`.
+3. Click **Next** or press `Enter` to continue. For a single-select question, Warp may advance to the next question after you choose an option.
+4. To skip the remaining questions, click **Skip all** or press `Ctrl+C`.
+
+After you answer or skip the questions, Warp summarizes the result in the conversation. You can expand the completed card to review the answers that were sent to the Agent.
+
+## Controlling when the Agent asks questions
+
+The **Ask questions** permission is part of each Agent Profile. To change it, open the Warp app and go to **Settings** > **Agents** > **Profiles** > **Permissions**, then edit the active profile.
+
+The available settings are:
+
+* **Never ask** - The Agent does not pause for clarifying questions. Warp skips the question and the Agent continues with its best judgment.
+* **Ask unless auto-approve** - The Agent can pause for your answer during normal conversations, but Warp skips questions while auto-approve is on.
+* **Always ask** - The Agent can pause for your answer even when auto-approve is on.
+
+Auto-approve is designed for unattended execution. If you want the Agent to keep running without pausing for clarifying questions, use **Ask unless auto-approve** or **Never ask**.
+
+## Related pages
+
+* [Terminal and Agent modes](/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes/) - Start and navigate Agent conversations in Warp.
+* [Profiles & permissions](/agent-platform/capabilities/agent-profiles-permissions/) - Configure Agent Profile permissions and autonomy settings.
+* [Agent notifications](/agent-platform/capabilities/agent-notifications/) - Learn how Warp notifies you when an Agent needs your input.

src/content/docs/agent-platform/local-agents/overview.mdx

@@ -25,6 +25,7 @@ Warp's client is open source under [AGPL v3](https://github.com/warpdotdev/warp/
 This section covers how to interact with Warp's agents and the capabilities available during agent conversations:
 
 * [Interacting with Agents](/agent-platform/local-agents/interacting-with-agents/) - Manage AI conversations tied to sessions, attach context, continue previous threads, or start new ones.
+* [Agent questions](/agent-platform/local-agents/interacting-with-agents/agent-questions/) - Answer, skip, and configure clarifying questions the Agent asks during a conversation.
 * [Agent Context](/agent-platform/local-agents/agent-context/) - Attach images, URLs, files, code blocks, and selections as context for your prompts.
 * [Model Choice](/agent-platform/inference/model-choice/) - Pick your preferred LLM from a curated set of top models, or let Warp choose the optimal one.
 * [Full Terminal Use](/agent-platform/capabilities/full-terminal-use/) - Let the agent drive interactive terminal apps, seeing live output and running commands.

src/sidebar.ts

@@ -277,6 +277,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [
 							items: [
 								{ slug: 'agent-platform/local-agents/interacting-with-agents', label: 'Overview' },
 								'agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes',
+								{ slug: 'agent-platform/local-agents/interacting-with-agents/agent-questions', label: 'Agent questions' },
 								{ slug: 'agent-platform/local-agents/interacting-with-agents/conversation-forking', label: 'Conversation forking' },
 								{ slug: 'agent-platform/local-agents/code-diffs', label: 'Code diffs' },
 								'agent-platform/local-agents/interacting-with-agents/voice',