@howaboua/pi-ask 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Warzocha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @howaboua/pi-ask
+
+Adds one agent-callable `ask` tool for human input. It handles free-text prompts, batched choices, review dispositions, and user-only handoffs without making the agent dump a report into chat first.
+
+## Install
+
+```bash
+pi install npm:@howaboua/pi-ask
+```
+
+Try it for one session:
+
+```bash
+pi -e npm:@howaboua/pi-ask
+```
+
+## How it behaves
+
+The agent can present several independently decidable prompts in one tabbed panel. Each prompt supports a short title, supporting evidence, one or more choices, free text, and an optional comment. Review findings become one prompt each, so you can fix, defer, or reject them without translating a wall of prose back into instructions.
+
+For work only you can complete—sign-in, authorization, hardware access, or another manual step—the agent can open a handoff and wait until you mark it done or unable to complete.
+
+`Other/rephrase` is always available. Submit it blank when the prompt needs to be rephrased, split, or followed up instead of answered as written.
+
+## Prompt commands
+
+- `/fold [report]` turns a long report or structured list into one interactive disposition prompt per item.
+- `/grill [idea]` investigates an idea, asks successive decisions, and keeps the agreed plan in `docs/`.
+
+Both templates are enabled by default. The extension creates `~/.pi/agent/ask.json` on first load:
+
+```json
+{
+  "grill": true,
+  "fold": true
+}
+```
+
+Set either value to `false`, then run `/reload`, to hide that template. The same configuration applies when pi-ask is installed through `@howaboua/pi-extensions` or `@howaboua/pi-stuff`.
+
+## TUI controls
+
+- `Up` / `Down` — move through choices, free text, and comments
+- `Enter` — choose or edit the focused item
+- `Left` / `Right` — move between prompts and the review tab
+- `Tab` — advance, using `Other/rephrase` when the current prompt is unanswered
+- `Esc` — dismiss the panel
+
+The tool requires Pi's interactive TUI or RPC UI. It returns dismissal as a distinct result so the agent can stop asking rather than guessing.

package/ask/config.ts

@@ -0,0 +1,43 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+interface AskConfig {
+	grill: boolean;
+	fold: boolean;
+}
+
+const DEFAULT_CONFIG: AskConfig = {
+	grill: true,
+	fold: true,
+};
+
+function askConfigPath(): string {
+	return join(getAgentDir(), "ask.json");
+}
+
+export function loadAskConfig(path = askConfigPath()): AskConfig {
+	if (!existsSync(path)) {
+		try {
+			mkdirSync(dirname(path), { recursive: true });
+			writeFileSync(
+				path,
+				`${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`,
+				"utf8",
+			);
+		} catch {
+			// A read-only agent directory must not disable default prompt resources.
+		}
+		return { ...DEFAULT_CONFIG };
+	}
+
+	try {
+		const raw = JSON.parse(readFileSync(path, "utf8")) as Partial<AskConfig>;
+		return {
+			grill: typeof raw.grill === "boolean" ? raw.grill : DEFAULT_CONFIG.grill,
+			fold: typeof raw.fold === "boolean" ? raw.fold : DEFAULT_CONFIG.fold,
+		};
+	} catch {
+		return { ...DEFAULT_CONFIG };
+	}
+}

package/ask/constants.ts

@@ -0,0 +1,7 @@
+export const OTHER_OPTION_LABEL = "Other/rephrase";
+export const REPHRASE_REQUEST_RESPONSE =
+	"User asked for rephrase, split, or follow-up.";
+export const HANDOFF_CHOICES = [
+	{ label: "Done" },
+	{ label: "Could not complete" },
+];

package/ask/contracts.ts

@@ -0,0 +1,48 @@
+import { type Static, Type } from "typebox";
+
+export { OTHER_OPTION_LABEL, REPHRASE_REQUEST_RESPONSE } from "./constants.js";
+
+export const ChoiceSchema = Type.Object({
+	label: Type.String({ description: "Short choice." }),
+	description: Type.Optional(Type.String({ description: "Optional detail." })),
+});
+
+export const PromptSchema = Type.Object({
+	title: Type.String({ description: "Short prompt." }),
+	body: Type.Optional(Type.String({ description: "Context or evidence." })),
+	multiple: Type.Optional(Type.Boolean({ description: "Allow multiple." })),
+	choices: Type.Optional(
+		Type.Array(ChoiceSchema, { description: "Choices; omit for free text." }),
+	),
+});
+
+export const AskParameters = Type.Object({
+	handoff: Type.Optional(
+		Type.Boolean({ description: "Wait for user action." }),
+	),
+	prompts: Type.Array(PromptSchema, { description: "Prompts." }),
+});
+
+export type AskInput = Static<typeof AskParameters>;
+export type PromptChoice = Static<typeof ChoiceSchema>;
+
+export interface AskPrompt {
+	id: string;
+	title: string;
+	body?: string;
+	multiple: boolean;
+	choices: PromptChoice[];
+}
+
+export interface AskResponse {
+	id: string;
+	selections: string[];
+	comment?: string;
+}
+
+export interface PromptState {
+	selections: string[];
+	customText: string;
+	customEnabled: boolean;
+	comment: string;
+}

