pi-ask-user 0.2.0 → 0.3.0

package/README.md

@@ -2,12 +2,23 @@
 
 A Pi package that adds an interactive `ask_user` tool for collecting user decisions during an agent run.
 
+## Demo
+
+![ask_user demo](./media/ask-user-demo.gif)
+
+High-quality video: [ask-user-demo.mp4](./media/ask-user-demo.mp4)
+
 ## Features
 
 - Single-select option lists
 - Multi-select option lists
 - Optional freeform responses
 - Context display support
+- Overlay mode — dialog floats over conversation, preserving context
+- Custom TUI rendering for tool calls and results
+- System prompt integration via `promptSnippet` and `promptGuidelines`
+- Optional timeout for auto-dismiss (fallback input mode)
+- Structured `details` on all results for session state reconstruction
 - Graceful fallback when interactive UI is unavailable
 - Bundled `ask-user` skill for mandatory decision-gating in high-stakes or ambiguous tasks
 
@@ -28,12 +39,6 @@ The skill follows a "decision handshake" flow:
 
 See: `skills/ask-user/references/ask-user-skill-extension-spec.md`.
 
-## Demo
-
-![ask_user demo](./media/ask-user-demo.gif)
-
-High-quality video: [ask-user-demo.mp4](./media/ask-user-demo.mp4)
-
 ## Install
 
 ```bash
@@ -46,6 +51,17 @@ The registered tool name is:
 
 - `ask_user`
 
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `question` | `string` | *required* | The question to ask the user |
+| `context` | `string?` | — | Relevant context summary shown before the question |
+| `options` | `(string \| {title, description?})[]?` | `[]` | Multiple-choice options |
+| `allowMultiple` | `boolean?` | `false` | Enable multi-select mode |
+| `allowFreeform` | `boolean?` | `true` | Add a "Type something" freeform option |
+| `timeout` | `number?` | — | Auto-dismiss after N ms (applies to fallback input mode) |
+
 ## Example usage shape
 
 ```json
