@pi-archimedes/ask 2.7.3 → 2.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/ask",
-  "version": "2.7.3",
+  "version": "2.9.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/danielcherubini/pi-archimedes.git"
@@ -15,7 +15,7 @@
   ],
   "main": "./src/index.ts",
   "dependencies": {
-    "@pi-archimedes/core": "2.7.3"
+    "@pi-archimedes/core": "2.9.0"
   },
   "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

@@ -1,8 +1,10 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getBus, Events } from "@pi-archimedes/core/bus";
+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,
@@ -19,11 +21,18 @@ export function registerIpcRelay(
 		// Skip main agent — it shows its own UI in the tool handler
 		if (data.source === "main") return;
 
+		// Bridge mode: the bridge forwards subagent asks to the Client — the
+		// relay must stay inert (per-message gate: registerIpcRelay runs at
+		// extension load when bridge.active is false in every mode, and ctx.mode
+		// is only captured at the first session_start, so a registration-time
+		// gate would silently reintroduce the double-consumption bug).
+		if (getBridge().active) return;
+
 		if (!data.questions || data.questions.length === 0) return;
 
 		// 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);
 }
@@ -34,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;
@@ -42,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]!;
@@ -69,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

@@ -0,0 +1,564 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as fs from "node:fs";
+import { randomUUID } from "node:crypto";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+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 ────────────────────────────────────────────────────────────────────
+//
+// Bus: an in-memory pub/sub whose `emit` is a spy (records + dispatches), so
+// tests can assert on emitted payloads while still letting the relay's
+// `on(ASK_REQUEST)` subscription receive them.
+// 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, 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] ?? []) {
+			Promise.resolve(fn(payload)).catch(() => {
+				/* listener errors are not under test here */
+			});
+		}
+	});
+	const on = (event: string, fn: (p: unknown) => void) => {
+		(listeners[event] ??= []).push(fn);
+		return () => {
+			const subs = listeners[event] ?? [];
+			const i = subs.indexOf(fn);
+			if (i !== -1) subs.splice(i, 1);
+		};
+	};
+	const ask = vi.fn();
+	return {
+		busState: { listeners, emit, on },
+		bridgeState: {
+			active: false,
+			ask,
+			confirm: vi.fn(),
+			password: vi.fn(),
+			state: vi.fn(() => "idle"),
+		},
+		eventsState: { emit: vi.fn() }, // pi.events — the shared extension event bus
+	};
+});
+
+vi.mock("@pi-archimedes/core/bus", async (importOriginal) => {
+	const actual = await importOriginal() as typeof import("@pi-archimedes/core/bus");
+	return { ...actual, getBus: () => ({ emit: busState.emit, on: busState.on }) };
+});
+
+vi.mock("@pi-archimedes/core/bridge", () => ({
+	getBridge: () => bridgeState,
+}));
+
+vi.mock("./picker.js", () => ({
+	askSingleQuestionWithInlineNote: vi.fn(),
+}));
+
+vi.mock("./dialog.js", () => ({
+	askQuestionsWithTabs: vi.fn(),
+}));
+
+const { askSingleQuestionWithInlineNote } = await import("./picker.js");
+const { askQuestionsWithTabs } = await import("./dialog.js");
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function captureTool(): {
+	execute: (
+		id: string,
+		params: { questions: unknown[] },
+		signal: unknown,
+		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),
+		events: eventsState,
+	} as unknown as ExtensionAPI);
+	return registered[0] as ReturnType<typeof captureTool>;
+}
+
+function makeParams(): { questions: unknown[] } {
+	return {
+		questions: [
+			{
+				id: "q1",
+				question: "Which option?",
+				description: "Some context",
+				options: [{ label: "A" }, { label: "B" }],
+			},
+		],
+	};
+}
+
+/** The payloads of the recorded `emit` calls for the given event. */
+function emitted(event: string): Record<string, unknown>[] {
+	return busState.emit.mock.calls
+		.filter((c) => c[0] === event)
+		.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).
+const relayUnsubs: Array<() => void> = [];
+
+afterEach(() => {
+	relayUnsubs.splice(0).forEach((u) => u());
+});
+
+beforeEach(() => {
+	busState.emit.mockClear();
+	eventsState.emit.mockClear();
+	bridgeState.active = false;
+	bridgeState.ask.mockReset();
+	vi.mocked(askSingleQuestionWithInlineNote).mockReset();
+	vi.mocked(askQuestionsWithTabs).mockReset();
+});
+
+// ── 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;
+		bridgeState.ask.mockResolvedValue({
+			cancelled: false,
+			results: [{ id: "q1", selectedOptions: ["B"], customInput: "extra" }],
+		});
+
+		const tool = captureTool();
+		const result = await tool.execute("tool-1", makeParams(), undefined, undefined, { hasUI: true, ui: {} });
+
+		// bridge.ask was called with the params + toolCallId + the turn's AbortSignal
+		// (undefined here — the test passes no signal)
+		expect(bridgeState.ask).toHaveBeenCalledTimes(1);
+		expect(bridgeState.ask).toHaveBeenCalledWith({ questions: makeParams().questions }, "tool-1", undefined);
+
+		// ASK_REQUEST (main) with toolCallId
+		expect(emitted(Events.ASK_REQUEST).length).toBe(1);
+		const req = emitted(Events.ASK_REQUEST)[0]!;
+		expect(req.source).toBe("main");
+		expect(req.toolCallId).toBe("tool-1");
+		expect(req.questions).toEqual(makeParams().questions);
+		expect(typeof req.requestId).toBe("string");
+
+		// Paired ASK_RESPONSE (same requestId, the bridge's response verbatim)
+		expect(emitted(Events.ASK_RESPONSE).length).toBe(1);
+		const resp = emitted(Events.ASK_RESPONSE)[0]!;
+		expect(resp.requestId).toBe(req.requestId);
+		expect(resp.cancelled).toBe(false);
+		expect(resp.results).toEqual([{ id: "q1", selectedOptions: ["B"], customInput: "extra" }]);
+
+		// Built results in the returned content
+		expect(result.content[0]!.text).toContain("q1: B + Other: \"extra\"");
+	});
+
+	it("a rejected bridge.ask() still emits the paired ASK_RESPONSE (cancelled) and returns the cancel text", async () => {
+		bridgeState.active = true;
+		bridgeState.ask.mockRejectedValue(new Error("bridge is not active"));
+
+		const tool = captureTool();
+		const result = await tool.execute("tool-1", makeParams(), undefined, undefined, { hasUI: true, ui: {} });
+
+		expect(emitted(Events.ASK_REQUEST).length).toBe(1);
+		expect(emitted(Events.ASK_RESPONSE).length).toBe(1);
+		const resp = emitted(Events.ASK_RESPONSE)[0]!;
+		expect(resp.requestId).toBe(emitted(Events.ASK_REQUEST)[0]!.requestId);
+		expect(resp.cancelled).toBe(true);
+		expect(resp.results).toEqual([{ id: "q1", selectedOptions: [] }]);
+		expect(result.content[0]!.text).toBe("User cancelled the question.");
+	});
+
+	it("a pre-aborted signal → cancelled content + paired cancelled ASK_RESPONSE", async () => {
+		bridgeState.active = true;
+		// Simulate the cancel-rejection: when the turn's signal is already aborted,
+		// bridge.ask() calls handle.cancel() directly (the abort event never fires),
+		// which settles the promise via the socket-close handler → a rejection.
+		bridgeState.ask.mockRejectedValue(new Error("bridge channel closed before response"));
+
+		const controller = new AbortController();
+		controller.abort(); // pre-aborted BEFORE execute() is invoked
+
+		const tool = captureTool();
+		const result = await tool.execute("tool-6", makeParams(), controller.signal, undefined, { hasUI: true, ui: {} });
+
+		// bridge.ask was called with the pre-aborted signal (3rd arg)
+		expect(bridgeState.ask).toHaveBeenCalledTimes(1);
+		expect(bridgeState.ask).toHaveBeenCalledWith(makeParams(), "tool-6", controller.signal);
+
+		// Paired cancelled ASK_RESPONSE (the tool's catch converts the
+		// cancel-rejection into a cancelled response so the refcount stays balanced)
+		expect(emitted(Events.ASK_REQUEST).length).toBe(1);
+		expect(emitted(Events.ASK_RESPONSE).length).toBe(1);
+		const resp = emitted(Events.ASK_RESPONSE)[0]!;
+		expect(resp.requestId).toBe(emitted(Events.ASK_REQUEST)[0]!.requestId);
+		expect(resp.cancelled).toBe(true);
+		expect(resp.results).toEqual([{ id: "q1", selectedOptions: [] }]);
+
+		// Cancelled content
+		expect(result.content[0]!.text).toBe("User cancelled the question.");
+	});
+});
+
+// ── Child (headless) branch — unchanged except toolCallId on the socket payload ──
+
+describe("child branch (bridge inactive, no UI)", () => {
+	it("writes ask_request with toolCallId to PI_SUBAGENT_SOCKET and returns the response results", async () => {
+		bridgeState.active = false;
+		const socketPath = path.join(os.tmpdir(), `ask-tool-test-${randomUUID()}.sock`);
+		const received: Array<Record<string, unknown>> = [];
+		const server = net.createServer((socket) => {
+			let buffer = "";
+			socket.on("data", (chunk: Buffer) => {
+				buffer += chunk.toString("utf-8");
+				const lines = buffer.split("\n");
+				buffer = lines.pop() ?? "";
+				for (const line of lines) {
+					const trimmed = line.trim();
+					if (!trimmed) continue;
+					try {
+						const msg = JSON.parse(trimmed) as Record<string, unknown>;
+						if (msg.type === "ask_request") {
+							received.push(msg);
+							socket.write(
+								JSON.stringify({
+									type: "ask_response",
+									requestId: msg.requestId,
+									cancelled: false,
+									results: [{ id: "q1", selectedOptions: ["A"], customInput: "from-parent" }],
+								}) + "\n",
+							);
+						}
+					} catch {
+						/* malformed — ignore */
+					}
+				}
+			});
+			socket.on("error", () => {
+				/* connection dropped */
+			});
+		});
+		await new Promise<void>((resolve) => server.listen(socketPath, resolve));
+		process.env.PI_SUBAGENT_SOCKET = socketPath;
+
+		try {
+			const tool = captureTool();
+			const result = await tool.execute("tool-2", makeParams(), undefined, undefined, { hasUI: false });
+
+			expect(received.length).toBe(1);
+			expect(received[0]!.type).toBe("ask_request");
+			expect(received[0]!.toolCallId).toBe("tool-2");
+			expect(received[0]!.questions).toEqual(makeParams().questions);
+			expect(typeof received[0]!.requestId).toBe("string");
+
+			// The response results are built into the returned content
+			expect(result.content[0]!.text).toContain("q1: A + Other: \"from-parent\"");
+		} finally {
+			delete process.env.PI_SUBAGENT_SOCKET;
+			server.close();
+			try {
+				fs.unlinkSync(socketPath);
+			} catch {
+				/* already gone */
+			}
+		}
+	});
+
+	it("no PI_SUBAGENT_SOCKET → immediate cancelled response (unchanged behavior)", async () => {
+		bridgeState.active = false;
+		delete process.env.PI_SUBAGENT_SOCKET;
+
+		const tool = captureTool();
+		const result = await tool.execute("tool-2", makeParams(), undefined, undefined, { hasUI: false });
+
+		expect(result.content[0]!.text).toBe("User cancelled the question.");
+		// The child branch does not emit on the bus
+		expect(busState.emit).not.toHaveBeenCalled();
+	});
+});
+
+// ── TUI branch — unchanged except toolCallId on the ASK_REQUEST emit ────────
+
+describe("TUI branch (bridge inactive, has UI)", () => {
+	it("emits ASK_REQUEST (main) with toolCallId and does NOT emit ASK_RESPONSE", async () => {
+		bridgeState.active = false;
+		vi.mocked(askSingleQuestionWithInlineNote).mockResolvedValue({ selectedOptions: ["A"] });
+
+		const tool = captureTool();
+		const result = await tool.execute("tool-3", makeParams(), undefined, undefined, { hasUI: true, ui: {} });
+
+		expect(emitted(Events.ASK_REQUEST).length).toBe(1);
+		const req = emitted(Events.ASK_REQUEST)[0]!;
+		expect(req.source).toBe("main");
+		expect(req.toolCallId).toBe("tool-3");
+		expect(typeof req.requestId).toBe("string");
+
+		// The TUI path settles the picker inline — no ASK_RESPONSE on the bus
+		expect(emitted(Events.ASK_RESPONSE).length).toBe(0);
+
+		expect(vi.mocked(askSingleQuestionWithInlineNote)).toHaveBeenCalledTimes(1);
+		expect(result.content[0]!.text).toContain("q1: A");
+	});
+
+	it("multi-question TUI path routes through the tabs dialog (unchanged)", async () => {
+		bridgeState.active = false;
+		vi.mocked(askQuestionsWithTabs).mockResolvedValue({
+			cancelled: false,
+			selections: [
+				{ selectedOptions: ["A"] },
+				{ selectedOptions: ["B"], customInput: "note" },
+			],
+		});
+
+		const tool = captureTool();
+		const result = await tool.execute(
+			"tool-4",
+			{
+				questions: [
+					{ id: "q1", question: "First?", options: [{ label: "A" }, { label: "B" }] },
+					{ id: "q2", question: "Second?", multi: true, options: [{ label: "A" }, { label: "B" }] },
+				],
+			},
+			undefined,
+			undefined,
+			{ hasUI: true, ui: {} },
+		);
+
+		expect(vi.mocked(askQuestionsWithTabs)).toHaveBeenCalledTimes(1);
+		expect(emitted(Events.ASK_REQUEST).length).toBe(1);
+		expect(emitted(Events.ASK_RESPONSE).length).toBe(0);
+		expect(result.content[0]!.text).toContain("q1: A");
+		expect(result.content[0]!.text).toContain("q2: [B] + Other: \"note\"");
+	});
+
+	it("the empty-questions guard still returns the error text (before any bus emit)", async () => {
+		bridgeState.active = false;
+
+		const tool = captureTool();
+		const result = await tool.execute("tool-5", { questions: [] }, undefined, undefined, { hasUI: true, 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([]);
+	});
+});
+
+// ── ipc-relay: per-message bridge gate ───────────────────────────────────────
+
+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({ 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-1",
+			questions: [{ id: "q1", question: "Which?", options: [{ label: "A" }] }],
+		});
+		// The relay defers via setImmediate before handling — give it a moment
+		await new Promise((resolve) => setTimeout(resolve, 50));
+
+		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({ 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-2",
+			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.requestId).toBe("relay-2");
+		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,11 +1,14 @@
-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";
 import { connect } from "node:net";
 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 ──────────────────────────────────────────────────────────────────
 
@@ -107,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);
 
@@ -183,6 +186,28 @@ export function buildAskSessionContent(results: QuestionResult[]): string {
 	return `User answers:\n${summaryLines}\n\nAnswer context:\n${contextBlocks}`;
 }
 
+/**
+ * Build QuestionResult[] from an AskResponsePayload-shaped response. Shared by
+ * the bridge branch and the child (headless) branch.
+ */
+function responseToResults(
+	response: { cancelled: boolean; results: Array<{ id: string; selectedOptions: string[]; customInput?: string }> },
+	questions: AskParams["questions"],
+): QuestionResult[] {
+	return questions.map((q, i) => {
+		const r = response.results[i];
+		return {
+			id: q.id,
+			question: q.question,
+			description: q.description && q.description.trim().length > 0 ? q.description : undefined,
+			options: q.options.map((o) => o.label),
+			multi: q.multi ?? false,
+			selectedOptions: r?.selectedOptions ?? [],
+			customInput: r?.customInput ?? undefined,
+		};
+	});
+}
+
 // ── Tool description ─────────────────────────────────────────────────────────
 
 const ASK_TOOL_DESCRIPTION = `
@@ -205,8 +230,49 @@ 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
+			// bridge.ask() directly — NOT by the relay/bridge bus subscription.
+			// The bus events are notify + refcount only, and the pairing
+			// ASK_RESPONSE fires on ALL paths (success, error, timeout) so the
+			// refcount never leaks and the state machine is not stuck at blocked.
+			if (getBridge().active) {
+				const requestId = randomUUID();
+				getBus().emit(Events.ASK_REQUEST, {
+					source: "main",
+					requestId,
+					questions: params.questions,
+					toolCallId: _toolCallId,
+				});
+
+				let response: { cancelled: boolean; results: Array<{ id: string; selectedOptions: string[]; customInput?: string }> };
+				try {
+					// Pass the turn's AbortSignal: if the user aborts while the Client
+					// modal is open, the bridge request is cancelled (instead of
+					// lingering up to the 5-minute timeout) and the paired cancelled
+					// ASK_RESPONSE keeps the refcount balanced.
+					response = await getBridge().ask(params, _toolCallId, _signal);
+				} catch {
+					response = { cancelled: true, results: params.questions.map((q) => ({ id: q.id, selectedOptions: [] })) };
+				}
+				getBus().emit(Events.ASK_RESPONSE, { requestId, cancelled: response.cancelled, results: response.results });
+
+				const results = responseToResults(response, params.questions);
+				if (response.cancelled && results.every((r) => r.selectedOptions.length === 0)) {
+					return {
+						content: [{ type: "text", text: "User cancelled the question." }],
+						details: { results, customInput: undefined, description: undefined } satisfies AskToolDetails,
+					};
+				}
+				return {
+					content: [{ type: "text", text: buildAskSessionContent(results) }],
+					details: { results, customInput: undefined, description: undefined } satisfies AskToolDetails,
+				};
+			}
+
 			// Headless/subagent path: the child's ask tool connects to the parent's
 			// PI_SUBAGENT_SOCKET bridge (created in subagent/spawn.ts:startAskSocketServer)
 			// and exchanges ask_request/ask_response JSON lines.
@@ -237,6 +303,7 @@ export function registerAskTool(pi: ExtensionAPI): void {
 							type: "ask_request",
 							requestId,
 							questions: params.questions,
+							toolCallId: _toolCallId,
 						}) + "\n");
 					});
 
@@ -272,19 +339,8 @@ export function registerAskTool(pi: ExtensionAPI): void {
 					timer.unref();
 				});
 
-				// Build results from response
-				const results: QuestionResult[] = params.questions.map((q, i) => {
-					const r = response.results[i];
-					return {
-						id: q.id,
-						question: q.question,
-						description: q.description && q.description.trim().length > 0 ? q.description : undefined,
-						options: q.options.map((o) => o.label),
-						multi: q.multi ?? false,
-						selectedOptions: r?.selectedOptions ?? [],
-						customInput: r?.customInput ?? undefined,
-					};
-				});
+				// Build results from response (shared with the bridge branch)
+				const results = responseToResults(response, params.questions);
 
 				if (response.cancelled && results.every((r) => r.selectedOptions.length === 0)) {
 					return {
@@ -307,64 +363,86 @@ 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 });
-
-			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,
-				};
-
-				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],
-				};
-
-				return {
-					content: [{ type: "text", text: buildAskSessionContent([result]) }],
-					details,
-				};
-			}
-
-			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,
-				});
+			getBus().emit(Events.ASK_REQUEST, { source: "main", requestId: randomUUID(), questions: params.questions, toolCallId: _toolCallId });
+
+			// 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);
 			}
-
-			return {
-				content: [{ type: "text", text: buildAskSessionContent(results) }],
-				details: { results, customInput: undefined, description: undefined } satisfies AskToolDetails,
-			};
 		},
 	});
 }
+
+/**
+ * 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,
+		};
+
+		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],
+		};
+
+		return {
+			content: [{ type: "text", text: buildAskSessionContent([result]) }],
+			details,
+		};
+	}
+
+	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,
+	};
+}