package/ask/normalize.ts

@@ -0,0 +1,107 @@
+import { HANDOFF_CHOICES, OTHER_OPTION_LABEL } from "./constants.js";
+import type {
+	AskInput,
+	AskPrompt,
+	AskResponse,
+	PromptChoice,
+} from "./contracts.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+export function textContent(text: string): { type: "text"; text: string } {
+	return { type: "text", text };
+}
+
+export function normalizePromptChoice(choice: unknown): PromptChoice | null {
+	if (!isRecord(choice)) return null;
+	const label =
+		typeof choice["label"] === "string" ? choice["label"].trim() : "";
+	if (!label || label === OTHER_OPTION_LABEL) return null;
+	const description =
+		typeof choice["description"] === "string"
+			? choice["description"].trim()
+			: "";
+	return { label, ...(description ? { description } : {}) };
+}
+
+export function normalizePrompt(
+	input: unknown,
+	index: number,
+	handoff = false,
+): AskPrompt | null {
+	if (!isRecord(input)) return null;
+	const title = typeof input["title"] === "string" ? input["title"].trim() : "";
+	if (!title) return null;
+	const body = typeof input["body"] === "string" ? input["body"].trim() : "";
+	const choices = Array.isArray(input["choices"])
+		? input["choices"]
+				.map(normalizePromptChoice)
+				.filter((choice) => choice !== null)
+		: [];
+	return {
+		id: `p${index + 1}`,
+		title,
+		...(body ? { body } : {}),
+		multiple: input["multiple"] === true,
+		choices: handoff && choices.length === 0 ? [...HANDOFF_CHOICES] : choices,
+	};
+}
+
+export function normalizeAskInput(params: AskInput | null | undefined): {
+	handoff: boolean;
+	prompts: AskPrompt[];
+} {
+	const handoff = params?.handoff === true;
+	const prompts = Array.isArray(params?.prompts)
+		? params.prompts
+				.map((prompt, index) => normalizePrompt(prompt, index, handoff))
+				.filter((prompt) => prompt !== null)
+		: [];
+	return { handoff, prompts };
+}
+
+export function normalizeResponses(
+	prompts: AskPrompt[],
+	responses: unknown,
+): AskResponse[] | null {
+	if (!Array.isArray(responses)) return null;
+	return prompts.map((prompt, index) => {
+		const response: unknown = responses[index];
+		const rawSelections = Array.isArray(response)
+			? response
+			: isRecord(response) && Array.isArray(response["selections"])
+				? response["selections"]
+				: [];
+		const selections = rawSelections.filter(
+			(selection): selection is string => {
+				return typeof selection === "string";
+			},
+		);
+		const comment =
+			isRecord(response) && typeof response["comment"] === "string"
+				? response["comment"].trim()
+				: "";
+		return {
+			id: prompt.id,
+			selections,
+			...(comment ? { comment } : {}),
+		};
+	});
+}
+
+export function summarizeResponses(
+	prompts: AskPrompt[],
+	responses: AskResponse[],
+): string {
+	return responses
+		.map((response, index) => {
+			const prompt = prompts[index];
+			const selection = `${prompt?.title ?? `Prompt ${index + 1}`}: ${response.selections.join(", ") || "No selection"}`;
+			return response.comment
+				? `${selection}\n  Comment: ${response.comment}`
+				: selection;
+		})
+		.join("\n");
+}

package/ask/pi-ui.ts

