@howaboua/pi-ask 0.0.6 → 0.0.8

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @howaboua/pi-ask
 
+## 0.0.8
+
+- Shepherdr now discovers and answers waiting questions invoked inside Code and Notebook Mode.
+
+## 0.0.7
+
+- The `ask` tool now supports steering questions that return immediately, preserve the full response panel, and deliver answers at the next safe boundary using the developer role under active Pi Codex Responses.
+
 ## 0.0.6
 
 - Added a Code and Notebook Mode bridge API. This allows extensions that use Pi TUI to run inside `exec`.

package/README.md

@@ -14,15 +14,17 @@ Try it for one session:
 pi -e npm:@howaboua/pi-ask
 ```
 
-When [Pi Codex](https://www.npmjs.com/package/@howaboua/pi-codex-conversion) 3.0.24 or newer is installed too, `ask` is available inside Code and Notebook Mode as `await tools.ask({ prompts, handoff? })`.
+When [Pi Codex](https://www.npmjs.com/package/@howaboua/pi-codex-conversion) 3.0.25 or newer is installed too, `ask` is available inside Code and Notebook Mode as `await tools.ask({ prompts, delivery?, handoff? })`.
 
 ## 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.
 
+Questions wait for your response by default. When the agent can continue useful reversible work, it can use `delivery: "steer"` instead. The tool then returns immediately, keeps the same panel open, and delivers your eventual response as steering at the next safe boundary. An active Pi Codex Responses adapter sends the answer with the developer role; other setups receive an ordinary user steering message. Pending steering questions survive session reloads.
+
 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.
 
-When Pi runs inside Herdr with its Pi integration installed, an open ask panel marks the pane as blocked until you submit, dismiss, or abort it.
+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.
 
 `Other/rephrase` is always available. Submit it blank when the prompt needs to be rephrased, split, or followed up instead of answered as written.
 

package/ask/contracts.ts

@@ -1,5 +1,8 @@
+import { StringEnum } from "@earendil-works/pi-ai";
 import { type Static, Type } from "typebox";
 
+const ASK_DELIVERIES = ["wait", "steer"] as const;
+
 const ChoiceSchema = Type.Object({
 	label: Type.String({ description: "Short choice." }),
 	description: Type.Optional(Type.String({ description: "Optional detail." })),
@@ -19,9 +22,14 @@ export const AskParameters = Type.Object({
 		Type.Boolean({ description: "Wait for user action." }),
 	),
 	prompts: Type.Array(PromptSchema, { description: "Prompts." }),
+	delivery: Type.Optional(
+		StringEnum(ASK_DELIVERIES, {
+			description:
+				"Wait for a gating response; steer while continuing reversible work. Omit to wait.",
+		}),
+	),
 });
 
-export type AskInput = Static<typeof AskParameters>;
 export type PromptChoice = Static<typeof ChoiceSchema>;
 
 export interface AskPrompt {
@@ -32,6 +40,11 @@ export interface AskPrompt {
 	choices: PromptChoice[];
 }
 
+export interface PendingAsk {
+	id: string;
+	prompts: AskPrompt[];
+}
+
 export interface AskResponse {
 	id: string;
 	selections: string[];

package/ask/coordinator.ts

@@ -0,0 +1,172 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AskPrompt, PendingAsk } from "./contracts.js";
+import { normalizeResponses, summarizeResponses } from "./normalize.js";
+import type { PendingAskUpdate } from "./pending.js";
+import { askWithPiUi } from "./pi-ui.js";
+import { askInTui } from "./tui.js";
+
+type AskInComposer = (
+	prompts: AskPrompt[],
+	signal: AbortSignal | undefined,
+) => Promise<unknown>;
+
+export interface AskCoordinatorOptions {
+	askInComposer?: AskInComposer;
+	deliverSteer?: (message: string) => void;
+	onPendingChange?: (update: PendingAskUpdate) => void;
+}
+
+interface PresentAskOptions {
+	onActiveChange?: (active: boolean) => void;
+	handoff?: boolean;
+	steering?: boolean;
+	signal?: AbortSignal;
+}
+
+function steerResponse(prompts: AskPrompt[], responses: unknown): string {
+	const normalized = normalizeResponses(prompts, responses);
+	return normalized
+		? `Response to your earlier ask:\n${summarizeResponses(prompts, normalized)}`
+		: `I dismissed your earlier ask: ${prompts.map((prompt) => prompt.title).join("; ")}`;
+}
+
+export function createAskCoordinator({
+	askInComposer,
+	deliverSteer,
+	onPendingChange,
+}: AskCoordinatorOptions = {}) {
+	let generation = 0;
+	let sessionAbort = new AbortController();
+	let presentationTail = Promise.resolve();
+	const activeSteers = new Set<string>();
+
+	const present = (
+		ctx: ExtensionContext,
+		prompts: AskPrompt[],
+		{
+			handoff = false,
+			steering = false,
+			signal,
+			onActiveChange,
+		}: PresentAskOptions = {},
+	): Promise<unknown> => {
+		const run = async () => {
+			if (signal?.aborted) return null;
+			try {
+				onActiveChange?.(true);
+				return askInComposer
+					? await askInComposer(prompts, signal)
+					: ctx.mode === "tui"
+						? await askInTui(ctx, prompts, {
+								handoff,
+								steering,
+								...(signal ? { signal } : {}),
+							})
+						: await askWithPiUi(ctx, prompts, {
+								handoff,
+								steering,
+								...(signal ? { signal } : {}),
+							});
+			} finally {
+				onActiveChange?.(false);
+			}
+		};
+		const result = presentationTail.then(run, run);
+		presentationTail = result.then(
+			() => undefined,
+			() => undefined,
+		);
+		return result;
+	};
+
+	const notifyFailure = (ctx: ExtensionContext, error: unknown) => {
+		const message = error instanceof Error ? error.message : String(error);
+		ctx.ui.notify(`Async ask failed: ${message}`, "error");
+		return message;
+	};
+
+	const deliver = (ctx: ExtensionContext, message: string): boolean => {
+		try {
+			deliverSteer?.(message);
+			return true;
+		} catch (error) {
+			notifyFailure(ctx, error);
+			return false;
+		}
+	};
+
+	const close = (ctx: ExtensionContext, id: string) => {
+		activeSteers.delete(id);
+		try {
+			onPendingChange?.({ version: 1, state: "closed", id });
+		} catch (error) {
+			notifyFailure(ctx, error);
+		}
+	};
+
+	const startSteer = (
+		request: PendingAsk,
+		ctx: ExtensionContext,
+		persist: boolean,
+	) => {
+		if (activeSteers.has(request.id) || sessionAbort.signal.aborted) return;
+		if (persist) {
+			onPendingChange?.({
+				version: 1,
+				state: "pending",
+				id: request.id,
+				prompts: request.prompts,
+			});
+		}
+		activeSteers.add(request.id);
+		const requestGeneration = generation;
+		void present(ctx, request.prompts, {
+			steering: true,
+			signal: sessionAbort.signal,
+		}).then(
+			(responses) => {
+				if (requestGeneration !== generation || sessionAbort.signal.aborted)
+					return;
+				if (deliver(ctx, steerResponse(request.prompts, responses)))
+					close(ctx, request.id);
+			},
+			(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);
+			},
+		);
+	};
+
+	return {
+		canSteer: deliverSteer !== undefined,
+		present,
+		requestSteer(request: PendingAsk, ctx: ExtensionContext) {
+			startSteer(request, ctx, true);
+		},
+		restorePending(pending: readonly PendingAsk[], ctx: ExtensionContext) {
+			generation++;
+			sessionAbort.abort();
+			sessionAbort = new AbortController();
+			presentationTail = Promise.resolve();
+			activeSteers.clear();
+			if ((!askInComposer && !ctx.hasUI) || !deliverSteer) return;
+			for (const request of pending) startSteer(request, ctx, false);
+		},
+		shutdown() {
+			generation++;
+			sessionAbort.abort();
+			activeSteers.clear();
+		},
+		get sessionSignal(): AbortSignal {
+			return sessionAbort.signal;
+		},
+	};
+}

package/ask/delivery.ts

@@ -0,0 +1,23 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export type TryCodexDeveloperMessage = (
+	pi: ExtensionAPI,
+	content: string,
+	options: { deliverAs: "steer"; triggerTurn: true },
+) => boolean;
+
+export function createSteerDelivery(
+	pi: ExtensionAPI,
+	trySendCodexDeveloperMessage?: TryCodexDeveloperMessage,
+): (message: string) => void {
+	return (message) => {
+		if (
+			trySendCodexDeveloperMessage?.(pi, message, {
+				deliverAs: "steer",
+				triggerTurn: true,
+			})
+		)
+			return;
+		pi.sendUserMessage(message, { deliverAs: "steer" });
+	};
+}

package/ask/normalize.ts

@@ -1,10 +1,5 @@
 import { HANDOFF_CHOICES, OTHER_OPTION_LABEL } from "./constants.js";
-import type {
-	AskInput,
-	AskPrompt,
-	AskResponse,
-	PromptChoice,
-} from "./contracts.js";
+import type { AskPrompt, AskResponse, PromptChoice } from "./contracts.js";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null;
@@ -49,17 +44,31 @@ function normalizePrompt(
 	};
 }
 
-export function normalizeAskInput(params: AskInput | null | undefined): {
+export function isSteeringAskInput(input: unknown): boolean {
+	return (
+		isRecord(input) &&
+		input["delivery"] === "steer" &&
+		input["handoff"] !== true
+	);
+}
+
+export function normalizeAskInput(params: unknown): {
+	delivery: "wait" | "steer";
 	handoff: boolean;
 	prompts: AskPrompt[];
 } {
-	const handoff = params?.handoff === true;
-	const prompts = Array.isArray(params?.prompts)
-		? params.prompts
+	const input = isRecord(params) ? params : {};
+	const handoff = input["handoff"] === true;
+	const prompts = Array.isArray(input["prompts"])
+		? input["prompts"]
 				.map((prompt, index) => normalizePrompt(prompt, index, handoff))
 				.filter((prompt) => prompt !== null)
 		: [];
-	return { handoff, prompts };
+	return {
+		delivery: input["delivery"] === "steer" ? "steer" : "wait",
+		handoff,
+		prompts,
+	};
 }
 
 export function normalizeResponses(

package/ask/pending.ts

@@ -0,0 +1,39 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { AskPrompt, PendingAsk } from "./contracts.js";
+import { normalizeAskInput } from "./normalize.js";
+
+export const PENDING_ASK_ENTRY_TYPE = "pi-ask-pending";
+
+export type PendingAskUpdate =
+	| { version: 1; state: "pending"; id: string; prompts: AskPrompt[] }
+	| { version: 1; state: "closed"; id: string };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function parsePendingAskUpdate(value: unknown): PendingAskUpdate | undefined {
+	if (!isRecord(value) || value["version"] !== 1) return undefined;
+	const id = typeof value["id"] === "string" ? value["id"].trim() : "";
+	if (!id) return undefined;
+	if (value["state"] === "closed") return { version: 1, state: "closed", id };
+	if (value["state"] !== "pending") return undefined;
+	const { prompts } = normalizeAskInput({ prompts: value["prompts"] });
+	if (prompts.length === 0) return undefined;
+	return { version: 1, state: "pending", id, prompts };
+}
+
+export function readPendingAsks(
+	entries: readonly SessionEntry[],
+): PendingAsk[] {
+	const pending = new Map<string, PendingAsk>();
+	for (const entry of entries) {
+		if (entry.type !== "custom" || entry.customType !== PENDING_ASK_ENTRY_TYPE)
+			continue;
+		const update = parsePendingAskUpdate(entry.data);
+		if (!update) continue;
+		if (update.state === "closed") pending.delete(update.id);
+		else pending.set(update.id, { id: update.id, prompts: update.prompts });
+	}
+	return [...pending.values()];
+}

package/ask/pi-ui.ts

@@ -22,9 +22,14 @@ async function askOther(
 	return value === undefined ? null : customSelectionFor(value);
 }
 
-function promptText(prompt: AskPrompt, handoff: boolean): string {
+function promptText(
+	prompt: AskPrompt,
+	handoff: boolean,
+	steering: boolean,
+): string {
 	const text = prompt.body ? `${prompt.title}\n\n${prompt.body}` : prompt.title;
-	return handoff ? `Human action needed\n\n${text}` : text;
+	if (handoff) return `Human action needed\n\n${text}`;
+	return steering ? `Agent continues while you decide\n\n${text}` : text;
 }
 
 async function askComment(
@@ -56,18 +61,19 @@ async function askSingleWithPiUi(
 	ctx: ExtensionContext,
 	prompt: AskPrompt,
 	handoff: boolean,
+	steering: 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),
+					promptText(prompt, handoff, steering),
 					[...choices, OTHER_OPTION_LABEL],
 					dialogOptions(signal),
 				)
 			: await ctx.ui.input(
-					promptText(prompt, handoff),
+					promptText(prompt, handoff, steering),
 					"Response",
 					dialogOptions(signal),
 				);
@@ -82,6 +88,7 @@ async function askMultipleWithPiUi(
 	ctx: ExtensionContext,
 	prompt: AskPrompt,
 	handoff: boolean,
+	steering: boolean,
 	signal?: AbortSignal,
 ): Promise<string[] | null> {
 	const choices = prompt.choices.map((choice) => choice.label);
@@ -89,7 +96,7 @@ async function askMultipleWithPiUi(
 	const picked: string[] = [];
 	while (true) {
 		const next = await ctx.ui.select(
-			promptText(prompt, handoff),
+			promptText(prompt, handoff, steering),
 			[
 				...choices.filter((choice) => !picked.includes(choice)),
 				OTHER_OPTION_LABEL,
@@ -112,14 +119,18 @@ async function askMultipleWithPiUi(
 export async function askWithPiUi(
 	ctx: ExtensionContext,
 	prompts: AskPrompt[],
-	{ handoff = false, signal }: { handoff?: boolean; signal?: AbortSignal } = {},
+	{
+		handoff = false,
+		steering = false,
+		signal,
+	}: { handoff?: boolean; steering?: 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);
+			? await askMultipleWithPiUi(ctx, prompt, handoff, steering, signal)
+			: await askSingleWithPiUi(ctx, prompt, handoff, steering, signal);
 		if (!selections) return null;
 		const comment = await askComment(ctx, prompt, signal);
 		if (comment === null || signal?.aborted) return null;

package/ask/tool.ts

@@ -2,50 +2,58 @@ import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { AskParameters, type AskPrompt } from "./contracts.js";
 import {
+	type AskCoordinatorOptions,
+	createAskCoordinator,
+} from "./coordinator.js";
+import {
+	isSteeringAskInput,
 	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>;
 
 interface BlockedState {
 	id: string;
 	active: boolean;
 	label: string;
 	prompt: string;
+	handoff: boolean;
+	prompts: AskPrompt[];
 }
 
 type OnBlockedChange = (state: BlockedState) => void;
 
-export function createAskTool({
+interface AskToolOptions extends AskCoordinatorOptions {
+	onBlockedChange?: OnBlockedChange;
+}
+
+export function createAskRuntime({
 	askInComposer,
+	deliverSteer,
 	onBlockedChange,
-}: {
-	askInComposer?: AskInComposer;
-	onBlockedChange?: OnBlockedChange;
-} = {}) {
-	return defineTool({
+	onPendingChange,
+}: AskToolOptions = {}) {
+	const coordinator = createAskCoordinator({
+		...(askInComposer ? { askInComposer } : {}),
+		...(deliverSteer ? { deliverSteer } : {}),
+		...(onPendingChange ? { onPendingChange } : {}),
+	});
+
+	const tool = defineTool({
 		name: "ask",
 		label: "Ask",
-		description:
-			"Request user input or action and return the response. Requires interactive UI.",
+		description: "Request user input or action. Requires interactive UI.",
 		parameters: AskParameters,
 		promptSnippet: "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: Use steer only while useful reversible work can continue; wait for gating answers and handoffs, stating a handoff's 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);
+			const { delivery, handoff, prompts } = normalizeAskInput(params);
 			if (prompts.length === 0) {
 				throw new Error(
 					"ask requires at least one prompt with a non-empty title.",
@@ -53,32 +61,42 @@ export function createAskTool({
 			}
 			if (!askInComposer && !ctx.hasUI)
 				throw new Error("ask requires an interactive UI.");
+			if (handoff && delivery === "steer")
+				throw new Error("ask handoffs require delivery wait.");
+			if (delivery === "steer") {
+				if (!coordinator.canSteer)
+					throw new Error("ask steering delivery is unavailable.");
+				signal?.throwIfAborted();
+				coordinator.requestSteer({ id: toolCallId, prompts }, ctx);
+				return {
+					content: [
+						textContent(
+							"Question presented. Continue working; the response will arrive as steering.",
+						),
+					],
+					details: { kind: "prompt", pending: true, id: toolCallId },
+				};
+			}
 
 			const blockedState = {
 				id: toolCallId,
 				active: true,
+				handoff,
+				prompts,
 				label: handoff ? "Human action needed" : "Waiting for input",
 				prompt: handoff
 					? "The user needs to complete an action before the active work can continue. Please announce this briefly in your natural voice."
 					: "User input is required before the active work can continue. Please announce this briefly in your natural voice.",
 			};
-			onBlockedChange?.(blockedState);
-			let rawResponses: unknown;
-			try {
-				rawResponses = askInComposer
-					? await askInComposer(prompts, signal)
-					: ctx.mode === "tui"
-						? await askInTui(ctx, prompts, {
-								handoff,
-								...(signal ? { signal } : {}),
-							})
-						: await askWithPiUi(ctx, prompts, {
-								handoff,
-								...(signal ? { signal } : {}),
-							});
-			} finally {
-				onBlockedChange?.({ ...blockedState, active: false });
-			}
+			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 }),
+			});
 			const responses = normalizeResponses(prompts, rawResponses);
 			if (!responses) {
 				return {
@@ -97,12 +115,18 @@ export function createAskTool({
 		},
 		renderCall(args, theme, context) {
 			const count = Array.isArray(args.prompts) ? args.prompts.length : 0;
+			const label =
+				args.handoff === true
+					? "ask handoff "
+					: isSteeringAskInput(args)
+						? "ask steer "
+						: "ask ";
 			return new Text(
 				theme.fg(
 					context && "isBlocked" in context && context.isBlocked === true
 						? "warning"
 						: "toolTitle",
-					theme.bold(args.handoff === true ? "ask handoff " : "ask "),
+					theme.bold(label),
 				) + theme.fg("muted", `${count} prompt${count === 1 ? "" : "s"}`),
 				0,
 				0,
@@ -114,4 +138,14 @@ export function createAskTool({
 			return new Text(theme.fg("success", text), 0, 0);
 		},
 	});
+
+	return {
+		tool,
+		restorePending: coordinator.restorePending,
+		shutdown: coordinator.shutdown,
+	};
+}
+
+export function createAskTool(options: AskToolOptions = {}) {
+	return createAskRuntime(options).tool;
 }

package/ask/tui-render.ts

@@ -14,6 +14,7 @@ interface RenderTabsOptions {
 	handoff: boolean;
 	prompts: AskPrompt[];
 	responded: (index: number) => boolean;
+	steering: boolean;
 	tab: number;
 	theme: AskTheme;
 }
@@ -80,10 +81,11 @@ export function renderAskTabs({
 	handoff,
 	prompts,
 	responded,
+	steering,
 	tab,
 	theme,
 }: RenderTabsOptions): string {
-	return ` ${Array.from({ length: prompts.length + 1 }, (_, index) => {
+	const tabs = Array.from({ length: prompts.length + 1 }, (_, index) => {
 		const active = index === tab;
 		const label =
 			index === prompts.length
@@ -94,7 +96,8 @@ export function renderAskTabs({
 		return active
 			? theme.bg("selectedBg", theme.fg("text", ` ${label} `))
 			: theme.fg("muted", ` ${label} `);
-	}).join(" ")}`;
+	}).join(" ");
+	return ` ${tabs}${steering ? theme.fg("muted", "  Agent continues while you decide") : ""}`;
 }
 
 export function renderAskReview({

package/ask/tui.ts

@@ -27,7 +27,11 @@ type AddLine = (line?: string) => void;
 export async function askInTui(
 	ctx: ExtensionContext,
 	prompts: AskPrompt[],
-	{ handoff = false, signal }: { handoff?: boolean; signal?: AbortSignal } = {},
+	{
+		handoff = false,
+		steering = false,
+		signal,
+	}: { handoff?: boolean; steering?: boolean; signal?: AbortSignal } = {},
 ): Promise<AskResponse[] | null> {
 	if (!ctx.hasUI || signal?.aborted) return null;
 	return await ctx.ui.custom<AskResponse[] | null>((tui, theme, kb, done) => {
@@ -170,7 +174,14 @@ export async function askInTui(
 				lines.push(truncateToWidth(line, width));
 			add(theme.fg("accent", "─".repeat(width)));
 			add(
-				renderAskTabs({ handoff, prompts, responded, tab: state.tab, theme }),
+				renderAskTabs({
+					handoff,
+					prompts,
+					responded,
+					steering,
+					tab: state.tab,
+					theme,
+				}),
 			);
 			add();
 			if (isReview()) {

package/index.ts

@@ -1,8 +1,17 @@
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
 import { loadAskConfig } from "./ask/config.js";
-import { createAskTool } from "./ask/tool.js";
+import {
+	createSteerDelivery,
+	type TryCodexDeveloperMessage,
+} from "./ask/delivery.js";
+import { 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";
 
 export { createAskTool } from "./ask/tool.js";
@@ -12,24 +21,60 @@ const REALTIME_VOICE_PROMPT_CHANNEL =
 	"@howaboua/pi-codex-conversion/realtime-voice-prompt/v1";
 const CODE_MODE_PACKAGE = "@howaboua/pi-codex-conversion";
 const CODE_MODE_MODULE = `${CODE_MODE_PACKAGE}/code-mode`;
+const DEVELOPER_MESSAGES_MODULE = `${CODE_MODE_PACKAGE}/developer-messages`;
 
 export default async function humanInTheLoop(pi: ExtensionAPI): Promise<void> {
 	registerPackageChangelog(pi);
-	const ask = createAskTool({
+	const trySendCodexDeveloperMessage = await loadCodexDeveloperMessageSender();
+	const askRuntime = createAskRuntime({
+		deliverSteer: createSteerDelivery(pi, trySendCodexDeveloperMessage),
 		onBlockedChange: (state) => {
-			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,
-			});
+			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();
+		},
+		onPendingChange: (update) => {
+			pi.appendEntry(PENDING_ASK_ENTRY_TYPE, update);
 		},
 	});
+	const ask = askRuntime.tool;
+	const restorePending = (ctx: ExtensionContext) => {
+		askRuntime.restorePending(
+			readPendingAsks(ctx.sessionManager.getBranch()),
+			ctx,
+		);
+	};
 	pi.registerTool(ask);
 	await registerAskInCodeMode(pi, ask);
+	pi.on("session_start", (_event, ctx) => restorePending(ctx));
+	pi.on("session_tree", (_event, ctx) => restorePending(ctx));
+	pi.on("session_shutdown", () => askRuntime.shutdown());
 	pi.on("resources_discover", () => {
 		const config = loadAskConfig();
 		return {
@@ -41,6 +86,24 @@ export default async function humanInTheLoop(pi: ExtensionAPI): Promise<void> {
 	});
 }
 
+async function loadCodexDeveloperMessageSender(): Promise<
+	TryCodexDeveloperMessage | undefined
+> {
+	try {
+		const { trySendCodexDeveloperMessage } = await import(
+			"@howaboua/pi-codex-conversion/developer-messages"
+		);
+		return trySendCodexDeveloperMessage;
+	} catch (error) {
+		if (
+			isMissingCodexModule(error, DEVELOPER_MESSAGES_MODULE) ||
+			isUnavailableCodexSubpath(error, "developer-messages")
+		)
+			return undefined;
+		throw error;
+	}
+}
+
 async function registerAskInCodeMode(
 	pi: ExtensionAPI,
 	ask: ReturnType<typeof createAskTool>,
@@ -50,14 +113,14 @@ async function registerAskInCodeMode(
 			await import("@howaboua/pi-codex-conversion/code-mode");
 		const registration = registerCodeModeExtensionTools(pi, () => [
 			adaptToolForCodeMode(ask, {
-				blocking: true,
+				blocking: (input) => !isSteeringAskInput(input),
 				usage:
-					"await tools.ask({ prompts: [{ title, body?, multiple?, choices?: [{ label, description? }] }], handoff? })",
+					'await tools.ask({ prompts: [{ title, body?, multiple?, choices?: [{ label, description? }] }], delivery?: "wait"|"steer", handoff? })',
 			}),
 		]);
 		pi.on("session_shutdown", () => registration.unregister());
 	} catch (error) {
-		if (isMissingCodeModeExtension(error)) return;
+		if (isMissingCodexModule(error, CODE_MODE_MODULE)) return;
 		if (isOutdatedCodeModeExtension(error)) {
 			throw new Error(
 				"Update " +
@@ -70,7 +133,7 @@ async function registerAskInCodeMode(
 	}
 }
 
-function isMissingCodeModeExtension(error: unknown): boolean {
+function isMissingCodexModule(error: unknown, moduleName: string): boolean {
 	if (
 		!error ||
 		typeof error !== "object" ||
@@ -84,7 +147,29 @@ function isMissingCodeModeExtension(error: unknown): boolean {
 	const missing = error.message.match(
 		/Cannot find (?:package|module) ['"]([^'"]+)['"]/,
 	)?.[1];
-	return missing === CODE_MODE_PACKAGE || missing === CODE_MODE_MODULE;
+	const normalizedMissing = missing?.replaceAll("\\", "/").replace(/\.js$/, "");
+	return (
+		missing === CODE_MODE_PACKAGE ||
+		normalizedMissing === moduleName ||
+		normalizedMissing?.endsWith(`/${moduleName}`) === true
+	);
+}
+
+function isUnavailableCodexSubpath(error: unknown, subpath: string): boolean {
+	if (
+		!error ||
+		typeof error !== "object" ||
+		!("code" in error) ||
+		!("message" in error) ||
+		typeof error.message !== "string"
+	)
+		return false;
+	return (
+		(error.code === "ERR_PACKAGE_PATH_NOT_EXPORTED" ||
+			error.code === "ERR_UNSUPPORTED_DIR_IMPORT") &&
+		error.message.includes(`Package subpath './${subpath}'`) &&
+		error.message.includes(CODE_MODE_PACKAGE)
+	);
 }
 
 function isOutdatedCodeModeExtension(error: unknown): boolean {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@howaboua/pi-ask",
-	"version": "0.0.6",
+	"version": "0.0.8",
 	"description": "Interactive decisions, review triage, and human handoffs for Pi.",
 	"type": "module",
 	"license": "MIT",
@@ -45,7 +45,8 @@
 		]
 	},
 	"peerDependencies": {
-		"@howaboua/pi-codex-conversion": ">=3.0.24",
+		"@howaboua/pi-codex-conversion": ">=3.0.30",
+		"@earendil-works/pi-ai": ">=0.84.3",
 		"@earendil-works/pi-coding-agent": ">=0.84.3",
 		"@earendil-works/pi-tui": ">=0.84.3",
 		"typebox": "*"
@@ -56,10 +57,11 @@
 		}
 	},
 	"devDependencies": {
-		"@howaboua/pi-codex-conversion": "3.0.24",
+		"@howaboua/pi-codex-conversion": "3.0.30",
 		"@biomejs/biome": "^2.5.10",
-		"@earendil-works/pi-coding-agent": "0.84.4",
-		"@earendil-works/pi-tui": "0.84.4",
+		"@earendil-works/pi-ai": "0.85.1",
+		"@earendil-works/pi-coding-agent": "0.85.1",
+		"@earendil-works/pi-tui": "0.85.1",
 		"typebox": "1.3.18",
 		"typescript": "^7.0.2"
 	},