pi-ask-tool-extension 0.2.2 → 0.2.4

package/README.md

@@ -24,6 +24,8 @@ This extension provides:
 - **Single + multi-select** in one tool
 - **Tab-based multi-question flow** with a final submit review tab
 - **Inline note editing** (no large UI pane shifts)
+- **Question text auto-wrap** (avoids one-line `...` truncation)
+- **Optional Markdown context** for longer explanations/structure diagrams
 - **Automatic `Other (type your own)` handling**
 
 ## Install
@@ -157,6 +159,24 @@ Response:
   Selected: Redis
 ```
 
+### Question with Markdown context (long guidance / structure)
+
+```ts
+ask({
+  questions: [
+    {
+      id: "architecture",
+      question: "Which execution path should we prioritize?",
+      description: `# Background\n\n- Current bottleneck: network I/O\n- Goal: reduce response latency\n\n\`\`\`text\n[Client] -> [API] -> [Cache] -> [DB]\n\`\`\``,
+      options: [{ label: "Cache-first" }, { label: "DB-first" }],
+      recommended: 0
+    }
+  ]
+})
+```
+
+`description` accepts both Markdown and plain text, and is wrapped above options.
+
 ## Interaction Model
 
 | Flow | UI style | Submit behavior |
@@ -170,7 +190,7 @@ Response:
 Press `Tab` on any option to edit a note inline on that same row.
 
 - Display format: `Option — note: ...`
-- Editing cursor: `▍`
+- Editing cursor: inverse block on the character under caret (or space at end)
 - Notes are sanitized for inline display (line breaks/control chars)
 - Narrow-width rendering keeps the edit cursor visible
 
@@ -192,6 +212,7 @@ For `Other`, a note is required to become valid.
     {
       id: string,
       question: string,
+      description?: string, // optional Markdown/plain context shown above options
       options: [{ label: string }],
       multi?: boolean,
       recommended?: number // 0-indexed
@@ -229,4 +250,5 @@ Coverage gate defaults (override via env vars in CI if needed):
 - `src/ask-inline-ui.ts` - single-question UI
 - `src/ask-tabs-ui.ts` - tabbed multi-question UI
 - `src/ask-inline-note.ts` - inline note rendering helper
+- `src/ask-text-wrap.ts` - shared line-wrapping helper for long prompts
 - `test/*.test.ts` - logic + UI mapping + integration coverage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ask-tool-extension",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Ask tool extension for pi with tabbed questioning and inline note editing",
   "repository": {
     "type": "git",

package/src/ask-inline-editor-cursor.ts

@@ -0,0 +1,20 @@
+interface CursorReadableEditor {
+	getLines(): string[];
+	getCursor(): { line: number; col: number };
+}
+
+export function getLinearCursorIndexFromEditor(editor: CursorReadableEditor): number {
+	const lines = editor.getLines();
+	const cursor = editor.getCursor();
+	if (lines.length === 0) return 0;
+
+	const safeLineIndex = Math.max(0, Math.min(cursor.line, lines.length - 1));
+	const safeColumnIndex = Math.max(0, Math.min(cursor.col, lines[safeLineIndex]?.length ?? 0));
+	let linearCursorIndex = safeColumnIndex;
+
+	for (let lineIndex = 0; lineIndex < safeLineIndex; lineIndex++) {
+		linearCursorIndex += (lines[lineIndex]?.length ?? 0) + 1;
+	}
+
+	return linearCursorIndex;
+}

package/src/ask-inline-note.ts

@@ -1,7 +1,8 @@
 import { wrapTextWithAnsi } from "@mariozechner/pi-tui";
 
 const INLINE_NOTE_SEPARATOR = " — note: ";
-const INLINE_EDIT_CURSOR = "▍";
+const INLINE_EDIT_CURSOR_INVERT_ON = "\u001b[7m";
+const INLINE_EDIT_CURSOR_INVERT_OFF = "\u001b[27m";
 
 export const INLINE_NOTE_WRAP_PADDING = 2;
 
@@ -9,6 +10,24 @@ function sanitizeNoteForInlineDisplay(rawNote: string): string {
 	return rawNote.replace(/[\r\n\t]/g, " ").replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, "");
 }
 
+function clampCursorIndex(index: number, rawTextLength: number): number {
+	if (!Number.isFinite(index)) return rawTextLength;
+	if (index < 0) return 0;
+	if (index > rawTextLength) return rawTextLength;
+	return Math.floor(index);
+}
+
+function buildEditingInlineNote(rawNote: string, editingCursorIndex?: number): string {
+	const cursorIndex = clampCursorIndex(editingCursorIndex ?? rawNote.length, rawNote.length);
+	const beforeCursor = sanitizeNoteForInlineDisplay(rawNote.slice(0, cursorIndex));
+	const rawCharAtCursor = rawNote.slice(cursorIndex, cursorIndex + 1);
+	const charAtCursor = sanitizeNoteForInlineDisplay(rawCharAtCursor) || " ";
+	const afterCursorStartIndex = rawCharAtCursor.length > 0 ? cursorIndex + 1 : cursorIndex;
+	const afterCursor = sanitizeNoteForInlineDisplay(rawNote.slice(afterCursorStartIndex));
+	const cursorCell = `${INLINE_EDIT_CURSOR_INVERT_ON}${charAtCursor}${INLINE_EDIT_CURSOR_INVERT_OFF}`;
+	return `${beforeCursor}${cursorCell}${afterCursor}`;
+}
+
 function truncateTextKeepingTail(text: string, maxLength: number): string {
 	if (maxLength <= 0) return "";
 	if (text.length <= maxLength) return text;
@@ -28,6 +47,7 @@ export function buildOptionLabelWithInlineNote(
 	rawNote: string,
 	isEditingNote: boolean,
 	maxInlineLabelLength?: number,
+	editingCursorIndex?: number,
 ): string {
 	const sanitizedNote = sanitizeNoteForInlineDisplay(rawNote);
 	if (!isEditingNote && sanitizedNote.trim().length === 0) {
@@ -35,7 +55,7 @@ export function buildOptionLabelWithInlineNote(
 	}
 
 	const labelPrefix = `${baseOptionLabel}${INLINE_NOTE_SEPARATOR}`;
-	const inlineNote = isEditingNote ? `${sanitizedNote}${INLINE_EDIT_CURSOR}` : sanitizedNote.trim();
+	const inlineNote = isEditingNote ? buildEditingInlineNote(rawNote, editingCursorIndex) : sanitizedNote.trim();
 	const inlineLabel = `${labelPrefix}${inlineNote}`;
 
 	if (maxInlineLabelLength == null) {
@@ -53,8 +73,15 @@ export function buildWrappedOptionLabelWithInlineNote(
 	isEditingNote: boolean,
 	maxInlineLabelLength: number,
 	wrapPadding = INLINE_NOTE_WRAP_PADDING,
+	editingCursorIndex?: number,
 ): string[] {
-	const inlineLabel = buildOptionLabelWithInlineNote(baseOptionLabel, rawNote, isEditingNote);
+	const inlineLabel = buildOptionLabelWithInlineNote(
+		baseOptionLabel,
+		rawNote,
+		isEditingNote,
+		undefined,
+		editingCursorIndex,
+	);
 	const sanitizedWrapPadding = Number.isFinite(wrapPadding) ? Math.max(0, Math.floor(wrapPadding)) : 0;
 	const sanitizedMaxInlineLabelLength = Number.isFinite(maxInlineLabelLength)
 		? Math.max(1, Math.floor(maxInlineLabelLength))

package/src/ask-inline-ui.ts

@@ -1,5 +1,14 @@
 import type { ExtensionUIContext } from "@mariozechner/pi-coding-agent";
-import { Editor, type EditorTheme, Key, matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+import {
+	Editor,
+	Markdown,
+	type EditorTheme,
+	type MarkdownTheme,
+	Key,
+	matchesKey,
+	truncateToWidth,
+	visibleWidth,
+} from "@mariozechner/pi-tui";
 import {
 	OTHER_OPTION,
 	appendRecommendedTagToOptionLabels,
@@ -7,10 +16,13 @@ import {
 	type AskOption,
 	type AskSelection,
 } from "./ask-logic";
+import { getLinearCursorIndexFromEditor } from "./ask-inline-editor-cursor";
 import { INLINE_NOTE_WRAP_PADDING, buildWrappedOptionLabelWithInlineNote } from "./ask-inline-note";
+import { appendWrappedTextLines } from "./ask-text-wrap";
 
 interface SingleQuestionInput {
 	question: string;
+	description?: string;
 	options: AskOption[];
 	recommended?: number;
 }
@@ -49,6 +61,7 @@ export async function askSingleQuestionWithInlineNote(
 		let cursorOptionIndex = initialCursorIndex;
 		let isNoteEditorOpen = false;
 		let cachedRenderedLines: string[] | undefined;
+		let cachedRenderedWidth: number | undefined;
 		const noteByOptionIndex = new Map<number, string>();
 
 		const editorTheme: EditorTheme = {
@@ -62,9 +75,32 @@ export async function askSingleQuestionWithInlineNote(
 			},
 		};
 		const noteEditor = new Editor(tui, editorTheme);
+		const markdownTheme: MarkdownTheme = {
+			heading: (text) => theme.fg("mdHeading", text),
+			link: (text) => theme.fg("mdLink", text),
+			linkUrl: (text) => theme.fg("mdLinkUrl", text),
+			code: (text) => theme.fg("mdCode", text),
+			codeBlock: (text) => theme.fg("mdCodeBlock", text),
+			codeBlockBorder: (text) => theme.fg("mdCodeBlockBorder", text),
+			quote: (text) => theme.fg("mdQuote", text),
+			quoteBorder: (text) => theme.fg("mdQuoteBorder", text),
+			hr: (text) => theme.fg("mdHr", text),
+			listBullet: (text) => theme.fg("mdListBullet", text),
+			bold: (text) => theme.bold(text),
+			italic: (text) => theme.italic(text),
+			strikethrough: (text) => theme.strikethrough(text),
+			underline: (text) => theme.underline(text),
+		};
+		const questionDescriptionMarkdown =
+			questionInput.description && questionInput.description.trim().length > 0
+				? new Markdown(questionInput.description, 0, 0, markdownTheme, {
+						color: (text) => theme.fg("muted", text),
+					})
+				: undefined;
 
 		const requestUiRerender = () => {
 			cachedRenderedLines = undefined;
+			cachedRenderedWidth = undefined;
 			tui.requestRender();
 		};
 
@@ -106,15 +142,28 @@ export async function askSingleQuestionWithInlineNote(
 		};
 
 		const render = (width: number): string[] => {
-			if (cachedRenderedLines) return cachedRenderedLines;
+			if (cachedRenderedLines && cachedRenderedWidth === width) return cachedRenderedLines;
 
 			const renderedLines: string[] = [];
 			const addLine = (line: string) => renderedLines.push(truncateToWidth(line, width));
 
 			addLine(theme.fg("accent", "─".repeat(width)));
-			addLine(theme.fg("text", ` ${questionInput.question}`));
+			appendWrappedTextLines(renderedLines, questionInput.question, width, {
+				indent: 1,
+				formatLine: (line) => theme.fg("text", line),
+			});
+			if (questionDescriptionMarkdown) {
+				renderedLines.push("");
+				const descriptionLines = questionDescriptionMarkdown.render(Math.max(1, width - 1));
+				for (const descriptionLine of descriptionLines) {
+					addLine(` ${descriptionLine}`);
+				}
+			}
 			renderedLines.push("");
 
+			const activeEditingCursorIndex = isNoteEditorOpen
+				? getLinearCursorIndexFromEditor(noteEditor)
+				: undefined;
 			for (let optionIndex = 0; optionIndex < selectableOptionLabels.length; optionIndex++) {
 				const optionLabel = selectableOptionLabels[optionIndex];
 				const isCursorOption = optionIndex === cursorOptionIndex;
@@ -131,6 +180,7 @@ export async function askSingleQuestionWithInlineNote(
 					isEditingThisOption,
 					Math.max(1, width - prefixWidth),
 					INLINE_NOTE_WRAP_PADDING,
+					isEditingThisOption ? activeEditingCursorIndex : undefined,
 				);
 				const continuationPrefix = " ".repeat(prefixWidth);
 				addLine(`${cursorPrefix}${theme.fg(optionColor, `${markerText}${wrappedInlineLabelLines[0] ?? ""}`)}`);
@@ -151,10 +201,16 @@ export async function askSingleQuestionWithInlineNote(
 
 			addLine(theme.fg("accent", "─".repeat(width)));
 			cachedRenderedLines = renderedLines;
+			cachedRenderedWidth = width;
 			return renderedLines;
 		};
 
 		const handleInput = (data: string) => {
+			if (matchesKey(data, Key.ctrl("c"))) {
+				done({ cancelled: true });
+				return;
+			}
+
 			if (isNoteEditorOpen) {
 				if (matchesKey(data, Key.tab) || matchesKey(data, Key.escape)) {
 					isNoteEditorOpen = false;
@@ -208,6 +264,7 @@ export async function askSingleQuestionWithInlineNote(
 			render,
 			invalidate: () => {
 				cachedRenderedLines = undefined;
+				cachedRenderedWidth = undefined;
 			},
 			handleInput,
 		};

package/src/ask-logic.ts

@@ -8,6 +8,7 @@ export interface AskOption {
 export interface AskQuestion {
 	id: string;
 	question: string;
+	description?: string;
 	options: AskOption[];
 	multi?: boolean;
 	recommended?: number;

package/src/ask-tabs-ui.ts

@@ -1,5 +1,14 @@
 import type { ExtensionUIContext } from "@mariozechner/pi-coding-agent";
-import { Editor, type EditorTheme, Key, matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+import {
+	Editor,
+	Markdown,
+	type EditorTheme,
+	type MarkdownTheme,
+	Key,
+	matchesKey,
+	truncateToWidth,
+	visibleWidth,
+} from "@mariozechner/pi-tui";
 import {
 	OTHER_OPTION,
 	appendRecommendedTagToOptionLabels,
@@ -8,11 +17,14 @@ import {
 	type AskQuestion,
 	type AskSelection,
 } from "./ask-logic";
+import { getLinearCursorIndexFromEditor } from "./ask-inline-editor-cursor";
 import { INLINE_NOTE_WRAP_PADDING, buildWrappedOptionLabelWithInlineNote } from "./ask-inline-note";
+import { appendWrappedTextLines } from "./ask-text-wrap";
 
 interface PreparedQuestion {
 	id: string;
 	question: string;
+	description?: string;
 	options: string[];
 	tabLabel: string;
 	multi: boolean;
@@ -120,6 +132,7 @@ export async function askQuestionsWithTabs(
 		return {
 			id: question.id,
 			question: question.question,
+			description: question.description,
 			options: optionLabels,
 			tabLabel: normalizeTabLabel(question.id, `Q${questionIndex + 1}`),
 			multi: question.multi === true,
@@ -135,6 +148,7 @@ export async function askQuestionsWithTabs(
 		let activeTabIndex = 0;
 		let isNoteEditorOpen = false;
 		let cachedRenderedLines: string[] | undefined;
+		let cachedRenderedWidth: number | undefined;
 		const cursorOptionIndexByQuestion = [...initialCursorOptionIndexByQuestion];
 		const selectedOptionIndexesByQuestion = preparedQuestions.map(() => [] as number[]);
 		const noteByQuestionByOption = preparedQuestions.map((preparedQuestion) =>
@@ -152,11 +166,35 @@ export async function askQuestionsWithTabs(
 			},
 		};
 		const noteEditor = new Editor(tui, editorTheme);
+		const markdownTheme: MarkdownTheme = {
+			heading: (text) => theme.fg("mdHeading", text),
+			link: (text) => theme.fg("mdLink", text),
+			linkUrl: (text) => theme.fg("mdLinkUrl", text),
+			code: (text) => theme.fg("mdCode", text),
+			codeBlock: (text) => theme.fg("mdCodeBlock", text),
+			codeBlockBorder: (text) => theme.fg("mdCodeBlockBorder", text),
+			quote: (text) => theme.fg("mdQuote", text),
+			quoteBorder: (text) => theme.fg("mdQuoteBorder", text),
+			hr: (text) => theme.fg("mdHr", text),
+			listBullet: (text) => theme.fg("mdListBullet", text),
+			bold: (text) => theme.bold(text),
+			italic: (text) => theme.italic(text),
+			strikethrough: (text) => theme.strikethrough(text),
+			underline: (text) => theme.underline(text),
+		};
+		const descriptionMarkdownByQuestion = preparedQuestions.map((preparedQuestion) =>
+			preparedQuestion.description && preparedQuestion.description.trim().length > 0
+				? new Markdown(preparedQuestion.description, 0, 0, markdownTheme, {
+						color: (text) => theme.fg("muted", text),
+					})
+				: undefined,
+		);
 
 		const submitTabIndex = preparedQuestions.length;
 
 		const requestUiRerender = () => {
 			cachedRenderedLines = undefined;
+			cachedRenderedWidth = undefined;
 			tui.requestRender();
 		};
 
@@ -314,9 +352,23 @@ export async function askQuestionsWithTabs(
 			const cursorOptionIndex = cursorOptionIndexByQuestion[questionIndex];
 			const selectedOptionIndexes = selectedOptionIndexesByQuestion[questionIndex];
 
-			addLine(theme.fg("text", ` ${preparedQuestion.question}`));
+			appendWrappedTextLines(renderedLines, preparedQuestion.question, width, {
+				indent: 1,
+				formatLine: (line) => theme.fg("text", line),
+			});
+			const questionDescriptionMarkdown = descriptionMarkdownByQuestion[questionIndex];
+			if (questionDescriptionMarkdown) {
+				renderedLines.push("");
+				const descriptionLines = questionDescriptionMarkdown.render(Math.max(1, width - 1));
+				for (const descriptionLine of descriptionLines) {
+					addLine(` ${descriptionLine}`);
+				}
+			}
 			renderedLines.push("");
 
+			const activeEditingCursorIndex = isNoteEditorOpen
+				? getLinearCursorIndexFromEditor(noteEditor)
+				: undefined;
 			for (let optionIndex = 0; optionIndex < preparedQuestion.options.length; optionIndex++) {
 				const optionLabel = preparedQuestion.options[optionIndex];
 				const isCursorOption = optionIndex === cursorOptionIndex;
@@ -335,6 +387,7 @@ export async function askQuestionsWithTabs(
 					isEditingThisOption,
 					Math.max(1, width - prefixWidth),
 					INLINE_NOTE_WRAP_PADDING,
+					isEditingThisOption ? activeEditingCursorIndex : undefined,
 				);
 				const continuationPrefix = " ".repeat(prefixWidth);
 				addLine(`${cursorPrefix}${theme.fg(optionColor, `${markerText}${wrappedInlineLabelLines[0] ?? ""}`)}`);
@@ -363,7 +416,7 @@ export async function askQuestionsWithTabs(
 		};
 
 		const render = (width: number): string[] => {
-			if (cachedRenderedLines) return cachedRenderedLines;
+			if (cachedRenderedLines && cachedRenderedWidth === width) return cachedRenderedLines;
 
 			const renderedLines: string[] = [];
 			const addLine = (line: string) => renderedLines.push(truncateToWidth(line, width));
@@ -380,10 +433,16 @@ export async function askQuestionsWithTabs(
 
 			addLine(theme.fg("accent", "─".repeat(width)));
 			cachedRenderedLines = renderedLines;
+			cachedRenderedWidth = width;
 			return renderedLines;
 		};
 
 		const handleInput = (data: string) => {
+			if (matchesKey(data, Key.ctrl("c"))) {
+				done(createTabsUiStateSnapshot(true, selectedOptionIndexesByQuestion, noteByQuestionByOption));
+				return;
+			}
+
 			if (isNoteEditorOpen) {
 				if (matchesKey(data, Key.tab) || matchesKey(data, Key.escape)) {
 					isNoteEditorOpen = false;
@@ -488,6 +547,7 @@ export async function askQuestionsWithTabs(
 			render,
 			invalidate: () => {
 				cachedRenderedLines = undefined;
+				cachedRenderedWidth = undefined;
 			},
 			handleInput,
 		};

package/src/ask-text-wrap.ts

@@ -0,0 +1,33 @@
+import { truncateToWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui";
+
+interface AppendWrappedTextOptions {
+	indent?: number;
+	formatLine?: (line: string) => string;
+}
+
+function normalizeMultilineText(text: string): string[] {
+	const normalized = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+	const lines = normalized.split("\n");
+	return lines.length > 0 ? lines : [""];
+}
+
+export function appendWrappedTextLines(
+	renderedLines: string[],
+	text: string,
+	width: number,
+	options: AppendWrappedTextOptions = {},
+): void {
+	const safeWidth = Number.isFinite(width) ? Math.max(1, Math.floor(width)) : 1;
+	const indent = Number.isFinite(options.indent) ? Math.max(0, Math.floor(options.indent ?? 0)) : 0;
+	const prefix = " ".repeat(indent);
+	const wrapWidth = Math.max(1, safeWidth - indent);
+	const formatLine = options.formatLine ?? ((line: string) => line);
+
+	for (const sourceLine of normalizeMultilineText(text)) {
+		const wrappedLines = wrapTextWithAnsi(sourceLine, wrapWidth);
+		const safeWrappedLines = wrappedLines.length > 0 ? wrappedLines : [""];
+		for (const wrappedLine of safeWrappedLines) {
+			renderedLines.push(truncateToWidth(`${prefix}${formatLine(wrappedLine)}`, safeWidth));
+		}
+	}
+}

package/src/index.ts

@@ -11,6 +11,12 @@ const OptionItemSchema = Type.Object({
 const QuestionItemSchema = Type.Object({
 	id: Type.String({ description: "Question id (e.g. auth, cache, priority)" }),
 	question: Type.String({ description: "Question text" }),
+	description: Type.Optional(
+		Type.String({
+			description:
+				"Optional context in Markdown/plain text. Rendered above options with wrapping (supports headings/lists/code blocks).",
+		}),
+	),
 	options: Type.Array(OptionItemSchema, {
 		description: "Available options. Do not include 'Other'.",
 		minItems: 1,
@@ -30,6 +36,7 @@ type AskParams = Static<typeof AskParamsSchema>;
 interface QuestionResult {
 	id: string;
 	question: string;
+	description?: string;
 	options: string[];
 	multi: boolean;
 	selectedOptions: string[];
@@ -39,6 +46,7 @@ interface QuestionResult {
 interface AskToolDetails {
 	id?: string;
 	question?: string;
+	description?: string;
 	options?: string[];
 	multi?: boolean;
 	selectedOptions?: string[];
@@ -54,6 +62,16 @@ function sanitizeForSessionText(value: string): string {
 		.trim();
 }
 
+function sanitizeMultilineForSessionText(value: string): string {
+	return value
+		.replace(/\r\n/g, "\n")
+		.replace(/\r/g, "\n")
+		.split("\n")
+		.map((line) => sanitizeForSessionText(line))
+		.join("\n")
+		.trim();
+}
+
 function sanitizeOptionForSessionText(option: string): string {
 	const sanitizedOption = sanitizeForSessionText(option);
 	return sanitizedOption.length > 0 ? sanitizedOption : "(empty option)";
@@ -64,12 +82,15 @@ function toSessionSafeQuestionResult(result: QuestionResult): QuestionResult {
 		.map((selectedOption) => sanitizeForSessionText(selectedOption))
 		.filter((selectedOption) => selectedOption.length > 0);
 
+	const rawDescription = result.description;
+	const description = rawDescription == null ? undefined : sanitizeMultilineForSessionText(rawDescription);
 	const rawCustomInput = result.customInput;
 	const customInput = rawCustomInput == null ? undefined : sanitizeForSessionText(rawCustomInput);
 
 	return {
 		id: sanitizeForSessionText(result.id) || "(unknown)",
 		question: sanitizeForSessionText(result.question) || "(empty question)",
+		description: description && description.length > 0 ? description : undefined,
 		options: result.options.map(sanitizeOptionForSessionText),
 		multi: result.multi,
 		selectedOptions,
@@ -108,13 +129,18 @@ function formatQuestionResult(result: QuestionResult): string {
 }
 
 function formatQuestionContext(result: QuestionResult, questionIndex: number): string {
-	const lines: string[] = [
-		`Question ${questionIndex + 1} (${result.id})`,
-		`Prompt: ${result.question}`,
-		"Options:",
-		...result.options.map((option, optionIndex) => `  ${optionIndex + 1}. ${option}`),
-		"Response:",
-	];
+	const lines: string[] = [`Question ${questionIndex + 1} (${result.id})`, `Prompt: ${result.question}`];
+
+	if (result.description) {
+		lines.push("Context:");
+		for (const descriptionLine of result.description.split("\n")) {
+			lines.push(`  ${descriptionLine}`);
+		}
+	}
+
+	lines.push("Options:");
+	lines.push(...result.options.map((option, optionIndex) => `  ${optionIndex + 1}. ${option}`));
+	lines.push("Response:");
 
 	const hasSelectedOptions = result.selectedOptions.length > 0;
 	const hasCustomInput = Boolean(result.customInput);
@@ -155,6 +181,7 @@ Ask the user for clarification when a choice materially affects the outcome.
 - Prefer 2-5 concise options.
 - Use multi=true when multiple answers are valid.
 - Use recommended=<index> (0-indexed) to mark the default option.
+- Use description to provide Markdown/plain context (supports long explanations and structure diagrams).
 - You can ask multiple related questions in one call using questions[].
 - Do NOT include an 'Other' option; UI adds it automatically.
 `.trim();
@@ -191,6 +218,7 @@ export default function askExtension(pi: ExtensionAPI) {
 				const result: QuestionResult = {
 					id: q.id,
 					question: q.question,
+					...(q.description && q.description.trim().length > 0 ? { description: q.description } : {}),
 					options: optionLabels,
 					multi: q.multi ?? false,
 					selectedOptions: selection.selectedOptions,
@@ -200,6 +228,7 @@ export default function askExtension(pi: ExtensionAPI) {
 				const details: AskToolDetails = {
 					id: q.id,
 					question: q.question,
+					...(q.description && q.description.trim().length > 0 ? { description: q.description } : {}),
 					options: optionLabels,
 					multi: q.multi ?? false,
 					selectedOptions: selection.selectedOptions,
@@ -221,6 +250,7 @@ export default function askExtension(pi: ExtensionAPI) {
 				results.push({
 					id: q.id,
 					question: q.question,
+					...(q.description && q.description.trim().length > 0 ? { description: q.description } : {}),
 					options: q.options.map((option) => option.label),
 					multi: q.multi ?? false,
 					selectedOptions: selection.selectedOptions,