@@ -0,0 +1,133 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { OTHER_OPTION_LABEL } from "./constants.js";
+import type { AskPrompt, AskResponse } from "./contracts.js";
+import { customSelectionFor } from "./state.js";
+
+function dialogOptions(
+	signal?: AbortSignal,
+): { signal: AbortSignal } | undefined {
+	return signal ? { signal } : undefined;
+}
+
+async function askOther(
+	ctx: ExtensionContext,
+	prompt: AskPrompt,
+	signal?: AbortSignal,
+): Promise<string | null> {
+	const value = await ctx.ui.input(
+		prompt.title,
+		"Alternative; blank = rephrase",
+		dialogOptions(signal),
+	);
+	return value === undefined ? null : customSelectionFor(value);
+}
+
+function promptText(prompt: AskPrompt, handoff: boolean): string {
+	const text = prompt.body ? `${prompt.title}\n\n${prompt.body}` : prompt.title;
+	return handoff ? `Human action needed\n\n${text}` : text;
+}
+
+async function askComment(
+	ctx: ExtensionContext,
+	prompt: AskPrompt,
+	signal?: AbortSignal,
+): Promise<string | null> {
+	const value = await ctx.ui.input(
+		`${prompt.title} — comment`,
+		"Optional comment",
+		dialogOptions(signal),
+	);
+	return value === undefined ? null : value.trim();
+}
+
+function finishSelectionLabelFor(choices: string[]): string {
+	const base = "Finish selection";
+	const unavailable = new Set([...choices, OTHER_OPTION_LABEL]);
+	let label = base;
+	let suffix = 2;
+	while (unavailable.has(label)) {
+		label = `${base} (${suffix})`;
+		suffix++;
+	}
+	return label;
+}
+
+async function askSingleWithPiUi(
+	ctx: ExtensionContext,
+	prompt: AskPrompt,
+	handoff: boolean,
+	signal?: AbortSignal,
+): Promise<string[] | null> {
+	const choices = prompt.choices.map((choice) => choice.label);
+	const picked =
+		choices.length > 0
+			? await ctx.ui.select(
+					promptText(prompt, handoff),
+					[...choices, OTHER_OPTION_LABEL],
+					dialogOptions(signal),
+				)
+			: await ctx.ui.input(
+					promptText(prompt, handoff),
+					"Response",
+					dialogOptions(signal),
+				);
+	if (picked === undefined) return null;
+	if (choices.length === 0) return [customSelectionFor(picked)];
+	if (picked !== OTHER_OPTION_LABEL) return [picked];
+	const other = await askOther(ctx, prompt, signal);
+	return other === null ? null : [other];
+}
+
+async function askMultipleWithPiUi(
+	ctx: ExtensionContext,
+	prompt: AskPrompt,
+	handoff: boolean,
+	signal?: AbortSignal,
+): Promise<string[] | null> {
+	const choices = prompt.choices.map((choice) => choice.label);
+	const finishSelectionLabel = finishSelectionLabelFor(choices);
+	const picked: string[] = [];
+	while (true) {
+		const next = await ctx.ui.select(
+			promptText(prompt, handoff),
+			[
+				...choices.filter((choice) => !picked.includes(choice)),
+				OTHER_OPTION_LABEL,
+				finishSelectionLabel,
+			],
+			dialogOptions(signal),
+		);
+		if (next === undefined) return null;
+		if (next === finishSelectionLabel) return picked;
+		if (next === OTHER_OPTION_LABEL) {
+			const other = await askOther(ctx, prompt, signal);
+			if (other === null) return null;
+			picked.push(other);
+		} else {
+			picked.push(next);
+		}
+	}
+}
+
+export async function askWithPiUi(
+	ctx: ExtensionContext,
+	prompts: AskPrompt[],
+	{ handoff = false, signal }: { handoff?: boolean; signal?: AbortSignal } = {},
+): Promise<AskResponse[] | null> {
+	if (!ctx.hasUI || signal?.aborted) return null;
+	const responses: AskResponse[] = [];
+	for (const prompt of prompts) {
+		const selections = prompt.multiple
+			? await askMultipleWithPiUi(ctx, prompt, handoff, signal)
+			: await askSingleWithPiUi(ctx, prompt, handoff, signal);
+		if (!selections) return null;
+		const comment = await askComment(ctx, prompt, signal);
+		if (comment === null || signal?.aborted) return null;
+		responses.push({
+			id: prompt.id,
+			selections,
+			...(comment ? { comment } : {}),
+		});
+	}
+	return responses;
+}

package/ask/state.ts

@@ -0,0 +1,100 @@
+import { REPHRASE_REQUEST_RESPONSE } from "./constants.js";
+import type {
+	AskPrompt,
+	AskResponse,
+	PromptChoice,
+	PromptState,
+} from "./contracts.js";
+
+export function customSelectionFor(value: unknown): string {
+	const trimmed = typeof value === "string" ? value.trim() : "";
+	return trimmed || REPHRASE_REQUEST_RESPONSE;
+}
+
+export function createPromptState(): PromptState {
+	return { selections: [], customText: "", customEnabled: false, comment: "" };
+}
+
+export function promptStateResponded(
+	promptState: PromptState | undefined,
+): boolean {
+	return (
+		(promptState?.selections.length ?? 0) > 0 ||
+		promptState?.customEnabled === true ||
+		Boolean(promptState?.comment.trim())
+	);
+}
+
+export function promptStatesToResponses(
+	prompts: Array<Pick<AskPrompt, "id">>,
+	promptStates: PromptState[],
+): AskResponse[] {
+	return promptStates.map((promptState, index) => {
+		const comment = promptState.comment.trim();
+		return {
+			id: prompts[index]?.id ?? `p${index + 1}`,
+			selections: promptState.selections,
+			...(comment ? { comment } : {}),
+		};
+	});
+}
+
+export function saveComment(
+	promptState: PromptState,
+	submittedText: unknown,
+): void {
+	promptState.comment = typeof submittedText === "string" ? submittedText : "";
+}
+
+export function saveCustomSelection(
+	prompt: Pick<AskPrompt, "multiple"> | undefined,
+	promptState: PromptState,
+	submittedText: unknown,
+): void {
+	const previous = promptState.customEnabled
+		? customSelectionFor(promptState.customText)
+		: null;
+	const value = typeof submittedText === "string" ? submittedText : "";
+	const next = customSelectionFor(value);
+
+	promptState.customText = value;
+	promptState.customEnabled = true;
+
+	if (prompt?.multiple) {
+		promptState.selections = [
+			...promptState.selections.filter(
+				(item) => item !== next && item !== previous,
+			),
+			next,
+		];
+	} else {
+		promptState.selections = [next];
+	}
+}
+
+export function clearCustomSelection(promptState: PromptState): void {
+	if (!promptState.customEnabled) return;
+	const customSelection = customSelectionFor(promptState.customText);
+	promptState.selections = promptState.selections.filter(
+		(item) => item !== customSelection,
+	);
+	promptState.customText = "";
+	promptState.customEnabled = false;
+}
+
+export function pickChoiceSelection(
+	prompt: Pick<AskPrompt, "multiple"> | undefined,
+	promptState: PromptState,
+	choice: PromptChoice | undefined,
+): void {
+	if (!choice) return;
+	if (prompt?.multiple) {
+		promptState.selections = promptState.selections.includes(choice.label)
+			? promptState.selections.filter((item) => item !== choice.label)
+			: [...promptState.selections, choice.label];
+		return;
+	}
+
+	promptState.selections = [choice.label];
+	promptState.customEnabled = false;
+}

