@pi-archimedes/ask 2.8.0 → 2.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/ask",
-  "version": "2.8.0",
+  "version": "2.9.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/danielcherubini/pi-archimedes.git"
@@ -15,7 +15,7 @@
   ],
   "main": "./src/index.ts",
   "dependencies": {
-    "@pi-archimedes/core": "2.8.0"
+    "@pi-archimedes/core": "2.9.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.1.0",
@@ -23,8 +23,8 @@
     "typebox": ">=1.1.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.85.1",
-    "@earendil-works/pi-tui": "^0.85.1",
+    "@earendil-works/pi-coding-agent": "^0.87.0",
+    "@earendil-works/pi-tui": "^0.87.0",
     "typebox": "^1.1.38",
     "typescript": "^6.0.0"
   },

package/src/herdr.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect, vi } from "vitest";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { emitBlocked, blockedLabel } from "./herdr.js";
+
+// ── blockedLabel ────────────────────────────────────────────────────────────
+
+describe("blockedLabel", () => {
+	it("uses the first question, collapsed to a single line", () => {
+		expect(blockedLabel([{ question: "  Which\n\tframework?  " }])).toBe("Which framework?");
+	});
+
+	it("truncates long questions at 80 chars with an ellipsis", () => {
+		const label = blockedLabel([{ question: "a".repeat(120) }]);
+		expect(label).toHaveLength(80);
+		expect(label.endsWith("…")).toBe(true);
+	});
+
+	it("keeps 80-char questions intact", () => {
+		const q = "a".repeat(80);
+		expect(blockedLabel([{ question: q }])).toBe(q);
+	});
+
+	it("falls back to 'question' for a missing or blank first question", () => {
+		expect(blockedLabel([])).toBe("question");
+		expect(blockedLabel([{ question: "   " }])).toBe("question");
+	});
+});
+
+// ── emitBlocked ─────────────────────────────────────────────────────────────
+
+describe("emitBlocked", () => {
+	it("emits 'herdr:blocked' on pi.events with the label only when active", () => {
+		const emit = vi.fn();
+		const pi = { events: { emit } } as unknown as ExtensionAPI;
+
+		emitBlocked(pi, true, "Which?");
+		emitBlocked(pi, false);
+
+		expect(emit).toHaveBeenCalledTimes(2);
+		expect(emit).toHaveBeenNthCalledWith(1, "herdr:blocked", { active: true, label: "Which?" });
+		expect(emit).toHaveBeenNthCalledWith(2, "herdr:blocked", { active: false, label: undefined });
+	});
+});

package/src/herdr.ts

