pi-ask-questions 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -7,8 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-25
+
 ### Changed
 
+- Added explicit `mode: "urgent"` (blocking) and `mode: "background"` (default) choices. `noWait` remains a compatibility alias; an explicit mode takes precedence.
+- Background answers now use steering delivery at the next model/tool boundary instead of waiting in the follow-up queue.
+
 - Tabs preserve unfinished drafts, caret positions, and option cursors when revisiting questions.
 - Multiline extra answers support arrow-key editing between lines; PageUp and PageDown navigate long option lists.
 - Questionnaires show progress, live selection counts, and optional-question hints. The review tab preserves answer summaries while displaying specific validation errors.

package/README.md

@@ -53,7 +53,8 @@ Once installed, run `/ask-demo` to preview the UI, or just let the model call `a
 - **Optional questions** (`required: false`) that can be skipped, plus preset answers (`selected: true`) and defaults.
 - **Review tab** — see your answers and specific validation errors together before submitting; jump back to any question to edit it.
 - **Validation** — required answers and `min`/`max` selection counts are enforced before submit.
-- **Background mode** — set `noWait: true` and the tool returns immediately while the questionnaire stays open; the answers arrive later as a follow-up message.
+- **Urgent mode** — set `mode: "urgent"` to block further work until the questionnaire is answered or cancelled.
+- **Background mode** — use `mode: "background"` (the default) and the tool returns immediately while the questionnaire stays open; answers steer the active run at the next model/tool boundary.
 - **Safe cancel** — `Esc` arms cancellation, a second `Esc` or `Ctrl+C` cancels immediately.
 - **Scrollable option lists** — long lists show “n more above / below” indicators. Use `PageUp` / `PageDown` to move eight rows at a time.
 - **Structured results** — the tool returns text for the model and a machine-readable `structuredContent` payload for codemode scripts.
@@ -130,13 +131,25 @@ Notes: (skipped)
 | `questions[].min` / `max` | integer | Selection bounds for multi-select. |
 | `questions[].placeholder` | string | Placeholder for the free-form editor. |
 | `questions[].otherLabel` | string | Custom label for the typed-answer entry. |
-| `noWait` | boolean | Show the questionnaire in the background and return immediately (interactive TUI only). The answers arrive as a follow-up message. Only one background questionnaire can be open at a time. |
+| `mode` | `"urgent"` / `"background"` | `"urgent"` waits for answers. Default `"background"` returns immediately and delivers answers as steering (interactive TUI only; other interactive modes wait). Only one background questionnaire can be open at a time. |
+| `noWait` | boolean | Compatibility alias: `true` means background, `false` means urgent. An explicit `mode` takes precedence. |
+
+Choose `mode: "urgent"` when the model needs input before proceeding anywhere. Choose `mode: "background"` when it can continue independent work:
+
+```json
+{
+  "mode": "background",
+  "questions": [{ "question": "Which deployment environment should I use?" }]
+}
+```
+
+Background answers use Pi's steering queue, so they are considered at the next model/tool boundary instead of waiting for the agent to finish. Steering does not interrupt a response mid-token or abort a running tool. If the agent has already stopped, submitting answers starts a new turn. Cancellation is also reported. In RPC mode, both modes wait for the dialog answers.
 
 ### Structured results
 
 `structuredContent` mirrors the answers for codemode scripts: `cancelled`, an optional `pending`, and `answers[]` with `{ id, question, skipped, answers: [{ value, label, custom }] }`.
 
-While a background questionnaire is open, `pending` is `true` and each `answers[]` entry is a stub with an empty `answers` array. Branch on `pending` before reading them; the real answers arrive as a follow-up message.
+While a background questionnaire is open, `pending` is `true` and each `answers[]` entry is a stub with an empty `answers` array. Branch on `pending` before reading them; the real answers arrive as a steering message.
 
 ### Keyboard reference
 
@@ -159,8 +172,8 @@ In a multiline extra answer, `↑` / `↓` edits between text lines. Moving up f
 
 | Mode | Behavior |
 | --- | --- |
-| Interactive TUI | Full tabbed questionnaire. |
-| Interactive TUI + `noWait` | Tool returns immediately; answers are delivered as a follow-up message. |
+| Interactive TUI + `mode: "urgent"` | Full tabbed questionnaire; tool waits for answers before further work. |
+| Interactive TUI + `mode: "background"` (default) | Tool returns immediately; answers steer the active run at the next model/tool boundary. |
 | RPC | Sequential fallback built from the dialog API (`select` / `input`). |
 | Print / JSON | The tool reports that no UI is available and lists the questions so the model can ask them in plain text. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-ask-questions",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "Interactive questionnaires for Pi: tabs, multi-select, free-form typing, validation, and structured answers.",
 	"keywords": [
 		"pi-package",

package/src/extension.ts

@@ -28,13 +28,13 @@ import { runQuestionnaire, type QuestionnaireContext } from "./ui/ask-questionna
 /** Structured details stored with the tool result for rendering. */
 export interface AskToolDetails {
 	cancelled: boolean;
-	/** True while a noWait questionnaire is still open in the background. */
+	/** True while a background questionnaire is still open. */
 	pending?: boolean;
 	answers: QuestionAnswer[];
 	questions: NormalizedQuestion[];
 }
 
-const TOOL_DESCRIPTION = `Ask the user one or more questions and wait for their answers. Use it when you need a decision, preference, or piece of information that only the user can provide.
+const TOOL_DESCRIPTION = `Ask the user one or more questions, either blocking for answers or continuing in the background. Use it when you need a decision, preference, or piece of information that only the user can provide.
 
 The interactive UI supports:
 - Tabs: every question gets its own tab (Tab / Shift+Tab and arrow keys switch).
@@ -42,14 +42,16 @@ The interactive UI supports:
 - Free-form typing: a question with no options is a text prompt. Option questions can also hold one typed answer alongside the selected option(s) unless allowOther is false, and the answer is edited inline.
 - Optional questions (required: false) that can be skipped, preselected options (selected: true), and min/max selection counts.
 - Space or number keys 1-9 select or clear options without submitting; Enter confirms. A selects all; C clears a multi-select.
-- Set noWait: true to open the questionnaire in the background: the tool returns immediately and the answers arrive later as a follow-up message.
+- Set mode: "urgent" to wait for the user before proceeding with any further work.
+- Use mode: "background" (default) to continue independent work while the questionnaire stays open. Answers are injected as steering at the next model/tool boundary, before further work; they do not wait until the agent finishes. This does not abort an in-flight response or running tool.
+- noWait is a compatibility alias: true means background, false means urgent. An explicit mode takes precedence.
 
 Guidelines:
 - Prefer this tool over asking questions in prose when you actually need the answer to proceed.
 - Group related questions into one call (2-6 questions) instead of asking repeatedly.
 - Provide concrete, labeled options whenever you can; use a free-form question only when the answer space is open.
 - Put recommended options first.
-- Use noWait only when you can keep working without the answer; otherwise omit it so the answers arrive in the same turn.`;
+- Choose urgent when an answer is required before any further work; choose background only when you can continue independent work. In non-TUI interactive modes, background falls back to waiting for answers.`;
 
 const HELP_TEXT = `Interactive UI is not available in this mode. Ask the user the following questions directly in your reply instead:
 {{questions}}`;
@@ -92,8 +94,8 @@ function resultContent(result: AskResult): string {
 
 /** Start the questionnaire and wait for the user. */
 export default function askQuestionsExtension(pi: ExtensionAPI): void {
-	// A noWait questionnaire stays open after its tool call returns. It owns a
-	// session-scoped abort controller and reports its answers with a follow-up
+	// A background questionnaire stays open after its tool call returns. It owns a
+	// session-scoped abort controller and reports its answers with a steering
 	// message instead of a tool result.
 	let backgroundController: AbortController | undefined;
 	let shuttingDown = false;
@@ -116,7 +118,7 @@ export default function askQuestionsExtension(pi: ExtensionAPI): void {
 		promptGuidelines: [
 			"Use ask_user when you need a decision or missing detail from the user; batch related questions into one call instead of asking repeatedly.",
 			"Give ask_user questions labeled options where possible, keep them self-contained, and put recommended options first.",
-			"Set noWait only when you can keep working without the answers, for example to ask while investigating something else.",
+			'Use mode: "urgent" when input is required before proceeding anywhere. Use mode: "background" (default) for independent work; answers steer the active run at the next model/tool boundary.',
 		],
 		parameters: AskUserParamsSchema,
 		outputSchema: AskUserOutputSchema,
@@ -140,7 +142,8 @@ export default function askQuestionsExtension(pi: ExtensionAPI): void {
 
 			const submitLabel = params.submitLabel?.trim() || DEFAULT_SUBMIT_LABEL;
 
-			if (params.noWait === true && ctx.mode === "tui") {
+			const mode = params.mode ?? (params.noWait === false ? "urgent" : "background");
+			if (mode === "background" && ctx.mode === "tui") {
 				if (backgroundController) {
 					return {
 						content: [
@@ -172,7 +175,7 @@ export default function askQuestionsExtension(pi: ExtensionAPI): void {
 								display: true,
 								details: { cancelled: result.cancelled, answers: result.answers, questions },
 							},
-							{ triggerTurn: true, deliverAs: "followUp" },
+							{ triggerTurn: true, deliverAs: "steer" },
 						);
 					})
 					.catch((error: unknown) => {
@@ -199,7 +202,7 @@ export default function askQuestionsExtension(pi: ExtensionAPI): void {
 					content: [
 						{
 							type: "text",
-							text: `Questionnaire shown to the user in the background. Continue with other work; the answers will arrive as a follow-up message.`,
+							text: `Questionnaire shown to the user in the background. Continue with other work; the answers will be injected as steering at the next model/tool boundary. Incorporate them before continuing further work.`,
 						},
 					],
 					details: { cancelled: false, pending: true, answers: [], questions },

package/src/schema.ts

@@ -111,10 +111,16 @@ export const AskUserParamsSchema = Type.Object({
 		description:
 			"Questions to ask, in order. Each question gets its own tab; the user can move between tabs freely.",
 	}),
+	mode: Type.Optional(
+		Type.Union([Type.Literal("urgent"), Type.Literal("background")], {
+			description:
+				'"urgent" blocks further work until the questionnaire is answered or cancelled. "background" (default) returns immediately and injects answers as steering at the next model/tool boundary (interactive TUI only; other interactive modes wait). Takes precedence over noWait. Only one background questionnaire can be open at a time.',
+		}),
+	),
 	noWait: Type.Optional(
 		Type.Boolean({
 			description:
-				"Show the questionnaire in the background and return immediately instead of waiting for the user (interactive TUI only). The answers arrive later as a follow-up message. Useful when the answers are not needed right now. Only one background questionnaire can be open at a time.",
+				"Compatibility alias: true selects background mode, false selects urgent mode. Prefer mode; an explicit mode takes precedence.",
 		}),
 	),
 });
@@ -126,7 +132,7 @@ export const AskUserOutputSchema = Type.Object({
 	pending: Type.Optional(
 		Type.Boolean({
 			description:
-				"True when the questionnaire is still open in the background (noWait); answers arrive in a follow-up message.",
+				"True when the questionnaire is still open in background mode; answers arrive as a steering message.",
 		}),
 	),
 	answers: Type.Array(