package/ask/tool.ts

@@ -0,0 +1,90 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { AskParameters, type AskPrompt } from "./contracts.js";
+import {
+	normalizeAskInput,
+	normalizeResponses,
+	summarizeResponses,
+	textContent,
+} from "./normalize.js";
+import { askWithPiUi } from "./pi-ui.js";
+import { askInTui } from "./tui.js";
+
+type AskInComposer = (
+	prompts: AskPrompt[],
+	signal: AbortSignal | undefined,
+) => Promise<unknown>;
+
+export function createAskTool({
+	askInComposer,
+}: {
+	askInComposer?: AskInComposer;
+} = {}) {
+	return defineTool({
+		name: "ask",
+		label: "Ask",
+		description:
+			"Request user input or action and return the response. Requires interactive UI.",
+		parameters: AskParameters,
+		promptSnippet: "ask: Request human input or action.",
+		promptGuidelines: [
+			"ask: Use for needed user decisions or input; set handoff true for a user-only action and state its completion signal.",
+			"ask: For reviews, make each finding a prompt with disposition choices; do not report first.",
+			"ask: Do not add Other/rephrase; it is automatic.",
+		],
+		executionMode: "sequential",
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const { handoff, prompts } = normalizeAskInput(params);
+			if (prompts.length === 0) {
+				throw new Error(
+					"ask requires at least one prompt with a non-empty title.",
+				);
+			}
+			if (!askInComposer && !ctx.hasUI)
+				throw new Error("ask requires an interactive UI.");
+
+			const rawResponses = askInComposer
+				? await askInComposer(prompts, signal)
+				: ctx.mode === "tui"
+					? await askInTui(ctx, prompts, {
+							handoff,
+							...(signal ? { signal } : {}),
+						})
+					: await askWithPiUi(ctx, prompts, {
+							handoff,
+							...(signal ? { signal } : {}),
+						});
+			const responses = normalizeResponses(prompts, rawResponses);
+			if (!responses) {
+				return {
+					content: [
+						textContent(
+							handoff ? "Handoff dismissed by user." : "Dismissed by user.",
+						),
+					],
+					details: { dismissed: true, kind: handoff ? "handoff" : "prompt" },
+				};
+			}
+			return {
+				content: [textContent(summarizeResponses(prompts, responses))],
+				details: { kind: handoff ? "handoff" : "prompt", responses },
+			};
+		},
+		renderCall(args, theme) {
+			const count = Array.isArray(args.prompts) ? args.prompts.length : 0;
+			return new Text(
+				theme.fg(
+					"toolTitle",
+					theme.bold(args.handoff === true ? "ask handoff " : "ask "),
+				) + theme.fg("muted", `${count} prompt${count === 1 ? "" : "s"}`),
+				0,
+				0,
+			);
+		},
+		renderResult(result, _options, theme) {
+			const text =
+				result.content[0]?.type === "text" ? result.content[0].text : "";
+			return new Text(theme.fg("success", text), 0, 0);
+		},
+	});
+}

package/ask/tui.ts