@@ -61,3 +77,31 @@ The registered tool name is:
 }
 ```
 
+## Result details
+
+All tool results include a structured `details` object for rendering and session state reconstruction:
+
+```typescript
+interface AskToolDetails {
+  question: string;
+  context?: string;
+  options: QuestionOption[];
+  answer: string | null;
+  cancelled: boolean;
+  wasCustom?: boolean;
+}
+```
+
+## Changelog
+
+### 0.3.0
+
+- Added `promptSnippet` and `promptGuidelines` for better LLM tool selection in the system prompt
+- Added `renderCall` and `renderResult` for custom TUI rendering (compact tool call display, ✓/Cancelled result indicators)
+- Added overlay mode — dialog now floats over the conversation instead of clearing the screen
+- Added `timeout` parameter for auto-dismiss in fallback input mode (when no options are provided)
+- Added structured `details` (`AskToolDetails`) to all result paths for session state reconstruction and branching support
+
+### 0.2.1
+
+- Initial public release

package/index.ts

@@ -37,6 +37,16 @@ interface AskParams {
 	options?: AskOptionInput[];
 	allowMultiple?: boolean;
 	allowFreeform?: boolean;
+	timeout?: number;
+}
+
+interface AskToolDetails {
+	question: string;
+	context?: string;
+	options: QuestionOption[];
+	answer: string | null;
+	cancelled: boolean;
+	wasCustom?: boolean;
 }
 
 function normalizeOptions(options: AskOptionInput[]): QuestionOption[] {
@@ -534,6 +544,12 @@ export default function (pi: ExtensionAPI) {
 		label: "Ask User",
 		description:
 			"Ask the user a question with optional multiple-choice answers. Use this to gather information interactively. Before calling, gather context with tools (read/exa/ref) and pass a short summary via the context field.",
+		promptSnippet:
+			"Ask the user a question with optional multiple-choice answers to gather information interactively",
+		promptGuidelines: [
+			"Before calling ask_user, gather context with tools (read/exa/ref) and pass a short summary via the context field.",
+			"Use ask_user when the user's intent is ambiguous, when a decision requires explicit user input, or when multiple valid options exist.",
+		],
 		parameters: Type.Object({
 			question: Type.String({ description: "The question to ask the user" }),
 			context: Type.Optional(
@@ -561,11 +577,17 @@ export default function (pi: ExtensionAPI) {
 			allowFreeform: Type.Optional(
 				Type.Boolean({ description: "Add a freeform text option. Default: true" }),
 			),
+			timeout: Type.Optional(
+				Type.Number({ description: "Auto-dismiss after N milliseconds (applies to fallback input mode when no options are provided)" }),
+			),
 		}),
 
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			if (signal?.aborted) {
-				return { content: [{ type: "text", text: "Cancelled" }] };
+				return {
+					content: [{ type: "text", text: "Cancelled" }],
+					details: { question: params.question, options: [], answer: null, cancelled: true } as AskToolDetails,
+				};
 			}
 
 			const {
@@ -574,6 +596,7 @@ export default function (pi: ExtensionAPI) {
 				options: rawOptions = [],
 				allowMultiple = false,
 				allowFreeform = true,
+				timeout,
 			} = params as AskParams;
 			const options = normalizeOptions(rawOptions);
 			const normalizedContext = context?.trim() || undefined;
@@ -590,36 +613,45 @@ export default function (pi: ExtensionAPI) {
 						},
 					],
 					isError: true,
-					details: { question, context: normalizedContext, options },
+					details: { question, context: normalizedContext, options, answer: null, cancelled: true } as AskToolDetails,
 				};
 			}
 
 			// If no options provided, fall back to freeform input prompt.
 			if (options.length === 0) {
 				const prompt = normalizedContext ? `${question}\n\nContext:\n${normalizedContext}` : question;
-				const answer = await ctx.ui.input(prompt, "Type your answer...");
+				const answer = await ctx.ui.input(prompt, "Type your answer...", timeout ? { timeout } : undefined);
 
 				if (!answer) {
-					return { content: [{ type: "text", text: "User cancelled the question" }] };
+					return {
+						content: [{ type: "text", text: "User cancelled the question" }],
+						details: { question, context: normalizedContext, options, answer: null, cancelled: true } as AskToolDetails,
+					};
 				}
 
-				return { content: [{ type: "text", text: `User answered: ${answer}` }] };
+				return {
+					content: [{ type: "text", text: `User answered: ${answer}` }],
+					details: { question, context: normalizedContext, options, answer, cancelled: false, wasCustom: true } as AskToolDetails,
+				};
 			}
 
 			let result: string | null;
 			try {
-				result = await ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
-					return new AskComponent(
-						question,
-						normalizedContext,
-						options,
-						allowMultiple,
-						allowFreeform,
-						tui,
-						theme,
-						done,
-					);
-				});
+				result = await ctx.ui.custom<string | null>(
+					(tui, theme, _kb, done) => {
+						return new AskComponent(
+							question,
+							normalizedContext,
+							options,
+							allowMultiple,
+							allowFreeform,
+							tui,
+							theme,
+							done,
+						);
+					},
+					{ overlay: true },
+				);
 			} catch (error) {
 				const message =
 					error instanceof Error ? `${error.message}\n${error.stack ?? ""}` : String(error);
@@ -631,10 +663,56 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			if (result === null) {
-				return { content: [{ type: "text", text: "User cancelled the question" }] };
+				return {
+					content: [{ type: "text", text: "User cancelled the question" }],
+					details: { question, context: normalizedContext, options, answer: null, cancelled: true } as AskToolDetails,
+				};
 			}
 
-			return { content: [{ type: "text", text: `User answered: ${result}` }] };
+			return {
+				content: [{ type: "text", text: `User answered: ${result}` }],
+				details: { question, context: normalizedContext, options, answer: result, cancelled: false } as AskToolDetails,
+			};
+		},
+
+		renderCall(args, theme) {
+			const question = (args.question as string) || "";
+			const rawOptions = Array.isArray(args.options) ? args.options : [];
+			let text = theme.fg("toolTitle", theme.bold("ask_user "));
+			text += theme.fg("muted", question);
+			if (rawOptions.length > 0) {
+				const labels = rawOptions.map((o: unknown) =>
+					typeof o === "string" ? o : (o as QuestionOption)?.title ?? "",
+				);
+				text += "\n" + theme.fg("dim", `  ${rawOptions.length} option(s): ${labels.join(", ")}`);
+			}
+			if (args.allowMultiple) {
+				text += theme.fg("dim", " [multi-select]");
+			}
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, _options, theme) {
+			const details = result.details as (AskToolDetails & { error?: string }) | undefined;
+
+			// Error state
+			if (details?.error) {
+				return new Text(theme.fg("error", `✗ ${details.error}`), 0, 0);
+			}
+
+			// Cancelled / no details
+			if (!details || details.cancelled) {
+				return new Text(theme.fg("warning", "Cancelled"), 0, 0);
+			}
+
+			// Success
+			const answer = details.answer ?? "";
+			let text = theme.fg("success", "✓ ");
+			if (details.wasCustom) {
+				text += theme.fg("muted", "(wrote) ");
+			}
+			text += theme.fg("accent", answer);
+			return new Text(text, 0, 0);
 		},
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ask-user",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Interactive ask_user tool for pi-coding-agent with multi-select and freeform input UI",
   "type": "module",
   "keywords": [

package/skills/ask-user/references/ask-user-skill-extension-spec.md

@@ -2,72 +2,13 @@
 
 ## Purpose
 
-Define how the `ask-user` skill (prompt-time behavior) and the `ask_user` extension tool (runtime UI) cooperate to create reliable human-in-the-loop decisions.
+This document defines a minimal decision-gating protocol for using the `ask-user` skill with the `ask_user` tool.
 
-This spec optimizes for:
-- explicit user control at decision boundaries
-- low-friction interactive UX
-- minimal context bloat (progressive disclosure)
-- deterministic behavior across high-stakes workflows
+Goal: require explicit user decisions at high-impact or ambiguous boundaries before implementation continues.
 
 ---
 
-## 1) 2026 Pattern Alignment
-
-This design intentionally follows three emerging patterns used by modern agent systems.
-
-### A. Progressive Disclosure
-
-The skill uses layered loading:
-
-1. **Metadata layer** (`name`, `description`) always in prompt.
-2. **Core protocol layer** (`SKILL.md`) loaded only when relevant.
-3. **Detailed reference layer** (`references/*.md`) loaded only when needed.
-
-Implication: keep `SKILL.md` concise and decision-focused; move large examples and policy details into references.
-
-### B. Agent Protocol Handshakes
-
-High-impact actions require a handshake:
-
-`detect boundary -> summarize evidence -> ask -> explicit user choice -> commit -> execute`
-
-The handshake prevents implicit assumptions from silently becoming implementation decisions.
-
-### C. Context-Aware Loading
-
-Questions must be formed from current evidence (repo state, docs, logs, external research), not from generic prompts.
-
-The `context` field in `ask_user` is the transport for this condensed evidence.
-
----
-
-## 2) System Model
-
-### Components
-
-1. **Skill layer (`skills/ask-user/SKILL.md`)**
-   - decides *when* user interaction is mandatory
-   - enforces handshake behavior
-
-2. **Extension layer (`index.ts`, tool `ask_user`)**
-   - renders question UX (single-select, multi-select, freeform)
-   - returns normalized answer text to the agent
-
-3. **Model runtime**
-   - interprets skill guidance
-   - calls `ask_user` with structured payload
-   - resumes execution after explicit user response
-
-### Contract boundary
-
-- Skill controls policy and decision gating.
-- Extension controls interaction mechanics.
-- Model must not bypass skill policy for high-stakes/ambiguous decisions.
-
----
-
-## 3) Trigger Matrix (When to Call `ask_user`)
+## 1) Trigger Matrix (When to Call `ask_user`)
 
 | Scenario | Must Ask? | Why |
 |---|---:|---|
@@ -82,122 +23,35 @@ The `context` field in `ask_user` is the transport for this condensed evidence.
 
 ---
 
-## 4) Handshake State Machine
-
-```text
-DISCOVER -> CLASSIFY -> (CLEAR -> EXECUTE)
-                     -> (AMBIGUOUS/HIGH_STAKES -> EVIDENCE -> ASK -> WAIT -> COMMIT -> EXECUTE)
-```
-
-### State definitions
+## 2) Decision Handshake
 
-- **DISCOVER**: inspect task and current project state.
-- **CLASSIFY**: decide whether decision gate is required.
-- **EVIDENCE**: gather and compress decision context.
-- **ASK**: invoke `ask_user` with a single focused decision.
-- **WAIT**: pause implementation until response arrives.
-- **COMMIT**: restate chosen option and intended next action.
-- **EXECUTE**: implement according to confirmed decision.
+Use this protocol whenever the trigger matrix says to ask.
 
-### Cancellation behavior
-
-If user cancels or response is unclear:
-- enforce a **max two-attempt budget** for the same decision boundary
-- attempt 1: normal structured question
-- attempt 2: narrower question with explicit recommendation + `Proceed with recommendation / Choose another / Stop`
-
-After attempt 2:
-- for `high_stakes` or `both`: do not continue; report blocked status
-- for `ambiguous` only: proceed only when user delegates choice (e.g., "your call"), using the most reversible default and explicit assumptions
-
----
-
-## 5) `ask_user` Payload Design Standard
-
-### Field mapping
-
-| Field | Required | Rule |
-|---|---:|---|
-| `question` | Yes | One decision only, concrete and action-bound |
-| `context` | Recommended | 3-7 bullets or short paragraph with evidence and trade-offs |
-| `options` | Optional | Prefer 2-5 choices when stable alternatives exist |
-| `allowMultiple` | Optional | `true` only for independent selections |
-| `allowFreeform` | Optional | Usually `true`; set `false` only when strict menu required |
+1. **Detect boundary**
+   - classify as `high_stakes`, `ambiguous`, `both`, or `clear`
+2. **Gather evidence**
+   - read code/docs/logs first; do not ask blindly
+3. **Summarize context**
+   - prepare concise trade-off context (3–7 bullets or short paragraph)
+4. **Ask one focused question**
+   - call `ask_user` for one decision at a time
+5. **Commit and proceed**
+   - restate chosen option and implement accordingly
 
-### Style rules
+### Retry/cancel policy
 
-- Keep options concise, decision-oriented, and contrastive.
-- Include brief descriptions for non-obvious trade-offs.
-- Avoid stacking unrelated questions.
-- Ask after evidence gathering, not before.
+- Max **2** `ask_user` attempts for the same decision boundary.
+- Attempt 1: normal structured question.
+- Attempt 2: narrower question with recommendation and explicit options.
+- After attempt 2:
+  - `high_stakes` / `both`: stop and report blocked.
+  - `ambiguous` only: proceed only if user delegates (e.g., “your call”), using the most reversible default.
 
 ---
 
-## 6) UX Guidance for Best Outcomes
+## 3) Example Payloads
 
-### Good interaction shape
-
-1. Agent summarizes known constraints.
-2. Agent asks one clear question.
-3. User selects an option quickly (or writes freeform).
-4. Agent confirms and proceeds.
-
-### Avoid
-
-- long speculative context dumps
-- “What do you want?” without options
-- repeated confirmation of unchanged decisions
-- more than two attempts for the same decision boundary
-- hidden assumptions after user response
-
-### Recommended defaults
-
-- `allowFreeform: true`
-- `allowMultiple: false`
-- `options`: include concise titles + descriptions for trade-offs
-
----
-
-## 7) Runtime and Fallback Semantics
-
-The extension already provides these behavior guarantees:
-
-1. **Interactive mode with UI**
-   - single-select list, multi-select list, or freeform editor
-
-2. **No options provided**
-   - freeform input prompt is used
-
-3. **No interactive UI available**
-   - tool returns an error-style textual fallback that includes question/context/options
-
-Design implication:
-- skill should prefer structured options when ambiguity is high
-- but always permit freeform for unanticipated requirements
-
----
-
-## 8) Quality Rubric
-
-A decision-gated interaction is successful when all are true:
-
-- [ ] High-stakes or ambiguous boundary was detected
-- [ ] Context was gathered before asking
-- [ ] At most two decision questions were asked for the same boundary (normally one)
-- [ ] User response was explicit
-- [ ] Agent restated decision before execution
-- [ ] Implementation followed the selected path
-
-Failure signals:
-- agent made architectural choice without user decision
-- question lacked trade-off context
-- user answer ignored or overwritten
-
----
-
-## 9) Example Protocol Templates
-
-### Template: architecture fork
+### Architecture decision
 
 ```json
 {
@@ -212,7 +66,7 @@ Failure signals:
 }
 ```
 
-### Template: ambiguity cleanup
+### Requirement-priority decision
 
 ```json
 {
@@ -227,24 +81,3 @@ Failure signals:
   "allowFreeform": true
 }
 ```
-
----
-
-## 10) Packaging + Distribution Notes
-
-To ship this skill with the extension package:
-
-- include `skills/` in npm package files
-- register skills in `package.json` under `pi.skills`
-
-This ensures the skill is discoverable at startup and available for implicit invocation.
-
----
-
-## 11) Future Enhancements (Optional)
-
-- **Decision memory log**: append chosen options to a lightweight session decision ledger.
-- **Adaptive option generation**: tailor options by repo language/framework context.
-- **Confidence thresholding**: auto-trigger ask gate when model confidence in requirements is low.
-
-These are optional and not required for initial rollout.