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,55 @@
+---
+title: Agent questions
+description: >-
+  Learn how Warp's Agent asks questions for clarification, how to
+  answer or skip them, and how to interact with them when the Agent asks.
+---
+
+Agent questions let Warp's Agent pause to ask for your input when it needs a decision before continuing. Instead of guessing, the Agent presents a few options in an **Agent questions** card right inside the conversation and waits for your answer.
+
+## Key features
+
+* **Multiple-choice questions** - The Agent presents options for you to choose from instead of asking a 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 pauses and shows an **Agent questions** card in the conversation instead of guessing.
+
+Each question comes with a set list of options. Questions can accept single or multiple answers.  The Agent can flag a recommended option, or let you add your own answer under **Other**. When you answer or skip a question, Warp passes that back to the Agent so it can keep going with your response in mind.
+
+The Agent saves questions for moments when it genuinely can't move forward safely or accurately on its own. If you skip a question, Warp sends the skipped state to the Agent so it can continue with 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. Options are numbered, so press the matching number key (`1`, `2`, `3`, and so on) or click an option to select it. Multi-select questions show “select all that apply” next to the question text.
+2. If available, click **Other** or press its number key to enter your own answer, then press `Enter`.
+3. Click **Next** or press `Enter` to continue. For a single-select question, Warp automatically advances to the next question after you choose an option.
+4. When a card contains more than one question, press `←` to revisit the previous question or `→` to move to the next one. A question counter and **prev** / **next** controls appear at the bottom of the card.
+5. 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

@@ -278,6 +278,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [
 								{ 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/prompt-queueing', label: 'Prompt queueing' },
+                { 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',