@@ -0,0 +1,542 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	Editor,
+	Key,
+	matchesKey,
+	truncateToWidth,
+	wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+import { OTHER_OPTION_LABEL } from "./constants.js";
+import type {
+	AskPrompt,
+	AskResponse,
+	PromptChoice,
+	PromptState,
+} from "./contracts.js";
+import {
+	clearCustomSelection,
+	createPromptState,
+	pickChoiceSelection,
+	promptStateResponded,
+	promptStatesToResponses,
+	saveComment,
+	saveCustomSelection,
+} from "./state.js";
+
+type AskTheme = ExtensionContext["ui"]["theme"];
+type AddLine = (line?: string) => void;
+type EditingKind = "other" | "comment";
+
+interface AskUiState {
+	tab: number;
+	focus: number;
+	editing: EditingKind | null;
+}
+
+interface RenderTabsOptions {
+	handoff: boolean;
+	prompts: AskPrompt[];
+	responded: (index: number) => boolean;
+	tab: number;
+	theme: AskTheme;
+}
+
+interface RenderReviewOptions {
+	add: AddLine;
+	handoff: boolean;
+	promptStates: PromptState[];
+	prompts: AskPrompt[];
+	theme: AskTheme;
+	width: number;
+}
+
+interface RenderChoiceOptions {
+	add: AddLine;
+	checked: boolean | undefined;
+	choice: PromptChoice;
+	selected: boolean;
+	theme: AskTheme;
+	width: number;
+}
+
+interface RenderPromptOptions {
+	add: AddLine;
+	editor: Editor;
+	handoff: boolean;
+	isEditing: EditingKind | null;
+	choices: PromptChoice[];
+	prompt: AskPrompt;
+	promptState: PromptState | undefined;
+	state: AskUiState;
+	theme: AskTheme;
+	width: number;
+}
+
+function addWrapped(
+	add: AddLine,
+	text: string,
+	width: number,
+	indent = "",
+): void {
+	for (const line of wrapTextWithAnsi(
+		text,
+		Math.max(1, width - indent.length),
+	)) {
+		add(`${indent}${line}`);
+	}
+}
+
+function renderAskTabs({
+	handoff,
+	prompts,
+	responded,
+	tab,
+	theme,
+}: RenderTabsOptions): string {
+	return ` ${Array.from({ length: prompts.length + 1 }, (_, index) => {
+		const active = index === tab;
+		const label =
+			index === prompts.length
+				? handoff
+					? "Resume"
+					: "Review"
+				: `${responded(index) ? "■" : "□"} ${index + 1}`;
+		return active
+			? theme.bg("selectedBg", theme.fg("text", ` ${label} `))
+			: theme.fg("muted", ` ${label} `);
+	}).join(" ")}`;
+}
+
+function renderAskReview({
+	add,
+	handoff,
+	promptStates,
+	prompts,
+	theme,
+	width,
+}: RenderReviewOptions): void {
+	add(
+		theme.fg(
+			handoff ? "warning" : "accent",
+			handoff ? " Resume agent" : " Review",
+		),
+	);
+	add();
+	prompts.forEach((prompt, index) => {
+		const promptState = promptStates[index];
+		const selections = promptState?.selections ?? [];
+		addWrapped(
+			add,
+			theme.fg("muted", `${index + 1}. ${prompt.title}`),
+			width,
+			" ",
+		);
+		addWrapped(
+			add,
+			theme.fg("text", selections.join(", ") || "No selection"),
+			width,
+			"    ",
+		);
+		if (promptState?.comment.trim()) {
+			addWrapped(
+				add,
+				theme.fg("muted", `Comment: ${promptState.comment.trim()}`),
+				width,
+				"    ",
+			);
+		}
+	});
+	add();
+	add(
+		theme.fg(
+			"dim",
+			handoff
+				? " Enter returns control • ←/→ prompts • Esc dismisses"
+				: " Enter submits • ←/→ prompts • Esc dismisses",
+		),
+	);
+}
+
+function renderAskChoice({
+	add,
+	checked,
+	choice,
+	selected,
+	theme,
+	width,
+}: RenderChoiceOptions): void {
+	add(
+		`${selected ? theme.fg("accent", "> ") : "  "}${checked ? theme.fg("success", "✓ ") : "  "}${theme.fg(selected ? "accent" : "text", choice.label)}`,
+	);
+	if (choice.description) {
+		addWrapped(add, theme.fg("muted", choice.description), width, "    ");
+	}
+}
+
+function renderAskPrompt({
+	add,
+	editor,
+	handoff,
+	isEditing,
+	choices,
+	prompt,
+	promptState,
+	state,
+	theme,
+	width,
+}: RenderPromptOptions): void {
+	if (handoff) {
+		add(theme.fg("warning", " Human action needed"));
+		add();
+	}
+	addWrapped(add, theme.fg("text", prompt.title), width, " ");
+	add(
+		theme.fg(
+			"muted",
+			` ${prompt.multiple ? "Choose any that apply" : "Choose one"}`,
+		),
+	);
+	if (prompt.body) {
+		add();
+		addWrapped(add, theme.fg("muted", prompt.body), width, "   ");
+	}
+	add();
+	choices.forEach((choice, index) => {
+		renderAskChoice({
+			add,
+			checked: promptState?.selections.includes(choice.label),
+			choice,
+			selected: state.focus === index,
+			theme,
+			width,
+		});
+	});
+	const selectedOther = state.focus === choices.length;
+	add(
+		`${selectedOther ? theme.fg("accent", "> ") : "  "}${promptState?.customEnabled ? theme.fg("success", "✓ ") : "  "}${theme.fg(selectedOther ? "accent" : "muted", OTHER_OPTION_LABEL)}${promptState?.customText.trim() ? theme.fg("text", `: ${promptState.customText.trim()}`) : ""}`,
+	);
+	if (isEditing === "other") {
+		add();
+		for (const line of editor.render(width - 2)) add(` ${line}`);
+	}
+	const selectedComment = state.focus === choices.length + 1;
+	add();
+	add(
+		`${selectedComment ? theme.fg("accent", "> ") : "  "}${theme.fg(selectedComment ? "accent" : "text", "Comment (optional)")}`,
+	);
+	if (promptState?.comment.trim()) {
+		addWrapped(
+			add,
+			theme.fg("muted", promptState.comment.trim()),
+			width,
+			"    ",
+		);
+	}
+	if (isEditing === "comment") {
+		add();
+		for (const line of editor.render(width - 2)) add(` ${line}`);
+	}
+	add();
+	add(
+		theme.fg(
+			"dim",
+			" ↑↓ select • Enter choose/type • Tab next/default • blank Other/rephrase = follow-up • Esc close",
+		),
+	);
+}
+
+interface EditingInputOptions {
+	advance: () => void;
+	editor: Editor;
+	refresh: () => void;
+	saveEditing: (submittedText?: string) => void;
+	state: AskUiState;
+}
+
+function handleAskEditingInput(
+	data: string,
+	{ advance, editor, refresh, saveEditing, state }: EditingInputOptions,
+): void {
+	if (matchesKey(data, Key.tab)) {
+		saveEditing(editor.getText());
+		state.editing = null;
+		advance();
+		return;
+	}
+	if (matchesKey(data, Key.escape)) {
+		state.editing = null;
+		refresh();
+		return;
+	}
+	editor.handleInput(data);
+	refresh();
+}
+
+interface PromptInputOptions {
+	advanceWithDefault: () => void;
+	choices: () => PromptChoice[];
+	count: () => number;
+	pick: (index: number) => void;
+	refresh: () => void;
+	selectOther: () => void;
+	startEditingComment: () => void;
+	state: AskUiState;
+}
+
+function handleAskPromptInput(
+	data: string,
+	{
+		advanceWithDefault,
+		choices,
+		count,
+		pick,
+		refresh,
+		selectOther,
+		startEditingComment,
+		state,
+	}: PromptInputOptions,
+): void {
+	if (matchesKey(data, Key.up)) {
+		state.focus = Math.max(0, state.focus - 1);
+		refresh();
+		return;
+	}
+	if (matchesKey(data, Key.down)) {
+		state.focus = Math.min(count() - 1, state.focus + 1);
+		refresh();
+		return;
+	}
+	if (matchesKey(data, Key.tab)) {
+		advanceWithDefault();
+		return;
+	}
+	if (!matchesKey(data, Key.enter)) return;
+	if (state.focus === choices().length) {
+		selectOther();
+		return;
+	}
+	if (state.focus === choices().length + 1) {
+		startEditingComment();
+		return;
+	}
+	pick(state.focus);
+}
+
+interface NavigationInputOptions {
+	done: (responses: AskResponse[] | null) => void;
+	isReview: () => boolean;
+	promptStates: PromptState[];
+	prompts: AskPrompt[];
+	setTab: (next: number) => void;
+	state: AskUiState;
+}
+
+function handleAskNavigationInput(
+	data: string,
+	{
+		done,
+		isReview,
+		promptStates,
+		prompts,
+		setTab,
+		state,
+	}: NavigationInputOptions,
+): boolean {
+	if (matchesKey(data, Key.escape)) {
+		done(null);
+		return true;
+	}
+	if (matchesKey(data, Key.left)) {
+		setTab(state.tab - 1);
+		return true;
+	}
+	if (matchesKey(data, Key.right)) {
+		setTab(state.tab + 1);
+		return true;
+	}
+	if (!isReview()) return false;
+	if (matchesKey(data, Key.enter)) {
+		done(promptStatesToResponses(prompts, promptStates));
+	}
+	return true;
+}
+
+export async function askInTui(
+	ctx: ExtensionContext,
+	prompts: AskPrompt[],
+	{ handoff = false, signal }: { handoff?: boolean; signal?: AbortSignal } = {},
+): Promise<AskResponse[] | null> {
+	if (!ctx.hasUI || signal?.aborted) return null;
+	return await ctx.ui.custom<AskResponse[] | null>((tui, theme, _kb, done) => {
+		let settled = false;
+		const finish = (result: AskResponse[] | null) => {
+			if (settled) return;
+			settled = true;
+			signal?.removeEventListener("abort", abort);
+			done(result);
+		};
+		const abort = () => finish(null);
+		signal?.addEventListener("abort", abort, { once: true });
+		if (signal?.aborted) queueMicrotask(abort);
+		const state: AskUiState = { tab: 0, focus: 0, editing: null };
+		let cached: string[] | undefined;
+		// Keep response lifecycle in one object per prompt. Parallel arrays made tab/default
+		// transitions easy to desynchronise as this tool grows.
+		const promptStates = prompts.map(createPromptState);
+		const editor = new Editor(tui, {
+			borderColor: (text) => theme.fg(handoff ? "warning" : "accent", text),
+			selectList: {
+				selectedPrefix: (text) => theme.fg("accent", text),
+				selectedText: (text) => theme.fg("accent", text),
+				description: (text) => theme.fg("muted", text),
+				scrollInfo: (text) => theme.fg("dim", text),
+				noMatch: (text) => theme.fg("warning", text),
+			},
+		});
+
+		const reviewTab = () => prompts.length;
+		const current = () => prompts[state.tab];
+		const currentPromptState = () => promptStates[state.tab];
+		const choices = () => current()?.choices ?? [];
+		const isReview = () => state.tab === reviewTab();
+		const count = () => choices().length + 2;
+		const refresh = () => {
+			cached = undefined;
+			tui.requestRender();
+		};
+		const responded = (index: number) =>
+			promptStateResponded(promptStates[index]);
+		const setTab = (next: number) => {
+			state.tab = Math.max(0, Math.min(reviewTab(), next));
+			state.focus = 0;
+			state.editing = null;
+			editor.setText(promptStates[state.tab]?.customText ?? "");
+			refresh();
+		};
+		const saveCustom = (submittedText = editor.getText()) => {
+			const prompt = current();
+			const promptState = currentPromptState();
+			if (!prompt || !promptState) return;
+			saveCustomSelection(prompt, promptState, submittedText);
+		};
+		const saveEditing = (submittedText = editor.getText()) => {
+			const promptState = currentPromptState();
+			if (!promptState) return;
+			if (state.editing === "comment") saveComment(promptState, submittedText);
+			else saveCustom(submittedText);
+		};
+		const startEditing = (kind: EditingKind) => {
+			const promptState = currentPromptState();
+			if (!promptState) return;
+			state.editing = kind;
+			editor.setText(
+				kind === "comment" ? promptState.comment : promptState.customText,
+			);
+			refresh();
+		};
+		const selectOther = () => {
+			const prompt = current();
+			const promptState = currentPromptState();
+			if (!prompt || !promptState) return;
+			if (prompt.multiple && promptState.customEnabled) {
+				clearCustomSelection(promptState);
+				refresh();
+				return;
+			}
+			startEditing("other");
+		};
+		const advance = () => setTab(state.tab + 1);
+		const advanceWithDefault = () => {
+			if (!isReview() && !responded(state.tab)) saveCustom("");
+			advance();
+		};
+		editor.onSubmit = (value) => {
+			saveEditing(value);
+			state.editing = null;
+			refresh();
+		};
+		const pick = (index: number) => {
+			const choice = choices()[index];
+			const prompt = current();
+			const promptState = currentPromptState();
+			if (!choice || !promptState) return;
+			pickChoiceSelection(prompt, promptState, choice);
+			refresh();
+		};
+		const handleInput = (data: string) => {
+			if (state.editing) {
+				handleAskEditingInput(data, {
+					advance,
+					editor,
+					refresh,
+					saveEditing,
+					state,
+				});
+				return;
+			}
+			if (
+				handleAskNavigationInput(data, {
+					done: finish,
+					isReview,
+					promptStates,
+					prompts,
+					setTab,
+					state,
+				})
+			) {
+				return;
+			}
+			handleAskPromptInput(data, {
+				advanceWithDefault,
+				count,
+				choices,
+				pick,
+				refresh,
+				selectOther,
+				startEditingComment: () => startEditing("comment"),
+				state,
+			});
+		};
+		const render = (width: number) => {
+			if (cached) return cached;
+			const lines: string[] = [];
+			const add: AddLine = (line = "") =>
+				lines.push(truncateToWidth(line, width));
+			add(theme.fg(handoff ? "warning" : "accent", "─".repeat(width)));
+			add(
+				renderAskTabs({ handoff, prompts, responded, tab: state.tab, theme }),
+			);
+			add();
+			if (isReview()) {
+				renderAskReview({ add, handoff, promptStates, prompts, theme, width });
+			} else {
+				const prompt = current();
+				if (prompt) {
+					renderAskPrompt({
+						add,
+						editor,
+						handoff,
+						isEditing: state.editing,
+						choices: choices(),
+						prompt,
+						promptState: currentPromptState(),
+						state,
+						theme,
+						width,
+					});
+				}
+			}
+			add(theme.fg(handoff ? "warning" : "accent", "─".repeat(width)));
+			cached = lines;
+			return lines;
+		};
+		return {
+			render,
+			handleInput,
+			dispose: () => signal?.removeEventListener("abort", abort),
+			invalidate: () => {
+				cached = undefined;
+			},
+		};
+	});
+}