@@ -0,0 +1,34 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Report the ask dialog to herdr's managed extension (herdr-agent-state.ts).
+ *
+ * That extension listens for "herdr:blocked" on pi's SHARED event bus
+ * (`pi.events` — every extension in the process sees it) and refcounts the
+ * blocked state: `active: true` → +1 (message = label), `active: false` → −1.
+ * It is TUI-only and inert unless herdr spawned pi with `HERDR_ENV=1` +
+ * `HERDR_SOCKET_PATH` + `HERDR_PANE_ID`, so when herdr is not active the
+ * event has no live listeners and the emit is a no-op — the same pattern as
+ * the `ASK_REQUEST` bus emit (a notify hook). No env gate is needed here.
+ *
+ * The caller MUST pair every `active: true` with exactly one `active: false`
+ * (try/finally) so the refcount never leaks — an unpaired increment would
+ * leave the pane stuck at "blocked".
+ */
+export function emitBlocked(pi: ExtensionAPI, active: boolean, label?: string): void {
+	pi.events.emit("herdr:blocked", { active, label });
+}
+
+/**
+ * The label herdr shows while the agent is blocked: the first question,
+ * collapsed to one line and truncated (herdr renders it in the pane's
+ * status line). One pair per dialog, not per question — the dialog is one
+ * UI, and the refcount is per pending prompt.
+ */
+export function blockedLabel(questions: Array<{ question: string }>): string {
+	const question = questions[0]?.question;
+	if (!question) return "question";
+	const label = question.replace(/\s+/g, " ").trim();
+	if (label.length === 0) return "question";
+	return label.length > 80 ? `${label.slice(0, 79)}…` : label;
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { registerIpcRelay } from "./ipc-relay.js";
 import { registerAskTool } from "./tool.js";
+export { renderAskCall, renderAskResult } from "./renderer.js";
 
 export function registerAsk(pi: ExtensionAPI) {
 	const unsubscribes: Array<() => void> = [];

package/src/ipc-relay.ts

@@ -4,6 +4,7 @@ import { getBridge } from "@pi-archimedes/core/bridge";
 import { type AskQuestion, type AskSelection } from "./selection.js";
 import { askSingleQuestionWithInlineNote } from "./picker.js";
 import { askQuestionsWithTabs } from "./dialog.js";
+import { emitBlocked, blockedLabel } from "./herdr.js";
 
 export function registerIpcRelay(
 	pi: ExtensionAPI,
@@ -31,7 +32,7 @@ export function registerIpcRelay(
 
 		// Defer to next tick so TUI can process current state
 		await new Promise((resolve) => setImmediate(resolve));
-		await handleAskRequest(data, getCtx);
+		await handleAskRequest(data, getCtx, (active, label) => emitBlocked(pi, active, label));
 	});
 	unsubscribes.push(unsubAskRequest);
 }
@@ -42,6 +43,7 @@ async function handleAskRequest(
 		questions: AskQuestion[];
 	},
 	getCtx: () => ExtensionContext | undefined,
+	reportBlocked: (active: boolean, label?: string) => void,
 ): Promise<void> {
 	const ctx = getCtx();
 	if (!ctx?.ui) return;
@@ -50,6 +52,12 @@ async function handleAskRequest(
 	let cancelled = true;
 	let selections: AskSelection[] = [];
 
+	// Report to herdr's managed extension: the PARENT's TUI is the surface this
+	// subagent's dialog appears on (the child process is headless and its own
+	// herdr extension is inert). Paired in the finally — the existing catch
+	// converts a picker error into a cancelled result, so the dialog always
+	// settles.
+	reportBlocked(true, blockedLabel(questions));
 	try {
 		if (questions.length === 1) {
 			const q = questions[0]!;
@@ -77,6 +85,8 @@ async function handleAskRequest(
 	} catch {
 		cancelled = true;
 		selections = questions.map(() => ({ selectedOptions: [] }));
+	} finally {
+		reportBlocked(false);
 	}
 
 	// Build results matching the request's questions

package/src/renderer.test.ts

@@ -0,0 +1,225 @@
+import { describe, it, expect, vi } from "vitest";
+import { Text } from "@earendil-works/pi-tui";
+import { renderAskCall, renderAskResult } from "./renderer.js";
+
+// Mocking dependencies if necessary
+vi.mock("@pi-archimedes/core/tool-render", () => ({
+	renderToolHeader: (name: string) => `Header:${name}`,
+	renderStatusLabel: (status: string, message: string) => `[${status}] ${message}`,
+}));
+
+function createMockText() {
+	const text = new Text("", 0, 0) as any;
+	text._text = "";
+	text.setText = (t: string) => { text._text = t; };
+	text.getText = () => text._text;
+	return text;
+}
+
+const mockTheme = {
+	fg: (color: string, text: string) => `${color}:${text}`,
+} as any;
+
+describe("renderer", () => {
+	it("renderAskCall renders header", () => {
+		const text = createMockText();
+		renderAskCall({}, mockTheme, { lastComponent: text });
+		expect(text.getText()).toBe("Header:ask");
+	});
+
+	it("renderAskResult with isPartial: true renders waiting", () => {
+		const text = createMockText();
+		renderAskResult({}, { isPartial: true }, mockTheme, { lastComponent: text });
+		expect(text.getText()).toBe("[running] waiting for input...");
+	});
+
+	it("renderAskResult completed single question renders correct selection", () => {
+		const text = createMockText();
+		const result = {
+			details: {
+				results: [{
+					id: "test",
+					question: "q",
+					options: ["A", "B"],
+					multi: false,
+					selectedOptions: ["A"],
+				}]
+			}
+		};
+		renderAskResult(result, {}, mockTheme, { lastComponent: text });
+		expect(text.getText()).toBe("[success] A");
+	});
+
+	it("renderAskResult completed multi-select renders [A, B]", () => {
+		const text = createMockText();
+		const result = {
+			details: {
+				results: [{
+					id: "test",
+					question: "q",
+					options: ["A", "B"],
+					multi: true,
+					selectedOptions: ["A", "B"],
+				}]
+			}
+		};
+		renderAskResult(result, {}, mockTheme, { lastComponent: text });
+		expect(text.getText()).toBe("[success] [A, B]");
+	});
+
+	it("renderAskResult completed custom input renders custom note", () => {
+		const text = createMockText();
+		const result = {
+			details: {
+				results: [{
+					id: "test",
+					question: "q",
+					options: ["A"],
+					multi: false,
+					selectedOptions: [],
+					customInput: "custom note"
+				}]
+			}
+		};
+		renderAskResult(result, {}, mockTheme, { lastComponent: text });
+		expect(text.getText()).toBe("[success] \"custom note\"");
+	});
+
+	it("renderAskResult completed combo choice + custom input renders A + Other", () => {
+		const text = createMockText();
+		const result = {
+			details: {
+				results: [{
+					id: "test",
+					question: "q",
+					options: ["A"],
+					multi: false,
+					selectedOptions: ["A"],
+					customInput: "custom note"
+				}]
+			}
+		};
+		renderAskResult(result, {}, mockTheme, { lastComponent: text });
+		expect(text.getText()).toBe("[success] A + Other: \"custom note\"");
+	});
+
+	it("renderAskResult completed multiple questions renders comma separated", () => {
+		const text = createMockText();
+		const result = {
+			details: {
+				results: [
+					{ id: "auth", question: "q", options: ["A"], multi: false, selectedOptions: ["OAuth"] },
+					{ id: "cache", question: "q", options: ["B"], multi: false, selectedOptions: ["Redis"] }
+				]
+			}
+		};
+		renderAskResult(result, {}, mockTheme, { lastComponent: text });
+		expect(text.getText()).toBe("[success] auth: OAuth, cache: Redis");
+	});
+
+	it("renderAskResult sanitizes multiline and control characters in collapsed status row", () => {
+		const text = createMockText();
+		const result = {
+			details: {
+				results: [{
+					id: "note\n1",
+					question: "q",
+					options: ["Option\r\nLine"],
+					multi: false,
+					selectedOptions: ["Option\r\nLine\x00"],
+					customInput: "Line 1\nLine 2\t\x07extra"
+				}]
+			}
+		};
+		renderAskResult(result, {}, mockTheme, { lastComponent: text });
+		expect(text.getText()).toBe("[success] Option Line + Other: \"Line 1 Line 2 extra\"");
+	});
+
+	it("renderAskResult cancelled renders (cancelled)", () => {
+		const text = createMockText();
+		const result = {
+			content: [{ type: "text", text: "User cancelled the question." }],
+			details: { results: [] }
+		};
+		renderAskResult(result, {}, mockTheme, { lastComponent: text });
+		expect(text.getText()).toBe("[error] (cancelled)");
+	});
+
+	it("renderAskResult error renders failed", () => {
+		const text = createMockText();
+		renderAskResult({}, {}, mockTheme, { lastComponent: text, isError: true });
+		expect(text.getText()).toBe("[error] failed");
+	});
+
+	it("renderAskResult expanded renders clean Q&A breakdown", () => {
+		const text = createMockText();
+		const result = {
+			details: {
+				results: [{
+					id: "test",
+					question: "Question prompt?",
+					options: ["A"],
+					multi: false,
+					selectedOptions: ["A"],
+				}]
+			}
+		};
+		renderAskResult(result, { expanded: true }, mockTheme, { lastComponent: text });
+		expect(text.getText()).toContain("dim:Question prompt?");
+		expect(text.getText()).toContain("success:✓");
+		expect(text.getText()).toContain("toolOutput:A");
+	});
+
+	it("renderAskResult expanded renders cancelled state", () => {
+		const text = createMockText();
+		const result = {
+			content: [{ type: "text", text: "User cancelled the question." }],
+			details: { results: [] }
+		};
+		renderAskResult(result, { expanded: true }, mockTheme, { lastComponent: text });
+		expect(text.getText()).toBe("error:✗ (cancelled)");
+	});
+
+	it("renderAskResult expanded renders error state", () => {
+		const text = createMockText();
+		renderAskResult({}, { expanded: true }, mockTheme, { lastComponent: text, isError: true });
+		expect(text.getText()).toBe("error:failed");
+	});
+
+	it("renderAskResult expanded renders empty results", () => {
+		const text = createMockText();
+		const result = { details: { results: [] } };
+		renderAskResult(result, { expanded: true }, mockTheme, { lastComponent: text });
+		expect(text.getText()).toBe("error:failed");
+	});
+
+	it("renderAskResult legacy details format", () => {
+		const text = createMockText();
+		const result = {
+			details: {
+				id: "test",
+				question: "q",
+			}
+		};
+		renderAskResult(result, {}, mockTheme, { lastComponent: text });
+		expect(text.getText()).toBe("[error] (cancelled)");
+	});
+
+	it("renderAskCall catch fallback", () => {
+		const text = createMockText();
+		const theme = { fg: () => { throw new Error(); } } as any;
+		renderAskCall({}, theme, { lastComponent: text });
+		expect(text.getText()).toBe("Header:ask");
+	});
+
+	it("renderAskResult catch fallback", () => {
+		const text = createMockText();
+		renderAskResult(null as any, {}, { fg: () => { throw new Error(); } } as any, { lastComponent: text });
+		expect(text.getText()).toBe("");
+	});
+
+	it("renderAskResult reuseText fallback", () => {
+		const text = renderAskResult({}, {}, mockTheme, { lastComponent: { something: "else" } });
+		expect(text).toBeInstanceOf(Text);
+	});
+});

package/src/renderer.ts

@@ -0,0 +1,114 @@
+import { Text } from "@earendil-works/pi-tui";
+import type { Component } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { renderToolHeader, renderStatusLabel } from "@pi-archimedes/core/tool-render";
+import { formatSelectionForSummary, type QuestionResult } from "./tool.js";
+
+export type RenderContext = {
+	lastComponent?: Component;
+	isError?: boolean;
+	expanded?: boolean;
+	isPartial?: boolean;
+};
+
+export type RenderOptions = {
+	expanded?: boolean;
+	isPartial?: boolean;
+};
+
+function reuseText(context?: RenderContext): Text {
+	return (context?.lastComponent instanceof Text
+		? context.lastComponent
+		: new Text("", 0, 0)) as Text;
+}
+
+function extractQuestionResults(result: unknown, context?: RenderContext): { results: QuestionResult[]; isCancelled: boolean; isError: boolean; errorMessage: string | undefined } {
+	const r = result as { content?: Array<{ type: string; text?: string }>; details?: { results?: QuestionResult[]; id?: string; question?: string; description?: string; options?: string[]; multi?: boolean; selectedOptions?: string[]; customInput?: string } };
+	
+	let results: QuestionResult[] = [];
+	if (r.details?.results && r.details.results.length > 0) {
+		results = r.details.results;
+	} else if (r.details?.id && r.details?.question) {
+		results = [{
+			id: r.details.id,
+			question: r.details.question,
+			description: r.details.description,
+			options: r.details.options ?? [],
+			multi: Boolean(r.details.multi),
+			selectedOptions: r.details.selectedOptions ?? [],
+			customInput: r.details.customInput,
+		}];
+	}
+
+	const isCancelled = (results.length > 0 && results.every(res => res.selectedOptions.length === 0 && !res.customInput)) || 
+						(r.content?.some(c => c.text?.match(/user cancelled the question/i)) ?? false);
+	
+	const isError = context?.isError === true || results.length === 0;
+	const errorMessage = isError ? (r.content?.[0]?.text ?? "failed") : undefined;
+
+	return { results, isCancelled, isError, errorMessage };
+}
+
+export function formatExpandedBreakdown(results: QuestionResult[], isCancelled: boolean, theme: Theme): string {
+	if (isCancelled) return theme.fg("error", "✗ (cancelled)");
+	if (results.length === 0) return theme.fg("muted", "(no details)");
+
+	return results.map(q => 
+		`${theme.fg("dim", q.question)}\n  ${theme.fg("success", "✓")} ${theme.fg("toolOutput", formatSelectionForSummary(q))}`
+	).join("\n\n");
+}
+
+function sanitizeForStatusRow(value: string): string {
+	return value
+		.replace(/[\r\n\t]/g, " ")
+		.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, "")
+		.replace(/\s{2,}/g, " ")
+		.trim();
+}
+
+export function renderAskCall(args: unknown, theme: Theme, context?: unknown): Text {
+	const text = reuseText(context as RenderContext | undefined);
+	try {
+		text.setText(renderToolHeader("ask", undefined, theme));
+	} catch {
+		text.setText("ask");
+	}
+	return text;
+}
+
+export function renderAskResult(result: unknown, options: RenderOptions = {}, theme: Theme, context?: unknown): Text {
+	const text = reuseText(context as RenderContext | undefined);
+	const ctx = context as RenderContext | undefined;
+	
+	try {
+		const expanded = options?.expanded ?? ctx?.expanded ?? false;
+		const isPartial = options?.isPartial ?? ctx?.isPartial ?? false;
+		const { results, isCancelled, isError, errorMessage } = extractQuestionResults(result, ctx);
+		if (expanded) {
+			if (isCancelled) {
+				text.setText(formatExpandedBreakdown(results, true, theme));
+			} else if (isError) {
+				text.setText(theme.fg("error", errorMessage ?? "failed"));
+			} else {
+				text.setText(formatExpandedBreakdown(results, false, theme));
+			}
+		} else {
+			if (isPartial) text.setText(renderStatusLabel("running", "waiting for input...", theme));
+			else if (isCancelled) text.setText(renderStatusLabel("error", "(cancelled)", theme));
+			else if (isError) text.setText(renderStatusLabel("error", sanitizeForStatusRow(errorMessage ?? "failed"), theme));
+			else if (results.length === 1) {
+				const first = results[0];
+				const label = sanitizeForStatusRow(first ? formatSelectionForSummary(first) : "(unknown)");
+				text.setText(renderStatusLabel("success", label, theme));
+			} else if (results.length > 1) {
+				const summary = sanitizeForStatusRow(results.map((r) => `${r.id}: ${formatSelectionForSummary(r)}`).join(", "));
+				text.setText(renderStatusLabel("success", summary, theme));
+			} else {
+				text.setText(renderStatusLabel("error", "failed", theme));
+			}
+		}
+	} catch {
+		text.setText("");
+	}
+	return text;
+}

package/src/tool.test.ts

@@ -8,6 +8,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { Events } from "@pi-archimedes/core/bus";
 import { registerAskTool } from "./tool.js";
 import { registerIpcRelay } from "./ipc-relay.js";
+import { renderAskCall, renderAskResult } from "./renderer.js";
 
 // ── Mocks ────────────────────────────────────────────────────────────────────
 //
@@ -17,7 +18,7 @@ import { registerIpcRelay } from "./ipc-relay.js";
 // Bridge: a mutable state object — `active` flips per test, `ask` is a vi.fn.
 // Picker/dialog: mocked so the TUI branch never touches the real TUI.
 
-const { busState, bridgeState } = vi.hoisted(() => {
+const { busState, bridgeState, eventsState } = vi.hoisted(() => {
 	const listeners: Record<string, Array<(p: unknown) => void>> = {};
 	const emit = vi.fn((event: string, payload: unknown) => {
 		for (const fn of listeners[event] ?? []) {
@@ -44,6 +45,7 @@ const { busState, bridgeState } = vi.hoisted(() => {
 			password: vi.fn(),
 			state: vi.fn(() => "idle"),
 		},
+		eventsState: { emit: vi.fn() }, // pi.events — the shared extension event bus
 	};
 });
 
@@ -77,9 +79,14 @@ function captureTool(): {
 		onUpdate: unknown,
 		ctx: unknown,
 	) => Promise<{ content: Array<{ type: string; text: string }>; details: unknown }>;
+	renderCall?: unknown;
+	renderResult?: unknown;
 } {
 	const registered: Array<Record<string, unknown>> = [];
-	registerAskTool({ registerTool: (t: Record<string, unknown>) => registered.push(t) } as unknown as ExtensionAPI);
+	registerAskTool({
+		registerTool: (t: Record<string, unknown>) => registered.push(t),
+		events: eventsState,
+	} as unknown as ExtensionAPI);
 	return registered[0] as ReturnType<typeof captureTool>;
 }
 
@@ -103,6 +110,13 @@ function emitted(event: string): Record<string, unknown>[] {
 		.map((c) => c[1]!) as Record<string, unknown>[];
 }
 
+/** The recorded `pi.events` "herdr:blocked" payloads, in order. */
+function herdrEmits(): Array<{ active: boolean; label?: string }> {
+	return eventsState.emit.mock.calls
+		.filter((c) => c[0] === "herdr:blocked")
+		.map((c) => c[1]!) as Array<{ active: boolean; label?: string }>;
+}
+
 // Relay subscriptions are tracked file-wide and torn down in afterEach (not at
 // the end of each test body) so a failing assertion cannot leak a live relay
 // handler into the next test (double registration → double ASK_RESPONSE).
@@ -114,6 +128,7 @@ afterEach(() => {
 
 beforeEach(() => {
 	busState.emit.mockClear();
+	eventsState.emit.mockClear();
 	bridgeState.active = false;
 	bridgeState.ask.mockReset();
 	vi.mocked(askSingleQuestionWithInlineNote).mockReset();
@@ -122,6 +137,14 @@ beforeEach(() => {
 
 // ── Bridge branch (checked first) ────────────────────────────────────────────
 
+describe("tool registration", () => {
+	it("registers the correct render functions", () => {
+		const tool = captureTool();
+		expect(tool.renderCall).toBe(renderAskCall);
+		expect(tool.renderResult).toBe(renderAskResult);
+	});
+});
+
 describe("bridge branch", () => {
 	it("emits ASK_REQUEST (main) with toolCallId, then a paired ASK_RESPONSE, and returns the built results", async () => {
 		bridgeState.active = true;
@@ -343,6 +366,104 @@ describe("TUI branch (bridge inactive, has UI)", () => {
 
 		expect(result.content[0]!.text).toBe("Error: questions must not be empty");
 		expect(busState.emit).not.toHaveBeenCalled();
+		// No dialog shown → no herdr pairing either
+		expect(herdrEmits()).toEqual([]);
+	});
+});
+
+// ── herdr pairing (pi.events 'herdr:blocked') ────────────────────────────
+//
+// herdr's managed extension refcounts the blocked state off this event
+// (+1 on active:true, −1 on active:false; TUI-only). The tool must pair
+// every active:true with exactly one active:false — on answer, cancel,
+// AND error — or the pane is stuck at "blocked".
+
+describe("herdr pairing (TUI)", () => {
+	it("single question, answered: active:true (label = the question) then active:false, in order", async () => {
+		bridgeState.active = false;
+		vi.mocked(askSingleQuestionWithInlineNote).mockResolvedValue({ selectedOptions: ["A"] });
+
+		const tool = captureTool();
+		await tool.execute("tool-7", makeParams(), undefined, undefined, { hasUI: true, ui: {} });
+
+		expect(herdrEmits()).toEqual([
+			{ active: true, label: "Which option?" },
+			{ active: false, label: undefined },
+		]);
+	});
+
+	it("single question, cancelled (empty selection): still paired", async () => {
+		bridgeState.active = false;
+		vi.mocked(askSingleQuestionWithInlineNote).mockResolvedValue({ selectedOptions: [] });
+
+		const tool = captureTool();
+		const result = await tool.execute("tool-8", makeParams(), undefined, undefined, { hasUI: true, ui: {} });
+
+		expect(result.content[0]!.text).toContain("(cancelled)");
+		expect(herdrEmits()).toEqual([
+			{ active: true, label: "Which option?" },
+			{ active: false, label: undefined },
+		]);
+	});
+
+	it("picker error: active:false still emitted (finally) and the error propagates", async () => {
+		bridgeState.active = false;
+		vi.mocked(askSingleQuestionWithInlineNote).mockRejectedValue(new Error("ui crashed"));
+
+		const tool = captureTool();
+		await expect(tool.execute("tool-9", makeParams(), undefined, undefined, { hasUI: true, ui: {} })).rejects.toThrow("ui crashed");
+
+		expect(herdrEmits()).toEqual([
+			{ active: true, label: "Which option?" },
+			{ active: false, label: undefined },
+		]);
+	});
+
+	it("multi question: ONE pair, label = the first question", async () => {
+		bridgeState.active = false;
+		vi.mocked(askQuestionsWithTabs).mockResolvedValue({
+			cancelled: false,
+			selections: [{ selectedOptions: ["A"] }, { selectedOptions: ["B"] }],
+		});
+
+		const tool = captureTool();
+		await tool.execute(
+			"tool-10",
+			{
+				questions: [
+					{ id: "q1", question: "First?", options: [{ label: "A" }] },
+					{ id: "q2", question: "Second?", options: [{ label: "B" }] },
+				],
+			},
+			undefined,
+			undefined,
+			{ hasUI: true, ui: {} },
+		);
+
+		expect(herdrEmits()).toEqual([
+			{ active: true, label: "First?" },
+			{ active: false, label: undefined },
+		]);
+	});
+
+	it("bridge path: NO herdr emit (non-TUI — herdr's handler is a no-op there)", async () => {
+		bridgeState.active = true;
+		bridgeState.ask.mockResolvedValue({ cancelled: false, results: [{ id: "q1", selectedOptions: ["A"] }] });
+
+		const tool = captureTool();
+		await tool.execute("tool-11", makeParams(), undefined, undefined, { hasUI: true, ui: {} });
+
+		expect(herdrEmits()).toEqual([]);
+	});
+
+	it("headless path: NO herdr emit (the child is non-TUI; the parent's relay reports it)", async () => {
+		bridgeState.active = false;
+		delete process.env.PI_SUBAGENT_SOCKET;
+
+		const tool = captureTool();
+		await tool.execute("tool-12", makeParams(), undefined, undefined, { hasUI: false });
+
+		expect(herdrEmits()).toEqual([]);
 	});
 });
 
@@ -352,7 +473,7 @@ describe("ipc-relay", () => {
 	it("bridge active: a subagent ASK_REQUEST is NOT consumed (no picker, no ASK_RESPONSE)", async () => {
 		bridgeState.active = true;
 		const unsubscribes: Array<() => void> = [];
-		registerIpcRelay({} as unknown as ExtensionAPI, () => ({ ui: {} } as unknown as ExtensionContext), unsubscribes);
+		registerIpcRelay({ events: eventsState } as unknown as ExtensionAPI, () => ({ ui: {} } as unknown as ExtensionContext), unsubscribes);
 		relayUnsubs.push(...unsubscribes);
 
 		busState.emit(Events.ASK_REQUEST, {
@@ -366,13 +487,15 @@ describe("ipc-relay", () => {
 		expect(vi.mocked(askSingleQuestionWithInlineNote)).not.toHaveBeenCalled();
 		expect(vi.mocked(askQuestionsWithTabs)).not.toHaveBeenCalled();
 		expect(emitted(Events.ASK_RESPONSE).length).toBe(0);
+		// Not consumed → no dialog shown → no herdr pairing
+		expect(herdrEmits()).toEqual([]);
 	});
 
 	it("bridge inactive: a subagent ASK_REQUEST is consumed and answered via ASK_RESPONSE (existing behavior)", async () => {
 		bridgeState.active = false;
 		vi.mocked(askSingleQuestionWithInlineNote).mockResolvedValue({ selectedOptions: ["A"] });
 		const unsubscribes: Array<() => void> = [];
-		registerIpcRelay({} as unknown as ExtensionAPI, () => ({ ui: {} } as unknown as ExtensionContext), unsubscribes);
+		registerIpcRelay({ events: eventsState } as unknown as ExtensionAPI, () => ({ ui: {} } as unknown as ExtensionContext), unsubscribes);
 		relayUnsubs.push(...unsubscribes);
 
 		busState.emit(Events.ASK_REQUEST, {
@@ -389,4 +512,53 @@ describe("ipc-relay", () => {
 		expect(resp.cancelled).toBe(false);
 		expect(resp.results).toEqual([{ id: "q1", selectedOptions: ["A"], customInput: undefined }]);
 	});
+
+	it("bridge inactive: the parent's dialog pairs a herdr blocked/unblocked (label = the subagent's question)", async () => {
+		bridgeState.active = false;
+		vi.mocked(askSingleQuestionWithInlineNote).mockResolvedValue({ selectedOptions: ["A"] });
+		const unsubscribes: Array<() => void> = [];
+		registerIpcRelay({ events: eventsState } as unknown as ExtensionAPI, () => ({ ui: {} } as unknown as ExtensionContext), unsubscribes);
+		relayUnsubs.push(...unsubscribes);
+
+		busState.emit(Events.ASK_REQUEST, {
+			source: "subagent:x",
+			requestId: "relay-3",
+			questions: [{ id: "q1", question: "Which?", options: [{ label: "A" }] }],
+		});
+		await vi.waitFor(() => {
+			expect(emitted(Events.ASK_RESPONSE).length).toBe(1);
+		});
+
+		// The PARENT's TUI is the surface the subagent's dialog appears on — the
+		// child process is headless and its own herdr extension is inert, so the
+		// pairing happens here, in the parent.
+		expect(herdrEmits()).toEqual([
+			{ active: true, label: "Which?" },
+			{ active: false, label: undefined },
+		]);
+	});
+
+	it("bridge inactive, picker error: the herdr pairing still settles (the catch converts it to a cancelled response)", async () => {
+		bridgeState.active = false;
+		vi.mocked(askSingleQuestionWithInlineNote).mockRejectedValue(new Error("ui crashed"));
+		const unsubscribes: Array<() => void> = [];
+		registerIpcRelay({ events: eventsState } as unknown as ExtensionAPI, () => ({ ui: {} } as unknown as ExtensionContext), unsubscribes);
+		relayUnsubs.push(...unsubscribes);
+
+		busState.emit(Events.ASK_REQUEST, {
+			source: "subagent:x",
+			requestId: "relay-4",
+			questions: [{ id: "q1", question: "Which?", options: [{ label: "A" }] }],
+		});
+		await vi.waitFor(() => {
+			expect(emitted(Events.ASK_RESPONSE).length).toBe(1);
+		});
+
+		const resp = emitted(Events.ASK_RESPONSE)[0]!;
+		expect(resp.cancelled).toBe(true);
+		expect(herdrEmits()).toEqual([
+			{ active: true, label: "Which?" },
+			{ active: false, label: undefined },
+		]);
+	});
 });

package/src/tool.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AgentToolResult, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 import { getBus, Events } from "@pi-archimedes/core/bus";
 import { getBridge } from "@pi-archimedes/core/bridge";
@@ -7,6 +7,8 @@ import { randomUUID } from "node:crypto";
 import { OTHER_OPTION, type AskQuestion } from "./selection.js";
 import { askSingleQuestionWithInlineNote } from "./picker.js";
 import { askQuestionsWithTabs } from "./dialog.js";
+import { renderAskCall, renderAskResult } from "./renderer.js";
+import { emitBlocked, blockedLabel } from "./herdr.js";
 
 // ── Schemas ──────────────────────────────────────────────────────────────────
 
@@ -108,7 +110,7 @@ function toSessionSafeQuestionResult(result: QuestionResult): QuestionResult {
 	};
 }
 
-function formatSelectionForSummary(result: QuestionResult): string {
+export function formatSelectionForSummary(result: QuestionResult): string {
 	const hasSelectedOptions = result.selectedOptions.length > 0;
 	const hasCustomInput = Boolean(result.customInput);
 
@@ -228,6 +230,8 @@ export function registerAskTool(pi: ExtensionAPI): void {
 		label: "Ask",
 		description: ASK_TOOL_DESCRIPTION,
 		parameters: AskParamsSchema,
+		renderCall: renderAskCall,
+		renderResult: renderAskResult,
 
 		async execute(_toolCallId, params: AskParams, _signal, _onUpdate, ctx) {
 			// Bridge mode (checked first): the root's Client request is sent by
@@ -361,62 +365,84 @@ export function registerAskTool(pi: ExtensionAPI): void {
 			// Emit bus event so notify (if installed) can schedule a desktop notification
 			getBus().emit(Events.ASK_REQUEST, { source: "main", requestId: randomUUID(), questions: params.questions, toolCallId: _toolCallId });
 
-			if (params.questions.length === 1) {
-				const q = params.questions[0]!;
-				const selection = q.multi
-					? (await askQuestionsWithTabs(ctx.ui, [q as AskQuestion])).selections[0] ?? { selectedOptions: [] }
-					: await askSingleQuestionWithInlineNote(ctx.ui, q as AskQuestion);
-				const optionLabels = q.options.map((option) => option.label);
-				const desc = q.description && q.description.trim().length > 0 ? q.description : undefined;
-
-				const result: QuestionResult = {
-					id: q.id,
-					question: q.question,
-					description: desc,
-					options: optionLabels,
-					multi: q.multi ?? false,
-					selectedOptions: selection.selectedOptions,
-					customInput: selection.customInput,
-				};
+			// Report to herdr's managed extension (inert unless herdr spawned pi — the
+			// event is a no-op otherwise). One pair per dialog; the finally pairs it on
+			// answer, cancel, AND error so the refcount never leaks. (The bridge and
+			// headless paths above are non-TUI — herdr's handler is TUI-only, so they
+			// are intentionally not reported.)
+			emitBlocked(pi, true, blockedLabel(params.questions));
+			try {
+				return await executeTuiAsk(params, ctx);
+			} finally {
+				emitBlocked(pi, false);
+			}
+		},
+	});
+}
 
-				const details: AskToolDetails = {
-					id: q.id,
-					question: q.question,
-					description: desc,
-					options: optionLabels,
-					multi: q.multi ?? false,
-					selectedOptions: selection.selectedOptions,
-					customInput: selection.customInput,
-					results: [result],
-				};
+/**
+ * Show the questions in the TUI (picker for a single non-multi question, tabs
+ * dialog otherwise) and build the tool result. The caller wraps this in the
+ * herdr blocked pairing (emitBlocked true before / false in finally).
+ */
+async function executeTuiAsk(
+	params: AskParams,
+	ctx: ExtensionContext,
+): Promise<AgentToolResult<AskToolDetails>> {
+	if (params.questions.length === 1) {
+		const q = params.questions[0]!;
+		const selection = q.multi
+			? (await askQuestionsWithTabs(ctx.ui, [q as AskQuestion])).selections[0] ?? { selectedOptions: [] }
+			: await askSingleQuestionWithInlineNote(ctx.ui, q as AskQuestion);
+		const optionLabels = q.options.map((option) => option.label);
+		const desc = q.description && q.description.trim().length > 0 ? q.description : undefined;
+
+		const result: QuestionResult = {
+			id: q.id,
+			question: q.question,
+			description: desc,
+			options: optionLabels,
+			multi: q.multi ?? false,
+			selectedOptions: selection.selectedOptions,
+			customInput: selection.customInput,
+		};
 
-				return {
-					content: [{ type: "text", text: buildAskSessionContent([result]) }],
-					details,
-				};
-			}
+		const details: AskToolDetails = {
+			id: q.id,
+			question: q.question,
+			description: desc,
+			options: optionLabels,
+			multi: q.multi ?? false,
+			selectedOptions: selection.selectedOptions,
+			customInput: selection.customInput,
+			results: [result],
+		};
 
-			const results: QuestionResult[] = [];
-			const tabResult = await askQuestionsWithTabs(ctx.ui, params.questions as AskQuestion[]);
-			for (let i = 0; i < params.questions.length; i++) {
-				const q = params.questions[i]!;
-				const selection = tabResult.selections[i] ?? { selectedOptions: [] };
-				const desc = q.description && q.description.trim().length > 0 ? q.description : undefined;
-				results.push({
-					id: q.id,
-					question: q.question,
-					description: desc,
-					options: q.options.map((option) => option.label),
-					multi: q.multi ?? false,
-					selectedOptions: selection.selectedOptions,
-					customInput: selection.customInput,
-				});
-			}
+		return {
+			content: [{ type: "text", text: buildAskSessionContent([result]) }],
+			details,
+		};
+	}
 
-			return {
-				content: [{ type: "text", text: buildAskSessionContent(results) }],
-				details: { results, customInput: undefined, description: undefined } satisfies AskToolDetails,
-			};
-		},
-	});
+	const results: QuestionResult[] = [];
+	const tabResult = await askQuestionsWithTabs(ctx.ui, params.questions as AskQuestion[]);
+	for (let i = 0; i < params.questions.length; i++) {
+		const q = params.questions[i]!;
+		const selection = tabResult.selections[i] ?? { selectedOptions: [] };
+		const desc = q.description && q.description.trim().length > 0 ? q.description : undefined;
+		results.push({
+			id: q.id,
+			question: q.question,
+			description: desc,
+			options: q.options.map((option) => option.label),
+			multi: q.multi ?? false,
+			selectedOptions: selection.selectedOptions,
+			customInput: selection.customInput,
+		});
+	}
+
+	return {
+		content: [{ type: "text", text: buildAskSessionContent(results) }],
+		details: { results, customInput: undefined, description: undefined } satisfies AskToolDetails,
+	};
 }