@howaboua/pi-ask 0.0.11 → 0.0.13

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @howaboua/pi-ask
 
+## 0.0.13
+
+- Ask now accepts supervisor replies through Shepherdr's `reply` action. Update and reload Ask and Shepherdr together on controllers and workers.
+
+  - Supervisors receive questions, choices and a reply template. Valid replies complete the worker's existing wait or steer panel. Human handoffs still require the user's confirmation.
+  - Unknown or misnamed fields, such as `options` instead of `choices`, and malformed choices now return errors naming the invalid field and accepted shape instead of silently dropping input.
+
+## 0.0.12
+
+- ### Improvements
+  - Ask returns help when called without arguments, including an empty structured object. Explicit help remains supported.
+
 ## 0.0.11
 
 - Parents can receive and answer asynchronous questions through Shepherdr while workers continue.

package/README.md

@@ -26,6 +26,8 @@ For work only you can complete—sign-in, authorization, hardware access, or ano
 
 When Pi runs inside Herdr with its Pi integration installed, only a waiting ask marks the pane as blocked. A steering ask remains pending while the agent continues.
 
+With Shepherdr, supervising agents receive the question, choices and a ready-to-fill reply. Replying completes the same panel. Ordinary agent messages do not answer it, and pending questions remain visible in later reports. Human handoffs still require your action and confirmation.
+
 `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

package/ask/contracts.ts

@@ -16,8 +16,9 @@ const PromptSchema = Type.Object({
 });
 
 export const AskParameters = Type.Object({
+	help: Type.Optional(Type.Literal(true)),
 	handoff: Type.Optional(Type.Boolean()),
-	prompts: Type.Array(PromptSchema),
+	prompts: Type.Optional(Type.Array(PromptSchema)),
 	delivery: Type.Optional(StringEnum(ASK_DELIVERIES)),
 });
 

package/ask/coordinator.ts

@@ -3,6 +3,7 @@ import type { AskPrompt, AskResponse, PendingAsk } from "./contracts.js";
 import { normalizeResponses, summarizeResponses } from "./normalize.js";
 import type { PendingAskUpdate } from "./pending.js";
 import { askWithPiUi } from "./pi-ui.js";
+import { AskRequests, type RequestChange } from "./requests.js";
 import { askInTui } from "./tui.js";
 
 type AskInComposer = (
@@ -14,10 +15,11 @@ export interface AskCoordinatorOptions {
 	askInComposer?: AskInComposer;
 	deliverSteer?: (message: string) => void;
 	onPendingChange?: (update: PendingAskUpdate) => void;
-	onSteerActiveChange?: (request: PendingAsk, active: boolean) => void;
+	onRequestChange?: (change: RequestChange) => void;
 }
 
 interface PresentAskOptions {
+	id: string;
 	onActiveChange?: (active: boolean) => void;
 	handoff?: boolean;
 	steering?: boolean;
@@ -35,41 +37,46 @@ export function createAskCoordinator({
 	askInComposer,
 	deliverSteer,
 	onPendingChange,
-	onSteerActiveChange,
+	onRequestChange,
 }: AskCoordinatorOptions = {}) {
+	const requests = new AskRequests(onRequestChange);
 	let generation = 0;
 	let sessionAbort = new AbortController();
 	let presentationTail = Promise.resolve();
 	const activeSteers = new Set<string>();
-	let presentedSteer: PendingAsk | undefined;
 
 	const present = (
 		ctx: ExtensionContext,
 		prompts: AskPrompt[],
 		{
+			id,
 			handoff = false,
 			steering = false,
 			signal,
 			onActiveChange,
-		}: PresentAskOptions = {},
+		}: PresentAskOptions,
 	): Promise<unknown> => {
+		const request = requests.open({ id, prompts, handoff, steering }, signal);
 		const run = async () => {
-			if (signal?.aborted) return null;
+			if (request.signal.aborted) return;
 			try {
 				onActiveChange?.(true);
-				return askInComposer
-					? await askInComposer(prompts, signal)
+				const response = askInComposer
+					? await askInComposer(prompts, request.signal)
 					: ctx.mode === "tui"
 						? await askInTui(ctx, prompts, {
 								handoff,
 								steering,
-								...(signal ? { signal } : {}),
+								signal: request.signal,
 							})
 						: await askWithPiUi(ctx, prompts, {
 								handoff,
 								steering,
-								...(signal ? { signal } : {}),
+								signal: request.signal,
 							});
+				request.select(response);
+			} catch (error) {
+				request.fail(error);
 			} finally {
 				onActiveChange?.(false);
 			}
@@ -79,7 +86,7 @@ export function createAskCoordinator({
 			() => undefined,
 			() => undefined,
 		);
-		return result;
+		return request.response;
 	};
 
 	const notifyFailure = (ctx: ExtensionContext, error: unknown) => {
@@ -102,7 +109,7 @@ export function createAskCoordinator({
 		ctx: ExtensionContext,
 		id: string,
 		responses?: AskResponse[],
-	) => {
+	): boolean => {
 		activeSteers.delete(id);
 		try {
 			onPendingChange?.({
@@ -111,8 +118,10 @@ export function createAskCoordinator({
 				id,
 				...(responses ? { responses } : { dismissed: true }),
 			});
+			return true;
 		} catch (error) {
 			notifyFailure(ctx, error);
+			return false;
 		}
 	};
 
@@ -133,49 +142,74 @@ export function createAskCoordinator({
 		activeSteers.add(request.id);
 		const requestGeneration = generation;
 		void present(ctx, request.prompts, {
+			id: request.id,
 			steering: true,
 			signal: sessionAbort.signal,
-			onActiveChange: (active) => {
-				if (requestGeneration === generation && !sessionAbort.signal.aborted) {
-					presentedSteer = active ? request : undefined;
-					onSteerActiveChange?.(request, active);
-				}
-			},
-		}).then(
-			(responses) => {
+		})
+			.then(
+				(responses) => {
+					if (requestGeneration !== generation || sessionAbort.signal.aborted)
+						return;
+					if (deliver(ctx, steerResponse(request.prompts, responses))) {
+						const saved = close(
+							ctx,
+							request.id,
+							normalizeResponses(request.prompts, responses) ?? undefined,
+						);
+						requests.complete(
+							request.id,
+							saved
+								? undefined
+								: "Answer delivered, but question state could not be saved; inspect the agent before retrying",
+						);
+					} else {
+						requests.complete(
+							request.id,
+							"Answer could not be delivered; the question is open again",
+						);
+						activeSteers.delete(request.id);
+						startSteer(request, ctx, false);
+					}
+				},
+				(error: unknown) => {
+					if (requestGeneration !== generation || sessionAbort.signal.aborted)
+						return;
+					const message = notifyFailure(ctx, error);
+					if (
+						deliver(
+							ctx,
+							`The asynchronous ask failed before I could answer: ${message}`,
+						)
+					) {
+						const saved = close(ctx, request.id);
+						requests.complete(
+							request.id,
+							saved
+								? undefined
+								: "Question state could not be saved; inspect the agent before retrying",
+						);
+					} else requests.complete(request.id, message);
+				},
+			)
+			.catch((error: unknown) => {
 				if (requestGeneration !== generation || sessionAbort.signal.aborted)
 					return;
-				if (deliver(ctx, steerResponse(request.prompts, responses)))
-					close(
-						ctx,
-						request.id,
-						normalizeResponses(request.prompts, responses) ?? undefined,
-					);
-			},
-			(error: unknown) => {
-				if (requestGeneration !== generation || sessionAbort.signal.aborted)
-					return;
-				const message = notifyFailure(ctx, error);
-				if (
-					deliver(
-						ctx,
-						`The asynchronous ask failed before I could answer: ${message}`,
-					)
-				)
-					close(ctx, request.id);
-			},
-		);
+				requests.complete(request.id, String(error));
+				notifyFailure(ctx, error);
+			});
 	};
 
 	return {
 		canSteer: deliverSteer !== undefined,
 		present,
+		reply: (id: string, message: string) => requests.reply(id, message),
+		complete: (id: string, error?: string) => requests.complete(id, error),
 		requestSteer(request: PendingAsk, ctx: ExtensionContext) {
 			startSteer(request, ctx, true);
 		},
 		restorePending(pending: readonly PendingAsk[], ctx: ExtensionContext) {
 			generation++;
-			presentedSteer = undefined;
+			requests.reset();
 			sessionAbort.abort();
 			sessionAbort = new AbortController();
 			presentationTail = Promise.resolve();
@@ -184,14 +218,10 @@ export function createAskCoordinator({
 			for (const request of pending) startSteer(request, ctx, false);
 		},
 		shutdown() {
-			try {
-				if (presentedSteer) onSteerActiveChange?.(presentedSteer, false);
-			} finally {
-				presentedSteer = undefined;
-				generation++;
-				sessionAbort.abort();
-				activeSteers.clear();
-			}
+			generation++;
+			requests.reset();
+			sessionAbort.abort();
+			activeSteers.clear();
 		},
 		get sessionSignal(): AbortSignal {
 			return sessionAbort.signal;

package/ask/extension-messages.ts

@@ -0,0 +1,85 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AskRequest, RequestChange } from "./requests.js";
+
+const ENTRY = "shepherdr-extension-message";
+const REPLY_CHANNEL = "@howaboua/pi-shepherdr/extension-reply/v1";
+const EXTENSION = "@howaboua/pi-ask";
+
+function questionText(request: AskRequest): string {
+	return [
+		request.handoff
+			? "Human action required; ask the user to complete this handoff"
+			: request.steering
+				? "Question pending; the agent can continue reversible work, but still needs an answer"
+				: "Question pending; the agent is waiting for an answer",
+		...request.prompts.map((prompt, index) =>
+			[
+				`${index + 1}. ${prompt.title}`,
+				...(prompt.body ? [prompt.body] : []),
+				...(prompt.choices.length
+					? [
+							`Choose ${prompt.multiple ? "one or more" : "one"}:`,
+							...prompt.choices.map(
+								(choice) =>
+									`- ${choice.label}${choice.description ? `: ${choice.description}` : ""}`,
+							),
+						]
+					: ["Free-text answer"]),
+			].join("\n"),
+		),
+		...(request.handoff
+			? []
+			: [
+					"Reply with a JSON array in prompt order: selections contains exact choice labels; other supplies free text; comment is optional. Blank other requests rephrasing. Replace the placeholders in the reply below, do not send them literally. An ordinary agent message does not resolve this question",
+				]),
+	].join("\n\n");
+}
+
+/** Ask owns question text and reply semantics; Shepherdr carries opaque strings. */
+export function publishAskRequest(
+	pi: ExtensionAPI,
+	change: RequestChange,
+): void {
+	const base = { version: 1, extension: EXTENSION };
+	if (change.state === "closed") {
+		pi.appendEntry(ENTRY, { ...base, id: change.id, state: "closed" });
+		return;
+	}
+	const { request } = change;
+	pi.appendEntry(ENTRY, {
+		...base,
+		id: request.id,
+		state: "pending",
+		message: questionText(request),
+		blocking: !request.steering,
+		...(request.handoff
+			? {}
+			: {
+					reply: JSON.stringify(
+						request.prompts.map((prompt) =>
+							prompt.choices.length
+								? { selections: ["<choice label>"] }
+								: { other: "<answer>" },
+						),
+					),
+				}),
+	});
+}
+
+export function registerAskReplies(
+	pi: ExtensionAPI,
+	reply: (id: string, message: string) => Promise<string>,
+): void {
+	pi.events.on(REPLY_CHANNEL, (value: unknown) => {
+		if (!value || typeof value !== "object") return;
+		const event = value as Record<string, unknown>;
+		if (
+			event["extension"] !== EXTENSION ||
+			typeof event["id"] !== "string" ||
+			typeof event["message"] !== "string" ||
+			typeof event["respond"] !== "function"
+		)
+			return;
+		event["respond"](reply(event["id"], event["message"]));
+	});
+}

package/ask/normalize.ts

@@ -44,6 +44,44 @@ function normalizePrompt(
 	};
 }
 
+const ASK_FIELDS = ["help", "handoff", "prompts", "delivery"];
+const PROMPT_FIELDS = ["title", "body", "multiple", "choices"];
+const CHOICE_FIELDS = ["label", "description"];
+const CHOICE_SHAPE = "{ label, description? }";
+
+function unknownField(
+	value: Record<string, unknown>,
+	fields: string[],
+	path: string,
+): string | undefined {
+	const field = Object.keys(value).find((key) => !fields.includes(key));
+	return field === undefined
+		? undefined
+		: `Unknown ask field ${path}${field}; allowed: ${fields.join(", ")}`;
+}
+
+/** Why a tool call would lose input to normalization, so a misnamed field fails instead of vanishing. */
+export function askInputProblem(params: unknown): string | undefined {
+	if (!isRecord(params)) return undefined;
+	const top = unknownField(params, ASK_FIELDS, "");
+	if (top) return top;
+	if (!Array.isArray(params["prompts"])) return undefined;
+	for (const [index, prompt] of params["prompts"].entries()) {
+		if (!isRecord(prompt)) continue;
+		const path = `prompts[${index}]`;
+		const field = unknownField(prompt, PROMPT_FIELDS, `${path}.`);
+		if (field) return `${field}; choices: [${CHOICE_SHAPE}]`;
+		if (!Array.isArray(prompt["choices"])) continue;
+		for (const [choiceIndex, choice] of prompt["choices"].entries()) {
+			const choicePath = `${path}.choices[${choiceIndex}]`;
+			if (!isRecord(choice)) return `${choicePath} must be ${CHOICE_SHAPE}`;
+			const choiceField = unknownField(choice, CHOICE_FIELDS, `${choicePath}.`);
+			if (choiceField) return choiceField;
+		}
+	}
+	return undefined;
+}
+
 export function isSteeringAskInput(input: unknown): boolean {
 	return (
 		isRecord(input) &&
@@ -52,6 +90,13 @@ export function isSteeringAskInput(input: unknown): boolean {
 	);
 }
 
+export function isAskHelpInput(input: unknown): boolean {
+	if (input === undefined) return true;
+	if (!isRecord(input) || Array.isArray(input)) return false;
+	const keys = Object.keys(input);
+	return keys.length === 0 || (keys.length === 1 && input["help"] === true);
+}
+
 export function normalizeAskInput(params: unknown): {
 	delivery: "wait" | "steer";
 	handoff: boolean;

package/ask/requests.ts

@@ -0,0 +1,189 @@
+import type { AskPrompt, AskResponse } from "./contracts.js";
+import { customSelectionFor } from "./state.js";
+
+export interface AskRequest {
+	id: string;
+	prompts: AskPrompt[];
+	handoff: boolean;
+	steering: boolean;
+}
+
+export type RequestChange =
+	| { state: "pending"; request: AskRequest }
+	| { state: "closed"; id: string };
+
+type Completion = { error: string } | { message: string };
+
+interface OpenRequest {
+	request: AskRequest;
+	controller: AbortController;
+	selected: boolean;
+	resolve: (response: unknown) => void;
+	finish: (result: Completion) => void;
+	completion: Promise<Completion>;
+}
+
+function parseAnswers(prompts: AskPrompt[], text: string): AskResponse[] {
+	let input: unknown;
+	try {
+		input = JSON.parse(text);
+	} catch {
+		throw new Error("Reply must be a JSON array of answers in prompt order");
+	}
+	if (!Array.isArray(input) || input.length !== prompts.length)
+		throw new Error(
+			`Provide exactly ${prompts.length} answers in prompt order`,
+		);
+	return prompts.map((prompt, index) => {
+		const value: unknown = input[index];
+		if (!value || typeof value !== "object" || Array.isArray(value))
+			throw new Error(`Answer ${index + 1} must be an object`);
+		const answer = value as Record<string, unknown>;
+		if (
+			Object.keys(answer).some(
+				(key) => !["selections", "other", "comment"].includes(key),
+			) ||
+			(answer["other"] !== undefined && typeof answer["other"] !== "string") ||
+			(answer["comment"] !== undefined && typeof answer["comment"] !== "string")
+		)
+			throw new Error(`Answer ${index + 1}: use selections, other or comment`);
+		const selections = answer["selections"] ?? [];
+		if (
+			!Array.isArray(selections) ||
+			!selections.every(
+				(value): value is string =>
+					typeof value === "string" &&
+					prompt.choices.some((choice) => choice.label === value),
+			)
+		)
+			throw new Error(
+				`Answer ${index + 1}: selections must match choice labels`,
+			);
+		const selected = [...new Set(selections)];
+		if (typeof answer["other"] === "string")
+			selected.push(customSelectionFor(answer["other"]));
+		const comment =
+			typeof answer["comment"] === "string" ? answer["comment"].trim() : "";
+		if (!selected.length && !comment)
+			throw new Error(
+				`Answer ${index + 1}: supply a selection, other or comment`,
+			);
+		if (!prompt.multiple && selected.length > 1)
+			throw new Error(
+				`Answer ${index + 1} accepts only one selection or other`,
+			);
+		return {
+			id: prompt.id,
+			selections: selected,
+			...(comment ? { comment } : {}),
+		};
+	});
+}
+
+/** Owns the race between the human panel, remote replies and session cancellation. */
+export class AskRequests {
+	private readonly requests = new Map<string, OpenRequest>();
+	private readonly onChange: ((change: RequestChange) => void) | undefined;
+	constructor(onChange?: (change: RequestChange) => void) {
+		this.onChange = onChange;
+	}
+
+	open(request: AskRequest, signal?: AbortSignal) {
+		if (this.requests.has(request.id))
+			throw new Error("Ask is already pending");
+		let resolve!: (response: unknown) => void;
+		let reject!: (error: unknown) => void;
+		let finish!: (result: Completion) => void;
+		const response = new Promise<unknown>((done, fail) => {
+			resolve = done;
+			reject = fail;
+		});
+		const completion = new Promise<Completion>((done) => {
+			finish = done;
+		});
+		const entry: OpenRequest = {
+			request,
+			controller: new AbortController(),
+			selected: false,
+			resolve,
+			finish,
+			completion,
+		};
+		const select = (value: unknown) => {
+			if (entry.selected) return;
+			entry.selected = true;
+			resolve(value);
+			entry.controller.abort();
+		};
+		const abort = () => select(null);
+		this.onChange?.({ state: "pending", request });
+		this.requests.set(request.id, entry);
+		signal?.addEventListener("abort", abort, { once: true });
+		if (signal?.aborted) abort();
+		return {
+			response: response.finally(() =>
+				signal?.removeEventListener("abort", abort),
+			),
+			signal: entry.controller.signal,
+			select,
+			fail(error: unknown) {
+				if (entry.selected) return;
+				entry.selected = true;
+				reject(error);
+				entry.controller.abort();
+			},
+		};
+	}
+
+	async reply(id: string, text: string): Promise<string> {
+		const entry = this.requests.get(id);
+		if (!entry)
+			throw new Error(
+				"This question is no longer pending; read the agent's latest state",
+			);
+		if (entry.request.handoff)
+			throw new Error(
+				"This handoff requires the user's action and confirmation",
+			);
+		if (entry.selected)
+			throw new Error(
+				"This question already has a response; read the agent's latest state",
+			);
+		const answers = parseAnswers(entry.request.prompts, text);
+		entry.selected = true;
+		entry.resolve(answers);
+		entry.controller.abort();
+		const result = await entry.completion;
+		if ("error" in result) throw new Error(result.error);
+		return result.message;
+	}
+
+	complete(id: string, error?: string): void {
+		const entry = this.requests.get(id);
+		if (!entry) return;
+		this.requests.delete(id);
+		try {
+			if (!error || !entry.request.steering)
+				this.onChange?.({ state: "closed", id });
+			entry.finish(error ? { error } : { message: "Answer accepted" });
+		} catch (failure) {
+			entry.finish({
+				error: `Response received, but question state could not be saved: ${String(failure)}`,
+			});
+			throw failure;
+		}
+	}
+
+	reset(): void {
+		for (const entry of this.requests.values()) {
+			entry.selected = true;
+			entry.resolve(null);
+			entry.controller.abort();
+			this.complete(
+				entry.request.id,
+				"Session changed before the answer was delivered; read the agent's latest state",
+			);
+		}
+		this.requests.clear();
+	}
+}

package/ask/tool.ts

@@ -1,11 +1,14 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
+import { Check } from "typebox/value";
 import { AskParameters, type AskPrompt } from "./contracts.js";
 import {
 	type AskCoordinatorOptions,
 	createAskCoordinator,
 } from "./coordinator.js";
 import {
+	askInputProblem,
+	isAskHelpInput,
 	isSteeringAskInput,
 	normalizeAskInput,
 	normalizeResponses,
@@ -33,27 +36,46 @@ export function createAskRuntime({
 	deliverSteer,
 	onBlockedChange,
 	onPendingChange,
-	onSteerActiveChange,
+	onRequestChange,
 }: AskToolOptions = {}) {
 	const coordinator = createAskCoordinator({
 		...(askInComposer ? { askInComposer } : {}),
 		...(deliverSteer ? { deliverSteer } : {}),
 		...(onPendingChange ? { onPendingChange } : {}),
-		...(onSteerActiveChange ? { onSteerActiveChange } : {}),
+		...(onRequestChange ? { onRequestChange } : {}),
 	});
 
 	const tool = defineTool({
 		name: "ask",
 		label: "Ask",
-		description: "Request user input or action",
+		description: "Request user input or action; {} for help",
 		parameters: AskParameters,
-		promptGuidelines: [
-			"ask: Omit delivery to wait; steer only while reversible work can continue. Handoffs wait for user action; state the completion signal",
-			"ask: For reviews, make each finding a prompt with disposition choices; do not report first.",
-			"ask: Other/rephrase is automatic; omit choices for free text",
-		],
 		executionMode: "sequential",
+		prepareArguments(input) {
+			const params = input === undefined ? {} : input;
+			const problem = askInputProblem(params);
+			if (problem) throw new Error(problem);
+			if (!Check(AskParameters, params))
+				throw new Error("Invalid ask arguments; ask({}) returns help");
+			return params;
+		},
 		async execute(toolCallId, params, signal, _onUpdate, ctx) {
+			if (isAskHelpInput(params)) {
+				return {
+					content: [
+						textContent(
+							[
+								"ask({}) or ask({ help: true }) returns help",
+								'ask({ prompts: [{ title, body?, multiple?, choices?: [{ label, description? }] }], delivery?: "wait"|"steer", handoff? })',
+								"Omit delivery to wait; steer only while reversible work can continue. Handoffs wait for user action; state the completion signal",
+								"For reviews, make each finding a prompt with disposition choices; do not report first",
+								"Other/rephrase is automatic; omit choices for free text. Blank Other/rephrase means rephrase or follow up",
+							].join("\n"),
+						),
+					],
+					details: { kind: "help" },
+				};
+			}
 			const { delivery, handoff, prompts } = normalizeAskInput(params);
 			if (prompts.length === 0) {
 				throw new Error(
@@ -92,12 +114,20 @@ export function createAskRuntime({
 			const presentationSignal = signal
 				? AbortSignal.any([signal, coordinator.sessionSignal])
 				: coordinator.sessionSignal;
-			const rawResponses = await coordinator.present(ctx, prompts, {
-				handoff,
-				signal: presentationSignal,
-				onActiveChange: (active) =>
-					onBlockedChange?.({ ...blockedState, active }),
-			});
+			let rawResponses: unknown;
+			try {
+				rawResponses = await coordinator.present(ctx, prompts, {
+					id: toolCallId,
+					handoff,
+					signal: presentationSignal,
+					onActiveChange: (active) =>
+						onBlockedChange?.({ ...blockedState, active }),
+				});
+				coordinator.complete(toolCallId);
+			} catch (error) {
+				coordinator.complete(toolCallId, String(error));
+				throw error;
+			}
 			const responses = normalizeResponses(prompts, rawResponses);
 			if (!responses) {
 				return {
@@ -115,6 +145,8 @@ export function createAskRuntime({
 			};
 		},
 		renderCall(args, theme, context) {
+			if (isAskHelpInput(args))
+				return new Text(theme.fg("toolTitle", theme.bold("ask help")), 0, 0);
 			const count = Array.isArray(args.prompts) ? args.prompts.length : 0;
 			const label =
 				args.handoff === true
@@ -142,6 +174,7 @@ export function createAskRuntime({
 
 	return {
 		tool,
+		reply: coordinator.reply,
 		restorePending: coordinator.restorePending,
 		shutdown: coordinator.shutdown,
 	};

package/index.ts

@@ -9,7 +9,11 @@ import {
 	createSteerDelivery,
 	type TryCodexDeveloperMessage,
 } from "./ask/delivery.js";
-import { isSteeringAskInput } from "./ask/normalize.js";
+import {
+	publishAskRequest,
+	registerAskReplies,
+} from "./ask/extension-messages.js";
+import { isAskHelpInput, isSteeringAskInput } from "./ask/normalize.js";
 import { PENDING_ASK_ENTRY_TYPE, readPendingAsks } from "./ask/pending.js";
 import { createAskRuntime, createAskTool } from "./ask/tool.js";
 import registerPackageChangelog from "./changelog.js";
@@ -27,57 +31,25 @@ export default async function humanInTheLoop(pi: ExtensionAPI): Promise<void> {
 	registerPackageChangelog(pi);
 	const trySendCodexDeveloperMessage = await loadCodexDeveloperMessageSender();
 	const askRuntime = createAskRuntime({
+		onRequestChange: (change) => publishAskRequest(pi, change),
 		deliverSteer: createSteerDelivery(pi, trySendCodexDeveloperMessage),
 		onBlockedChange: (state) => {
-			const notify = () => {
-				pi.events.emit(REALTIME_VOICE_PROMPT_CHANNEL, {
-					id: state.id,
-					active: state.active,
-					prompt: state.prompt,
-				});
-				pi.events.emit("herdr:blocked", {
-					active: state.active,
-					label: state.label,
-				});
-			};
-			// Publish before Herdr reports blocked, including calls nested inside exec.
-			try {
-				pi.appendEntry(
-					"pi-ask-active",
-					state.active
-						? {
-								version: 1,
-								state: "active",
-								id: state.id,
-								handoff: state.handoff,
-								prompts: state.prompts,
-							}
-						: { version: 1, state: "closed", id: state.id },
-				);
-			} finally {
-				if (!state.active) notify();
-			}
-			if (state.active) notify();
+			pi.events.emit(REALTIME_VOICE_PROMPT_CHANNEL, {
+				id: state.id,
+				active: state.active,
+				prompt: state.prompt,
+			});
+			pi.events.emit("herdr:blocked", {
+				active: state.active,
+				label: state.label,
+			});
 		},
 		onPendingChange: (update) => {
 			pi.appendEntry(PENDING_ASK_ENTRY_TYPE, update);
 		},
-		onSteerActiveChange: (request, active) => {
-			pi.appendEntry(
-				"pi-ask-active",
-				active
-					? {
-							version: 1,
-							state: "active",
-							id: request.id,
-							delivery: "steer",
-							prompts: request.prompts,
-						}
-					: { version: 1, state: "closed", id: request.id },
-			);
-		},
 	});
 	const ask = askRuntime.tool;
+	registerAskReplies(pi, askRuntime.reply);
 	const restorePending = (ctx: ExtensionContext) => {
 		askRuntime.restorePending(
 			readPendingAsks(ctx.sessionManager.getBranch()),
@@ -127,9 +99,9 @@ async function registerAskInCodeMode(
 			await import("@howaboua/pi-codex-conversion/code-mode");
 		const registration = registerCodeModeExtensionTools(pi, () => [
 			adaptToolForCodeMode(ask, {
-				blocking: (input) => !isSteeringAskInput(input),
-				usage:
-					'await tools.ask({ prompts: [{ title, body?, multiple?, choices?: [{ label, description? }] }], delivery?: "wait"|"steer", handoff? })',
+				blocking: (input) =>
+					!isAskHelpInput(input) && !isSteeringAskInput(input),
+				usage: "await tools.ask() // help",
 			}),
 		]);
 		pi.on("session_shutdown", () => registration.unregister());

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@howaboua/pi-ask",
-	"version": "0.0.11",
+	"version": "0.0.13",
 	"description": "Interactive decisions, review triage, and human handoffs for Pi.",
 	"type": "module",
 	"license": "MIT",
@@ -45,7 +45,7 @@
 		]
 	},
 	"peerDependencies": {
-		"@howaboua/pi-codex-conversion": ">=3.0.46",
+		"@howaboua/pi-codex-conversion": ">=3.0.50",
 		"@earendil-works/pi-ai": ">=1.0.0",
 		"@earendil-works/pi-coding-agent": ">=1.0.0",
 		"@earendil-works/pi-tui": ">=1.0.0",
@@ -57,18 +57,17 @@
 		}
 	},
 	"devDependencies": {
-		"@howaboua/pi-codex-conversion": "3.0.46",
+		"@howaboua/pi-codex-conversion": "3.0.50",
 		"@biomejs/biome": "^2.5.10",
-		"@earendil-works/pi-ai": "1.0.4",
-		"@earendil-works/pi-coding-agent": "1.0.4",
-		"@earendil-works/pi-tui": "1.0.4",
+		"@earendil-works/pi-ai": "1.1.0",
+		"@earendil-works/pi-coding-agent": "1.1.0",
+		"@earendil-works/pi-tui": "1.1.0",
 		"typebox": "1.3.18",
 		"typescript": "^7.0.2"
 	},
 	"scripts": {
-		"check": "bun run lint && bun run typecheck && bun run test",
+		"check": "bun run lint && bun run typecheck",
 		"prepack": "bun run check",
-		"test": "bun test",
 		"typecheck": "tsgo --noEmit",
 		"lint": "biome check .",
 		"format": "biome check --write .",