package/biome.json

@@ -0,0 +1,31 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.4.16/schema.json",
+	"vcs": {
+		"enabled": true,
+		"clientKind": "git",
+		"useIgnoreFile": true
+	},
+	"files": {
+		"includes": [
+			"**",
+			"!node_modules",
+			"!dist",
+			"!coverage",
+			"!package-lock.json"
+		]
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab"
+	},
+	"linter": {
+		"enabled": false
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "double",
+			"semicolons": "always",
+			"trailingCommas": "all"
+		}
+	}
+}

package/index.ts

@@ -0,0 +1,22 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadAskConfig } from "./ask/config.js";
+import { createAskTool } from "./ask/tool.js";
+
+export { createAskTool } from "./ask/tool.js";
+
+const PROMPTS_DIR = join(dirname(fileURLToPath(import.meta.url)), "prompts");
+
+export default function humanInTheLoop(pi: ExtensionAPI): void {
+	pi.registerTool(createAskTool());
+	pi.on("resources_discover", () => {
+		const config = loadAskConfig();
+		return {
+			promptPaths: [
+				...(config.grill ? [join(PROMPTS_DIR, "grill.md")] : []),
+				...(config.fold ? [join(PROMPTS_DIR, "fold.md")] : []),
+			],
+		};
+	});
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+	"name": "@howaboua/pi-ask",
+	"version": "0.0.1",
+	"description": "Interactive decisions, review triage, and human handoffs for Pi.",
+	"type": "module",
+	"license": "MIT",
+	"author": "Igor Warzocha",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/IgorWarzocha/howaboua-pi-stuff.git",
+		"directory": "packages/pi-ask"
+	},
+	"homepage": "https://github.com/IgorWarzocha/howaboua-pi-stuff/tree/main/packages/pi-ask#readme",
+	"bugs": {
+		"url": "https://github.com/IgorWarzocha/howaboua-pi-stuff/issues"
+	},
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"pi-coding-agent",
+		"human-in-the-loop",
+		"review",
+		"handoff"
+	],
+	"engines": {
+		"node": ">=20.6.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"index.ts",
+		"ask",
+		"prompts",
+		"README.md",
+		"LICENSE",
+		"tsconfig.json",
+		"biome.json"
+	],
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": ">=0.80.7",
+		"@earendil-works/pi-tui": ">=0.80.7",
+		"typebox": "*"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.4.16",
+		"@earendil-works/pi-coding-agent": "0.80.7",
+		"@earendil-works/pi-tui": "0.80.7",
+		"typebox": "1.1.38",
+		"typescript": "^6.0.3"
+	},
+	"scripts": {
+		"check": "bun run lint && bun run typecheck && bun run test",
+		"prepack": "bun run check",
+		"test": "bun test",
+		"typecheck": "tsgo --noEmit",
+		"lint": "biome check .",
+		"format": "biome check --write .",
+		"pack:dry": "npm pack --dry-run"
+	},
+	"main": "index.ts",
+	"exports": "./index.ts"
+}

