threadroom-pi 0.1.0-beta.0

package/extensions/questions/stream.ts

@@ -0,0 +1,299 @@
+import type { Theme, ToolRenderContext, ToolRenderResultOptions } from '@earendil-works/pi-coding-agent';
+import { Text, truncateToWidth, type Component } from '@earendil-works/pi-tui';
+import { readable } from './text.ts';
+
+/** Transcript presentation only. Raw records confer no storage/delivery authority.
+ * Authored fields are sanitized before trusted theme styling; inputs are never changed. */
+export type StreamOptions = { readonly expanded: boolean };
+type Result = { readonly details?: unknown; readonly content?: readonly unknown[] };
+type RecordValue = Record<string, unknown>;
+type Role = 'question' | 'reply' | 'context';
+type Row = { text: string; color?: 'text' | 'dim' | 'warning' | 'error'; compact?: boolean };
+
+function record(value: unknown): RecordValue {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as RecordValue : {};
+}
+function list(value: unknown): unknown[] { return Array.isArray(value) ? value : []; }
+function field(value: unknown): string { return typeof value === 'string' ? readable(value) : ''; }
+function line(value: unknown): string { return field(value).replace(/\s+/gu, ' ').trim(); }
+function title(prompt: unknown): string {
+  const data = record(prompt);
+  return line(data.header) || field(data.question).split('\n').find(part => part.trim())?.trim() || '';
+}
+function authoredTitle(prompt: unknown): string { return line(record(prompt).header); }
+function preview(value: unknown, maxLines = 6, maxCharacters = 2000): string {
+  const text = field(value), lines = text.split('\n').map(part => part.trimEnd());
+  let shown = lines.slice(0, maxLines).join('\n'), clipped = lines.length > maxLines;
+  if (shown.length > maxCharacters) { shown = shown.slice(0, maxCharacters); clipped = true; }
+  return shown + (clipped ? '…' : '');
+}
+function compactPromptRows(prompts: unknown[]): Row[] {
+  if (prompts.length === 1) return preview(record(prompts[0]).question) ? [{ text: preview(record(prompts[0]).question) }] : [];
+  return prompts.flatMap((value, index) => {
+    const prompt = record(value), label = authoredTitle(prompt) || `Question ${index + 1}`;
+    return [{ text: label, color: 'dim' as const }, { text: preview(prompt.question) }];
+  });
+}
+// Escaped literal IDs retain actual identity even if an older host supplies controls.
+function identity(value: unknown): string {
+  return typeof value === 'string' && value.length ? JSON.stringify(value).slice(1, -1)
+    .replace(/[\u007f-\u009f\u202a-\u202e\u2066-\u2069]/gu, char => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`) : '';
+}
+function reference(kind: string, value: unknown): string {
+  const id = identity(value); return id ? `${kind}:${id}` : '';
+}
+function callReference(context?: ToolRenderContext): string { return reference('call', context?.toolCallId); }
+function integer(value: unknown): value is number { return Number.isInteger(value) && (value as number) >= 0; }
+function literal(label: string, value: unknown): Row[] {
+  return typeof value === 'string' ? [{ text: `${label}:`, color: 'dim' }, { text: field(value) }] : [];
+}
+function promptRows(value: unknown): Row[] {
+  const prompt = record(value), rows = [...literal('Authored header', prompt.header), ...literal('Question', prompt.question), ...literal('Context', prompt.context)];
+  if (typeof prompt.multiSelect === 'boolean') rows.push({ text: `Multiple selections: ${prompt.multiSelect ? 'allowed' : 'no'}`, color: 'dim' });
+  for (const [index, value] of list(prompt.options).entries()) {
+    const option = typeof value === 'string' ? { label: value } : record(value);
+    rows.push(...literal(`Suggestion ${index + 1}`, option.label), ...literal('Description', option.description), ...literal('Preview', option.preview));
+  }
+  return rows;
+}
+function compactReply(value: unknown): string {
+  const answer = record(value), selected = list(answer.selected).map(line).filter(Boolean).join(', ');
+  const custom = field(answer.answer) || field(answer.text), parts = [selected, custom].filter(Boolean);
+  return preview(parts.join(selected && custom ? '\n' : ''));
+}
+function nativeReplyRows(value: unknown): Row[] {
+  const answer = record(value), rows = literal('Reply', answer.text);
+  if (integer(answer.optionIndex)) rows.push({ text: `Original suggestion: ${answer.optionIndex + 1}`, color: 'dim' });
+  const selection = record(answer.selection);
+  rows.push(...literal('Selected label', selection.label), ...literal('Selected preview', selection.preview));
+  const indices = list(answer.optionIndices), selections = list(answer.selections);
+  for (const [position, value] of selections.entries()) {
+    const selected = record(value), index = indices[position];
+    rows.push(...literal(integer(index) ? `Selected suggestion ${index + 1}` : 'Selected label', selected.label),
+      ...literal('Selected preview', selected.preview));
+  }
+  rows.push(...literal('Additional reply', answer.custom));
+  return rows;
+}
+function contentText(result: Result): string {
+  return list(result.content).map(part => field(record(part).text)).filter(Boolean).join('\n');
+}
+
+/** No implicit padding or colored tool-success shell. The host owns placement. */
+function card(role: Role, heading: string, authoredTitle: string, metadata: string[], rows: Row[], theme: Theme): Component {
+  const color = role === 'question' ? 'borderAccent' : role === 'reply' ? 'customMessageLabel' : 'dim';
+  return {
+    render(width: number) {
+      if (width <= 0) return [];
+      const header = theme.fg(color, heading) + (authoredTitle ? ` · ${theme.fg('text', authoredTitle)}` : '');
+      const output = [truncateToWidth(header, width, '…')];
+      const meta = metadata.filter(Boolean).join(' · ');
+      if (meta) output.push(truncateToWidth(theme.fg('dim', `│ ${meta}`), width, '…'));
+      for (const row of rows) {
+        // SDK rows never contain line breaks. A one-column viewport cannot fit
+        // a wide glyph, so expanded originals use reversible Unicode escapes.
+        const literal = row.compact ? line(row.text) : width === 1
+          ? row.text.replace(/[^\x00-\x7f]/gu, char => `\\u{${char.codePointAt(0)!.toString(16)}}`) : row.text;
+        const text = theme.fg(row.color || 'text', literal);
+        output.push(...(row.compact ? [truncateToWidth(text, width, '…')] : new Text(text, 0, 0).render(width).map(part => truncateToWidth(part, width, ''))));
+      }
+      return output;
+    },
+    invalidate() {},
+  };
+}
+function nativeMetadata(data: RecordValue, question: boolean): string[] {
+  return ['PRIVATE', 'ASYNC', reference('q', question ? data.id : data.questionId)];
+}
+
+/** Original native source record. A caption is not proof of a successful append. */
+export function renderNativeQuestion(data: unknown, options: StreamOptions, theme: Theme): Component {
+  const source = record(data), prompt = record(source.prompt), expanded = options?.expanded;
+  const rows = expanded ? [
+    ...literal('Question identity', identity(source.id) || undefined),
+    ...literal('Source call', identity(source.toolCallId) || undefined),
+    ...promptRows(prompt),
+  ] : [...compactPromptRows([prompt]), ...([{ text: [list(prompt.options).length ? `${list(prompt.options).length} suggestions` : '',
+    typeof prompt.context === 'string' ? 'Context available' : ''].filter(Boolean).join(' · '), color: 'dim', compact: true }]
+    .filter(row => row.text) as Row[])];
+  return card('question', 'Question', authoredTitle(prompt), expanded ? nativeMetadata(source, true) : [], rows, theme);
+}
+
+/** Human reply record; does not claim persistence, consumption, or completion. */
+export function renderNativeAnswer(data: unknown, options: StreamOptions, theme: Theme): Component {
+  const source = record(data), answer = record(source.answer);
+  const rows = options?.expanded ? [
+    ...literal('Question identity', identity(source.questionId) || undefined),
+    ...literal('Answer identity', identity(source.answerId) || undefined),
+    ...promptRows(source.prompt), ...nativeReplyRows(answer),
+  ] : [{ text: compactReply(answer) }].filter(row => row.text);
+  return card('reply', 'Your reply', title(source.prompt), options?.expanded ? nativeMetadata(source, false) : [], rows, theme);
+}
+
+/** Context echo is intentionally compact, not another primary reply body.
+ * An SDK context row alone cannot prove the model read or received it. */
+export function renderNativeFeedback(details: unknown, options: StreamOptions, theme: Theme): Component {
+  const source = record(details);
+  const rows = options?.expanded ? [
+    ...literal('Question identity', identity(source.questionId) || undefined),
+    ...literal('Answer identity', identity(source.answerId) || undefined),
+    ...promptRows(source.prompt), ...nativeReplyRows(source.answer),
+  ] : [];
+  return card('context', 'Reply context', '', options?.expanded ? nativeMetadata(source, false) : [], rows, theme);
+}
+
+/** Public SDK call context supplies a call reference; absent older-host context
+ * never causes a reference inferred from authored question text. */
+export function renderAsyncAskCall(args: unknown, theme: Theme, context?: ToolRenderContext): Component {
+  const prompt = record(args), expanded = !!context?.expanded;
+  return card('question', 'Question request', authoredTitle(prompt), expanded ? ['PRIVATE', 'ASYNC', callReference(context)] : [],
+    expanded ? promptRows(prompt) : compactPromptRows([prompt]), theme);
+}
+
+const failedRequests: Record<string, string> = {
+  unsupported_host: 'Not presented · unsupported host',
+  aborted: 'Request aborted',
+  session_changing: 'Request detached · session changing',
+  invalid_question: 'Question request invalid',
+  identity_conflict: 'Question identity conflict',
+  save_failed: 'Question storage failed',
+  storage_unconfirmed: 'Storage unconfirmed',
+};
+export function renderAsyncAskResult(result: Result, options: ToolRenderResultOptions, theme: Theme, context?: ToolRenderContext): Component {
+  const details = record(result.details), status = field(details.status), partial = options?.isPartial || context?.isPartial;
+  const children = list(details.questions).map(record);
+  const failed = Object.hasOwn(failedRequests, status) ? failedRequests[status] : undefined;
+  const error = context?.isError === true, expanded = !!options?.expanded;
+  const metadata = expanded ? ['PRIVATE', 'ASYNC', reference('q', details.id) || callReference(context)] : [];
+  const heading = error ? 'Question request failed' : partial ? 'Question request update'
+    : status === 'pending' ? 'Waiting for reply' : status === 'answered' ? 'Reply already saved' : 'Question request result';
+  const rows: Row[] = [], content = contentText(result);
+  if (failed) rows.push({ text: failed, color: status === 'storage_unconfirmed' ? 'warning' : 'error', compact: true });
+  for (const [index, child] of children.entries()) {
+    const childStatus = field(child.status), childFailure = failedRequests[childStatus];
+    const childIdentity = expanded && identity(child.id) ? ` · q:${identity(child.id)}` : '';
+    rows.push({ text: `Question ${index + 1}${childIdentity} · ${childFailure || childStatus || 'unknown result'}`,
+      color: childFailure ? childStatus === 'storage_unconfirmed' ? 'warning' : 'error' : 'dim', compact: true });
+    if (childFailure || options?.expanded) rows.push(...literal('Reason', child.reason), ...literal('Storage diagnostic', child.error),
+      ...literal('Presentation diagnostic', child.presentationError));
+  }
+  if (error || !Object.keys(details).length) {
+    const diagnostic = content || field(details.error) || field(details.reason);
+    if (diagnostic) rows.push({ text: diagnostic, color: error ? 'error' : 'text', compact: !options?.expanded });
+  }
+  if (expanded) {
+    rows.push(...literal('Question identity', identity(details.id) || undefined), ...literal('Source call', identity(context?.toolCallId) || undefined));
+    if (status) rows.push({ text: `Status reported by request: ${status}`, color: 'dim' });
+    rows.push(...literal('Reason', details.reason), ...literal('Storage diagnostic', details.error), ...literal('Presentation diagnostic', details.presentationError));
+    const args = record(context?.args), authored = list(args.questions);
+    if (authored.length) for (const [index, prompt] of authored.entries()) {
+      rows.push({ text: `Original question ${index + 1}`, color: 'dim' }, ...promptRows(prompt));
+    }
+    else if (context?.args) rows.push(...promptRows(context.args));
+  }
+  return card('context', heading, '', metadata, rows, theme);
+}
+
+export function renderBlockingAskCall(args: unknown, theme: Theme, context?: ToolRenderContext): Component {
+  const input = record(args), requests = list(input.questions), first = record(requests[0]);
+  const nestedQuestionId = requests.length === 1 ? identity(first.questionId) : '';
+  const questionId = nestedQuestionId || (!requests.length ? identity(input.questionId) : ''), questions = questionId ? [] : requests;
+  const expanded = !!context?.expanded;
+  const rows: Row[] = questionId
+    ? expanded ? literal('Existing question identity', questionId) : []
+    : expanded ? questions.flatMap((question, index) => [
+      { text: `Original question ${index + 1}`, color: 'dim' as const }, ...promptRows(question),
+    ]) : compactPromptRows(questions);
+  return card('question', questionId ? 'Wait for existing question' : 'Question request',
+    questionId ? '' : questions.length === 1 ? authoredTitle(first) : `${questions.length} questions`,
+    expanded ? ['PRIVATE', 'BLOCKING', questionId ? reference('q', questionId) : callReference(context)] : [], rows, theme);
+}
+function blockingAnswerRows(value: unknown, specs: unknown[], expanded: boolean, ref: string): Row[] {
+  const answer = record(value), index = integer(answer.questionIndex) ? answer.questionIndex : undefined;
+  const heading = index === undefined ? 'Question reply' : `Original question ${index + 1}`;
+  if (!expanded) {
+    const rows: Row[] = [];
+    if (specs.length > 1) {
+      const spec = index === undefined ? undefined : specs[index];
+      rows.push({ text: authoredTitle(spec) || (index === undefined ? 'Reply' : `Question ${index + 1}`), color: 'dim' });
+    }
+    const reply = compactReply(answer);
+    if (reply) rows.push({ text: reply });
+    if (typeof answer.notes === 'string') rows.push({ text: 'Notes available', color: 'dim', compact: true });
+    return rows;
+  }
+  const rows: Row[] = [{ text: `${heading}${ref ? ` · ${ref}${index === undefined ? '' : `/${index + 1}`}` : ''}`, color: 'dim' }];
+  if (!specs.length) rows.push(...literal('Question', answer.question));
+  rows.push(...literal('Reply', answer.answer));
+  if (integer(answer.optionIndex)) rows.push({ text: `Original suggestion: ${answer.optionIndex + 1}`, color: 'dim' });
+  const indices = list(answer.optionIndices);
+  for (const [position, selected] of list(answer.selected).entries()) {
+    const option = indices[position], label = integer(option) ? `Selected suggestion ${option + 1}` : 'Selected label';
+    rows.push(...literal(label, selected));
+  }
+  rows.push(...literal('Selected preview', answer.preview));
+  for (const [position, preview] of list(answer.previews).entries()) {
+    rows.push(...literal(`Selected preview ${position + 1}`, preview === null ? '(none authored)' : preview));
+  }
+  rows.push(...literal('Notes', answer.notes));
+  return rows;
+}
+
+/** Partial replies retain authored indices; abort/errors never become a human cancel. */
+export function renderBlockingAskResult(result: Result, options: ToolRenderResultOptions, theme: Theme, context?: ToolRenderContext): Component {
+  const details = record(result.details), input = record(context?.args), requests = list(input.questions), first = record(requests[0]);
+  const nestedQuestionId = requests.length === 1 ? identity(first.questionId) : '';
+  const referencedQuestionId = nestedQuestionId || (!requests.length ? identity(input.questionId) : '');
+  const specs = referencedQuestionId ? [] : requests, answers = list(details.answers);
+  const questionId = identity(details.questionId) || referencedQuestionId, existing = !!questionId;
+  const partial = options?.isPartial || context?.isPartial, error = context?.isError, expanded = !!options?.expanded;
+  const recognizedReply = typeof details.cancelled === 'boolean' || Array.isArray(details.answers);
+  const heading = error ? 'Question request failed' : partial ? 'Reply update'
+    : existing && details.cancelled === true ? 'Question wait cancelled'
+    : existing && answers.length ? 'Your reply' : existing ? 'Question wait result'
+    : details.cancelled === true ? 'Questionnaire cancelled'
+    : recognizedReply ? answers.length === 1 ? 'Your reply' : 'Your replies' : 'Question request result';
+  const metadata = expanded
+    ? ['PRIVATE', 'BLOCKING', existing ? reference('q', details.questionId || referencedQuestionId) : callReference(context) || reference('group', details.groupId)]
+    : [];
+  const rows: Row[] = [];
+  if (existing) {
+    if (details.cancelled === true) rows.push({ text: 'Wait cancelled · original nonblocking question remains pending', color: 'dim', compact: true });
+    else if (typeof details.waitNote === 'string') rows.push({ text: field(details.waitNote), color: 'dim', compact: true });
+  } else if (typeof details.cancelled === 'boolean' && (details.cancelled || specs.length !== 1 || answers.length !== 1)) {
+    rows.push({ text: `${answers.length} ${answers.length === 1 ? 'reply' : 'replies'}${specs.length ? ` / ${specs.length} original questions` : ''}${details.cancelled ? ' · partial replies retained' : ''}`, color: 'dim', compact: true });
+    if (specs.length && answers.length < specs.length) rows.push({ text: 'Some original questions unanswered', color: 'dim', compact: true });
+  }
+  if (expanded) {
+    rows.push(...literal(existing ? 'Existing question identity' : 'Group identity', existing ? questionId : identity(details.groupId) || undefined));
+    if (existing && typeof details.waitStatus === 'string') rows.push({ text: `Wait status: ${field(details.waitStatus)}`, color: 'dim' });
+    for (const [index, spec] of specs.entries()) rows.push({ text: `Original question ${index + 1}`, color: 'dim' }, ...promptRows(spec));
+  }
+  for (const answer of answers) rows.push(...blockingAnswerRows(answer, specs, expanded, metadata[2] || ''));
+  if (!answers.length && typeof details.cancelled !== 'boolean') {
+    const text = contentText(result);
+    if (text) rows.push({ text, color: error ? 'error' : 'text', compact: !expanded });
+  }
+  const resultTitle = !existing && specs.length === 1 ? authoredTitle(specs[0]) : '';
+  return card(error ? 'context' : 'reply', heading, resultTitle, metadata, rows, theme);
+}
+
+/** One public question tool has two execution modes. The authored schema stays
+ * familiar; only an explicit blocking=false changes the execution contract. */
+export function renderPrivateAskCall(args: unknown, theme: Theme, context?: ToolRenderContext): Component {
+  const input = record(args);
+  if (input.blocking !== false) return renderBlockingAskCall(args, theme, context);
+  const questions = list(input.questions), first = record(questions[0]);
+  if (questions.length === 1) return renderAsyncAskCall(first, theme, context);
+  const expanded = !!context?.expanded;
+  return card('question', 'Question request', `${questions.length} questions`, expanded ? ['PRIVATE', 'ASYNC', callReference(context)] : [],
+    expanded ? questions.flatMap((question, index) => [
+      { text: `Original question ${index + 1}`, color: 'dim' as const }, ...promptRows(question),
+    ]) : compactPromptRows(questions), theme);
+}
+
+export function renderPrivateAskResult(result: Result, options: ToolRenderResultOptions, theme: Theme, context?: ToolRenderContext): Component {
+  return record(context?.args).blocking === false
+    ? renderAsyncAskResult(result, options, theme, context)
+    : renderBlockingAskResult(result, options, theme, context);
+}

package/extensions/questions/text.ts

@@ -0,0 +1,10 @@
+import { stripVTControlCharacters } from 'node:util';
+
+/** Render/paste safety, never a rewrite of the original stored question. */
+export function readable(value: unknown): string {
+  return stripVTControlCharacters(String(value)).replace(/[\u0000-\u0009\u000b-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/gu, ' ');
+}
+export function replyText(value: string): string { return readable(value); }
+export function pastedReplyText(value: string): string {
+  return readable(value.replace(/\r\n/gu, '\n').replace(/\r/gu, '\n').replace(/\t/gu, '    '));
+}

package/extensions/questions/tool.ts

@@ -0,0 +1,309 @@
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { truncateHead } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+import type { QuestionAnswer, QuestionGroup, QuestionResult } from './types.ts';
+import { renderPrivateAskCall, renderPrivateAskResult } from './stream.ts';
+
+/** TUI presentation owns interaction; rejection means no human cancellation result.
+ * Composed hosts carry their originating native activation through final return. */
+export type QuestionPresentation = QuestionResult | Readonly<{ result: QuestionResult; accept: () => void }>;
+export type QuestionPresenter = (
+  group: QuestionGroup, ctx: ExtensionContext, signal?: AbortSignal,
+) => Promise<QuestionPresentation>;
+
+// New questions and references share one required collection so an omitted
+// alternative never needs a fabricated placeholder in a generated tool call.
+const authoredQuestion = Type.Object({
+  question: Type.String({ minLength: 1, description: 'What the person is being asked.' }),
+  header: Type.Optional(Type.String({ maxLength: 16, description: 'Short tab label.' })),
+  context: Type.Optional(Type.String({ description: 'Supporting detail shown directly beneath the question, such as a command, path, or comparison background.' })),
+  options: Type.Array(Type.Object({
+    label: Type.String({ minLength: 1, maxLength: 60 }),
+    description: Type.Optional(Type.String({ description: 'A short explanation shown when this suggestion is selected.' })),
+    preview: Type.Optional(Type.String({ description: 'Additional content shown when this suggestion is selected.' })),
+  }, { additionalProperties: false }), { minItems: 2, maxItems: 4 }),
+  multiSelect: Type.Optional(Type.Boolean()),
+}, { additionalProperties: false });
+const pendingQuestion = Type.Object({
+  questionId: Type.String({ minLength: 1,
+    description: 'Stable pending ID returned by an earlier nonblocking call. Reuses that question instead of asking it again.' }),
+}, { additionalProperties: false });
+const parameters = Type.Object({
+  questions: Type.Union([
+    Type.Array(authoredQuestion, { minItems: 1, maxItems: 4 }),
+    Type.Array(pendingQuestion, { minItems: 1, maxItems: 1 }),
+  ], { description: 'New questions, or one pending question reference when returning to an earlier nonblocking question.' }),
+  blocking: Type.Optional(Type.Boolean({ default: true,
+    description: 'Wait for an answer before continuing. Defaults to true; set false to leave new questions pending while continuing.' })),
+}, { additionalProperties: false,
+  description: 'Provide 1–4 new questions, or a single pending question reference. blocking defaults to true.' });
+
+function failure(code: string, message: string): Error {
+  return Object.assign(new Error(message), { code });
+}
+
+function resultText(result: QuestionResult): string {
+  const notice = '\n[Result text truncated; full answers are retained in tool result details.]';
+  const complete = JSON.stringify(result, null, 2);
+  const first = truncateHead(complete, { maxBytes: 50 * 1024 - Buffer.byteLength(notice), maxLines: 1998 });
+  if (!first.truncated) return complete;
+  // A large preview (or a single huge escaped line) must not erase the decision.
+  const short = (text: string | undefined) => text === undefined ? undefined : text.length > 512 ? `${text.slice(0, 512)}…` : text;
+  const summary = JSON.stringify({ cancelled: result.cancelled, answers: result.answers.map((answer) => ({
+    questionIndex: answer.questionIndex, question: short(answer.question),
+    optionIndex: answer.optionIndex, optionIndices: answer.optionIndices,
+    selected: answer.selected?.map(short), answer: short(answer.answer), notes: short(answer.notes), wasCustom: answer.wasCustom,
+  })) }, null, 2);
+  const prefix = `Answer summary (long text shortened; previews omitted):\n${summary}\n\nResult detail:\n`;
+  const remaining = truncateHead(complete, {
+    maxBytes: 50 * 1024 - Buffer.byteLength(prefix) - Buffer.byteLength(notice),
+    maxLines: 2000 - prefix.split('\n').length - notice.split('\n').length,
+  });
+  return prefix + remaining.content + notice;
+}
+
+/** Stop waiting even if a presenter ignores cancellation; always observe its late rejection. */
+function abortable<T>(work: () => Promise<T>, signal: AbortSignal): Promise<T> {
+  signal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const aborted = () => reject(signal.reason);
+    signal.addEventListener('abort', aborted, { once: true });
+    Promise.resolve().then(() => {
+      signal.throwIfAborted();
+      return work();
+    }).then(resolve, reject).finally(() => signal.removeEventListener('abort', aborted));
+  });
+}
+
+/** SDK dialog fallback: numbered entries preserve identity even for duplicate labels. */
+async function dialogs(group: QuestionGroup, ctx: ExtensionContext, signal: AbortSignal): Promise<QuestionResult> {
+  const answers: QuestionAnswer[] = [];
+  const select = (title: string, choices: string[]) => abortable(() => ctx.ui.select(title, choices, { signal }), signal);
+  const input = (title: string) => abortable(() => ctx.ui.input(title, undefined, { signal }), signal);
+  for (const [questionIndex, spec] of group.questions.entries()) {
+    const options = spec.options ?? [];
+    const checked = new Set<number>();
+    let custom = '', notes = '';
+    const title = [spec.header, spec.question, spec.context].filter(Boolean).join('\n');
+    const currentAnswer = (): QuestionAnswer | undefined => {
+      if (!checked.size && !custom) return undefined;
+      const indices = [...checked].sort((a, b) => a - b);
+      const base = { questionIndex, question: spec.question, ...(notes ? { notes } : {}) };
+      if (spec.multiSelect) {
+        return { ...base, selected: indices.map((index) => options[index].label), optionIndices: indices,
+          previews: indices.map((index) => options[index].preview ?? null),
+          ...(custom ? { answer: custom, wasCustom: true } : { wasCustom: false }) };
+      }
+      if (custom) return { ...base, answer: custom, wasCustom: true };
+      const optionIndex = indices[0], option = options[optionIndex];
+      return { ...base, answer: option.label, optionIndex, wasCustom: false,
+        ...(option.preview !== undefined ? { preview: option.preview } : {}) };
+    };
+    const cancelled = (): QuestionResult => {
+      const current = currentAnswer();
+      return { answers: current ? [...answers, current] : answers, cancelled: true };
+    };
+    while (true) {
+      const choices = options.map((option, index) => [
+        `${checked.has(index) ? '[x]' : '[ ]'} ${index + 1}. ${option.label}`,
+        option.description, option.preview,
+      ].filter((part) => part !== undefined).join('\n'));
+      const controls = ['Reply: Write or clear custom answer', 'Notes: Write or clear notes',
+        'Next: Keep this answer', 'Skip: Leave this question unanswered', 'Cancel: Cancel this questionnaire'];
+      const menu = [...choices, ...controls];
+      const choice = await select(`${title}${custom ? `\nCustom answer: ${custom}` : ''}${notes ? `\nNotes: ${notes}` : ''}`, menu);
+      signal.throwIfAborted();
+      if (choice === undefined) return cancelled();
+      const action = menu.indexOf(choice);
+      if (action < 0) throw failure('invalid_dialog_response', 'Question dialog returned an unknown choice.');
+      if (action < options.length) {
+        if (spec.multiSelect) {
+          if (checked.has(action)) checked.delete(action); else checked.add(action);
+        } else {
+          checked.clear(); checked.add(action); custom = '';
+        }
+        continue;
+      }
+      switch (action - options.length) {
+        case 0: {
+          const value = await input(`${title}\nCustom answer (empty clears it)`);
+          signal.throwIfAborted();
+          if (value !== undefined) custom = value.trim();
+          continue;
+        }
+        case 1: {
+          const value = await input(`${title}\nNotes (empty clears them)`);
+          signal.throwIfAborted();
+          if (value !== undefined) notes = value.trim();
+          continue;
+        }
+        case 2: {
+          const answer = currentAnswer();
+          if (!answer) continue;
+          answers.push(answer);
+          break;
+        }
+        case 3: break;
+        case 4: return cancelled();
+      }
+      break;
+    }
+  }
+  const submit = 'Submit: Return these answers', cancel = 'Cancel: Cancel this questionnaire';
+  const decision = await select(`Review: ${answers.length}/${group.questions.length} questions answered\n${JSON.stringify(answers, null, 2)}`, [submit, cancel]);
+  signal.throwIfAborted();
+  if (decision !== undefined && decision !== submit && decision !== cancel) {
+    throw failure('invalid_dialog_response', 'Question review returned an unknown choice.');
+  }
+  return { answers, cancelled: decision !== submit };
+}
+
+export type NonblockingQuestionProducer = (
+  toolCallId: string,
+  question: Readonly<{ question: string; header?: string; context?: string; options?: readonly Readonly<{ label: string; description?: string; preview?: string }>[]; multiSelect?: boolean }>,
+  ctx: ExtensionContext,
+  signal?: AbortSignal,
+) => Promise<Readonly<{ content: readonly unknown[]; details: Record<string, unknown> }>>;
+
+export type ExistingQuestionWait = (questionId: string, ctx: ExtensionContext, signal: AbortSignal) => Promise<Readonly<{
+  sessionId: string;
+  questionId: string;
+  answerId?: string;
+  status: 'answered' | 'cancelled' | 'already_queued' | 'already_received' | 'already_claimed';
+  note?: string;
+  acceptWait?: () => void;
+  acceptClaim?: () => void;
+  releaseClaim?: () => void;
+  result: QuestionResult;
+}>>;
+
+/** Registers the private question tool; no network, service, or global settings changes. */
+export function registerBlockingQuestions(pi: ExtensionAPI, present: QuestionPresenter, waitExisting?: ExistingQuestionWait,
+  captureAdmission?: (ctx: ExtensionContext) => () => void, askNonblocking?: NonblockingQuestionProducer): void {
+  const active = new Set<AbortController>();
+  let retired = false, replacing = false, changingTree = false, compacting = false;
+  const transitioning = () => replacing || changingTree || compacting;
+  function detachActive(message: string) {
+    for (const controller of active) controller.abort(failure('presentation_detached', message));
+    active.clear();
+  }
+  pi.on('session_shutdown', () => {
+    retired = true; replacing = true;
+    detachActive('Question presentation detached during session shutdown.');
+  });
+  for (const event of ['session_before_switch', 'session_before_fork'] as const) pi.on(event, () => {
+    replacing = true; detachActive('Question presentation detached during session transition.');
+  });
+  pi.on('session_before_tree', () => {
+    changingTree = true; detachActive('Question presentation detached during session transition.');
+  });
+  pi.on('session_before_compact', () => {
+    compacting = true; detachActive('Question presentation detached during session transition.');
+  });
+  // Only the matching positive lifecycle event reopens its gate. Stock Pi
+  // exposes no cancelled/failed replacement or tree event, so those attempts
+  // remain fail-closed until their positive event or a lifecycle rebind.
+  pi.on('session_start', () => { retired = false; replacing = changingTree = compacting = false; });
+  pi.on('session_tree', () => { changingTree = false; });
+  pi.on('session_compact', () => { compacting = false; });
+  pi.on('session_compact_failed', () => { compacting = false; });
+  pi.registerTool({
+    name: 'ask_user_question',
+    label: 'Ask Questions',
+    description: 'A private questionnaire for decisions and feedback. It ordinarily waits for the person’s answer. A nonblocking question stays open while useful work continues and can become required later without being asked twice. The person sees the question, its context, suggestions, and selected previews together. Supports 1–4 questions, 2–4 suggestions, custom replies, multiple selection, and partial submission. Result text is limited to 2000 lines/50KB; full answers remain in details.',
+    promptSnippet: 'Ask private questions; ordinarily waits, or can leave them pending while useful work continues',
+    promptGuidelines: ['Blocking is the ordinary question-and-answer experience. Nonblocking questions fit moments when useful work can continue while the person answers.'],
+    parameters,
+    renderShell: 'self',
+    renderCall: renderPrivateAskCall,
+    renderResult: renderPrivateAskResult,
+    async execute(toolCallId, params, signal, _onUpdate, ctx) {
+      if (retired) throw failure('presentation_detached', 'Question producer belongs to a retired session.');
+      if (transitioning()) throw failure('presentation_detached', 'Private question admission is closed during an unresolved session transition.');
+      const controller = new AbortController();
+      const signals = [controller.signal, signal, ctx.signal].filter((value): value is AbortSignal => value !== undefined);
+      const lifetime = AbortSignal.any(signals);
+      lifetime.throwIfAborted();
+      if (!ctx.hasUI || ctx.mode === 'print' || ctx.mode === 'json') {
+        throw failure('unsupported_host', 'ask_user_question needs an interactive TUI or SDK dialog host; no question was presented and no human declined.');
+      }
+      const requests = Array.isArray(params.questions) ? params.questions : [];
+      const references = requests.filter((request): request is { questionId: string } => 'questionId' in request);
+      const reference = references[0], authored = reference ? undefined : requests;
+      const blocking = params.blocking !== false;
+      if (!requests.length || references.length > 1 || (reference && requests.length !== 1)) {
+        throw failure('invalid_arguments', 'Provide 1–4 new questions, or one existing pending question reference.');
+      }
+      if (reference && !blocking) {
+        throw failure('invalid_arguments', 'A pending question reference is already nonblocking; wait for it with blocking=true.');
+      }
+      if (!blocking && !askNonblocking) throw failure('unsupported_host', 'This question producer does not support nonblocking questions.');
+      active.add(controller);
+      try {
+        if (!blocking) {
+          const results = [];
+          for (const [index, spec] of authored!.entries()) {
+            results.push(await askNonblocking!(`${toolCallId}:${index}`, {
+              question: spec.question,
+              ...(spec.header !== undefined ? { header: spec.header } : {}),
+              ...(spec.context !== undefined ? { context: spec.context } : {}),
+              options: spec.options.map((option) => ({ label: option.label,
+                ...(option.description !== undefined ? { description: option.description } : {}),
+                ...(option.preview !== undefined ? { preview: option.preview } : {}) })),
+              ...(spec.multiSelect !== undefined ? { multiSelect: spec.multiSelect } : {}),
+            }, ctx, lifetime));
+            lifetime.throwIfAborted();
+          }
+          if (results.length === 1) return results[0];
+          const questions = results.map((item) => item.details);
+          const accepted = questions.every((item) => item.status === 'pending' || item.status === 'answered');
+          const value = { status: !accepted ? 'partial' : questions.every((item) => item.status === 'answered') ? 'answered' : 'pending', questions };
+          return { content: [{ type: 'text', text: JSON.stringify(value) }], details: value };
+        }
+        if (reference) {
+          if (ctx.mode !== 'tui' || !waitExisting) throw failure('unsupported_host', 'Waiting on an existing private nonblocking question needs the interactive TUI host that owns it.');
+          let waited: Awaited<ReturnType<ExistingQuestionWait>> | undefined;
+          try {
+            // The native wait already owns lifetime cancellation. Keeping its
+            // resolved value visible here lets a final abort release a claim
+            // before any answer-bearing tool result exists.
+            waited = await waitExisting(reference.questionId, ctx, lifetime);
+            lifetime.throwIfAborted();
+            // Every native outcome is activation-bound; answer-bearing outcomes
+            // additionally arbitrate the one delivery winner.
+            waited.acceptWait?.();
+            waited.acceptClaim?.();
+            const text = waited.note
+              ? JSON.stringify({ status: waited.status, questionId: waited.questionId, note: waited.note })
+              : waited.status === 'cancelled'
+                ? JSON.stringify({ status: waited.status, questionId: waited.questionId, ...waited.result,
+                    note: 'Blocking wait cancelled. The original nonblocking question remains pending.' })
+                : resultText(waited.result);
+            return { content: [{ type: 'text', text }], details: {
+              groupId: `native:${waited.questionId}`, sessionId: waited.sessionId, questionId: waited.questionId,
+              waitStatus: waited.status, ...(waited.note ? { waitNote: waited.note } : {}),
+              ...(waited.status === 'answered' && waited.answerId ? { receivedNativeAnswerIds: [waited.answerId] } : {}), ...waited.result,
+            } };
+          } catch (error) { waited?.releaseClaim?.(); throw error; }
+        }
+        // TUI composition returns its fence with the presenter outcome; SDK
+        // dialogs need it captured here before their first awaited interaction.
+        const acceptCompletion = ctx.mode === 'tui' ? undefined : captureAdmission?.(ctx);
+        const group: QuestionGroup = Object.freeze({
+          id: `blocking:${toolCallId}`, mode: 'blocking',
+          questions: Object.freeze(authored!.map((spec, index) => Object.freeze({
+            ...spec, id: `question:${index}`,
+            options: Object.freeze(spec.options.map((option) => Object.freeze({ ...option }))),
+          }))),
+        });
+        const presented = await abortable(() => ctx.mode === 'tui' ? present(group, ctx, lifetime) : dialogs(group, ctx, lifetime), lifetime);
+        lifetime.throwIfAborted();
+        const result = 'result' in presented ? presented.result : presented;
+        if ('result' in presented) presented.accept(); else acceptCompletion?.();
+        return { content: [{ type: 'text', text: resultText(result) }], details: { groupId: group.id, ...result } };
+      } finally {
+        active.delete(controller);
+      }
+    },
+  });
+}