From 49f3148fd3446604ccb0ac03bb39c299c28906c1 Mon Sep 17 00:00:00 2001 From: seemeroland Date: Fri, 29 May 2026 21:10:43 +0000 Subject: [PATCH 1/4] docs: document Agent questions behavior Co-Authored-By: Oz --- .../agent-profiles-permissions.mdx | 13 +++++ .../agent-questions.mdx | 56 +++++++++++++++++++ .../agent-platform/local-agents/overview.mdx | 1 + src/sidebar.ts | 1 + 4 files changed, 71 insertions(+) create mode 100644 src/content/docs/agent-platform/local-agents/interacting-with-agents/agent-questions.mdx diff --git a/src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx b/src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx index d7da4531..86206f6f 100644 --- a/src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx +++ b/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/))
![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)
@@ -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: diff --git a/src/content/docs/agent-platform/local-agents/interacting-with-agents/agent-questions.mdx b/src/content/docs/agent-platform/local-agents/interacting-with-agents/agent-questions.mdx new file mode 100644 index 00000000..154ec71d --- /dev/null +++ b/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. diff --git a/src/content/docs/agent-platform/local-agents/overview.mdx b/src/content/docs/agent-platform/local-agents/overview.mdx index 5a96c27d..b6f90fb0 100644 --- a/src/content/docs/agent-platform/local-agents/overview.mdx +++ b/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. diff --git a/src/sidebar.ts b/src/sidebar.ts index 9c56c366..88694dfa 100644 --- a/src/sidebar.ts +++ b/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', From ea44bec96370c8ddadb32ca69e386f2535005dc4 Mon Sep 17 00:00:00 2001 From: Leon Fattakhov Date: Tue, 9 Jun 2026 13:54:43 -0400 Subject: [PATCH 2/4] docs: document keyboard navigation for Agent questions Note that options can be selected with number keys and that the left and right arrow keys move between questions on a multi-question card. Co-Authored-By: Oz --- .../agent-questions.mdx | 23 +++++++++---------- 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/src/content/docs/agent-platform/local-agents/interacting-with-agents/agent-questions.mdx b/src/content/docs/agent-platform/local-agents/interacting-with-agents/agent-questions.mdx index 154ec71d..9473cb15 100644 --- a/src/content/docs/agent-platform/local-agents/interacting-with-agents/agent-questions.mdx +++ b/src/content/docs/agent-platform/local-agents/interacting-with-agents/agent-questions.mdx @@ -1,13 +1,11 @@ --- 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. + 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 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. +Agent questions let Warp's Agent pause and ask for your input when it needs a decision before continuing. Instead of guessing and risking the wrong approach, the Agent presents a few options in an **Agent questions** card right inside the conversation and waits for your answer. ## Key features @@ -20,20 +18,21 @@ Use this page to understand when the Agent asks questions, what kinds of answers ## 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. +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 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. +Each question comes with a set list of options. Some accept a single answer, others let you pick several, and the Agent can flag a recommended option or let you add your own under **Other**. When you answer or skip, Warp passes that straight back to the Agent so it can keep going 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. +The Agent saves questions for moments when it genuinely can't move forward safely or accurately on its own. And if you skip a question, it won't ask the same one again—it continues 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. 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`. +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 **Other** appears and none of the listed options fit, click **Other** or press its number key, enter your answer, and 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. From ca27caa10b209add7d614988f8d9edff5cd93708 Mon Sep 17 00:00:00 2001 From: Leon Fattakhov <17069243+coolcom200@users.noreply.github.com> Date: Tue, 9 Jun 2026 15:41:13 -0400 Subject: [PATCH 3/4] Update src/content/docs/agent-platform/local-agents/interacting-with-agents/agent-questions.mdx Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com> --- .../local-agents/interacting-with-agents/agent-questions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/agent-platform/local-agents/interacting-with-agents/agent-questions.mdx b/src/content/docs/agent-platform/local-agents/interacting-with-agents/agent-questions.mdx index 9473cb15..9027888c 100644 --- a/src/content/docs/agent-platform/local-agents/interacting-with-agents/agent-questions.mdx +++ b/src/content/docs/agent-platform/local-agents/interacting-with-agents/agent-questions.mdx @@ -22,7 +22,7 @@ When the Agent needs a decision from you before it can continue confidently, it Each question comes with a set list of options. Some accept a single answer, others let you pick several, and the Agent can flag a recommended option or let you add your own under **Other**. When you answer or skip, Warp passes that straight 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. And if you skip a question, it won't ask the same one again—it continues with the context it already has. +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 From 8ade78c0275d3c359242fa3f000b781db41a7238 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 9 Jun 2026 16:28:54 -0600 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> --- .../interacting-with-agents/agent-questions.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/agent-platform/local-agents/interacting-with-agents/agent-questions.mdx b/src/content/docs/agent-platform/local-agents/interacting-with-agents/agent-questions.mdx index 9027888c..2bc02dec 100644 --- a/src/content/docs/agent-platform/local-agents/interacting-with-agents/agent-questions.mdx +++ b/src/content/docs/agent-platform/local-agents/interacting-with-agents/agent-questions.mdx @@ -5,11 +5,11 @@ description: >- answer or skip them, and how to interact with them when the Agent asks. --- -Agent questions let Warp's Agent pause and ask for your input when it needs a decision before continuing. Instead of guessing and risking the wrong approach, the Agent presents a few options in an **Agent questions** card right inside the conversation and waits for your answer. +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 an open-ended freeform question. +* **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. @@ -20,7 +20,7 @@ Agent questions let Warp's Agent pause and ask for your input when it needs a de 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. Some accept a single answer, others let you pick several, and the Agent can flag a recommended option or let you add your own under **Other**. When you answer or skip, Warp passes that straight back to the Agent so it can keep going with your response in mind. +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. @@ -29,7 +29,7 @@ The Agent saves questions for moments when it genuinely can't move forward safel 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 **Other** appears and none of the listed options fit, click **Other** or press its number key, enter your answer, and press `Enter`. +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`.