package/prompts/fold.md

@@ -0,0 +1,17 @@
+---
+description: Fold a long report or list into interactive review
+argument-hint: "[report or instructions]"
+---
+Fold this material into `ask` instead of replying with another long report:
+
+$ARGUMENTS
+
+If no material follows the command, use the most recent lengthy report or structured list in the conversation.
+
+Call `ask` once with one prompt per independently decidable item:
+- Keep the title short.
+- Preserve concrete evidence, consequences, and recommendations in the body.
+- Use the source's natural choices. For review findings, default to Fix, Defer, and Reject.
+- Keep coupled points together; do not manufacture decisions from explanatory bullets.
+
+Do not repeat the report before or after the tool call. Once the responses return, summarize the dispositions briefly and continue only when the surrounding task already authorizes action.

package/prompts/grill.md

@@ -0,0 +1,33 @@
+---
+description: Grill an idea into an agreed plan
+argument-hint: "[idea or plan]"
+---
+Grill this into an agreed plan:
+
+$ARGUMENTS
+
+Use the working directory, web search, available skills, and any relevant tools to understand the thing before asking. Prefer finding answers yourself over asking me.
+
+Loop until ask is dismissed. There is no round limit:
+1. Investigate the relevant context.
+2. Use ask for the next set of decisions.
+3. After the first answer round, create docs/<short-name>.md.
+4. Keep asking better questions, using tools between rounds as needed.
+5. Keep updating the markdown file after each round.
+
+The markdown file is the current plan, not a transcript. Keep it ready to use if I stop at any point. Include:
+- goal
+- agreed decisions
+- important tradeoffs
+- relevant user reasoning
+- open questions
+- proposed next steps
+
+Do not log every question and answer.
+
+When ask is dismissed, the grilling session is done. Then:
+- give a short summary of what was agreed
+- open the markdown file with $EDITOR if available
+- print the file path
+
+Do not start implementation unless I explicitly choose to proceed.

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+	"extends": "../../tsconfig.base.json",
+	"include": ["index.ts", "ask/**/*.ts"]
+}