@fitchmultz/pi-ask-question 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,9 +1,18 @@
 # Changelog
 
+## 0.6.0 — 2026-10-31
+
+- Keep preceding conversation text visible above TUI questions and let users read the transcript without cancelling or losing their answer.
+- Let cooperative observers query a current TUI question after attachment, including its original deadline and runtime owner, and reconcile accepted answer IDs after a lost result without reapplying them.
+- Rewrite the README for human readers, add a question-flow diagram, and move API and maintainer details into linked guides.
+- Add a cooperative `pi.events` bridge for exact, correlated answers to live TUI questions, with receipts after applying the existing answer state.
+- Preserve local keyboard/dialog behavior and the shared five-minute deadline; reject stale/duplicate replies and dispose subscriptions on completion, cancellation, timeout, and reload.
+- Support literal custom text and exact multi-select arrays without interpreting speech as option approvals.
+
 ## 0.5.1 — 2026-10-04
 
 - Distribute this project publicly as `@fitchmultz/pi-ask-question`, preserving the existing version line, Git installation, `ask_question` tool, and `/grill-me` behavior.
-- Lead installation guidance with the owned scoped package and distinguish the unrelated unscoped npm package.
+- Lead installation guidance with the owned scoped package.
 - Qualify the latest stable official Pi and maintained fork main once per run, freezing their SDK and companion graphs across existing TUI/RPC, type, package, and native install checks.
 - Add a main-only, opt-in repository npm release pipeline that requires both host qualifications before publishing.
 

package/README.md

@@ -1,129 +1,66 @@
-# pi ask-question extension
+# pi-ask-question
 
-A [pi](https://github.com/earendil-works/pi-mono) extension that adds `ask_question`: a model-callable tool with interactive UIs in TUI and RPC modes for asking one or more clarifying questions before work continues. It also adds `/grill-me`, a mode that makes the agent pressure-test underspecified requests before doing the work.
+This [Pi](https://github.com/earendil-works/pi) extension asks for your decisions before the agent continues a task. Use `/grill-me` to guide the agent through unclear requirements.
 
-## What it does
-
-- Adds the `ask_question` custom tool
-- Supports one question or a sequence of questions
-- Supports ordered choices, multi-select, and typed custom answers
-- Adds the custom-answer option automatically
-- Returns answers in tool result text and structured `details`
-- Stops waiting after five minutes and lets the agent continue with an AFK reply
-- Adds `/grill-me` to toggle pressure-test mode
-
-## Requirements
-
-- Pi 1.0.0 or later (official releases and the maintained fork)
-- Node.js 24 or later
+![Pi calls ask_question, shows choices, and returns your answer to the agent. A separate five-minute timeout returns an AFK reply.](.github/readme/question-flow.png)
 
 ## Install
 
-Install the scoped package with pi:
+Requires Pi 1.0.0+ and Node.js 24+. Supports official Pi releases and Mitch's Pi fork.
+
+Run these commands:
 
 ```bash
 pi install npm:@fitchmultz/pi-ask-question
+pi
 ```
 
-**The unscoped npm package `pi-ask-question` is not this project and is maintained by someone else.** Use `@fitchmultz/pi-ask-question` for this repository.
+Use `/reload` if Pi is already open. See [Git installation](docs/reference.md#installation-and-updates) for the alternative source.
 
-GitHub remains a supported fallback, including existing tags:
+## Try it
 
-```bash
-pi install https://github.com/fitchmultz/pi-ask-question
-```
+Send this request to Pi:
 
-Use `/reload` after updating extension code on current official Pi and the maintained fork. Restart Pi after changing dependencies or the host runtime.
+> Plan a settings page. Use ask_question to ask which settings to include first.
 
-For local development:
+Select a choice or select **Type a custom answer**. Multi-select questions let you select more than one choice.
 
-```bash
-pi -e ./extensions/ask-question.ts
-```
+Use Up/Down to move between choices. Press Enter to answer. For multi-select questions, press Space to change selected choices. Submit question sets and multi-select answers from the final review.
 
-## Grill-me mode
+Press Ctrl+O to read the conversation, then press it again to return to the question. Your current answer stays in place.
 
-Toggle the mode:
+Escape leaves the custom answer editor; otherwise, it cancels the question. Your editor draft stays unchanged. See [terminal controls](docs/reference.md#terminal-controls) for question navigation, long text, and custom bindings.
 
-```text
-/grill-me
-```
+## Limits
 
-Explicit commands:
+Each call has one five-minute limit for all questions. At timeout, the agent receives an AFK reply and can use its best judgment.
 
-```text
-/grill-me on
-/grill-me off
-/grill-me status
-```
+The tool keeps saved answers. It does not submit unsaved custom answer text or select an answer for you.
 
-When enabled, the footer shows subtle `grill-mode` text, and the agent is told to walk the decision tree, inspect available repo evidence before asking, ask one blocking question at a time, and include its recommended answer first. It uses `ask_question` in TUI and RPC modes when the tool is active; in print and JSON modes, it asks in normal text instead.
+Question dialogs require the terminal UI or an RPC client that supports Pi dialogs. Print and JSON modes return a tool error.
 
-## Tool shape
+## Check requirements with `/grill-me`
 
-Ask one question:
+Enable the mode before your request:
 
-```json
-{
-  "question": "Which implementation should I use?",
-  "options": ["Smallest working change", "Full refactor"],
-  "multiSelect": false
-}
+```text
+/grill-me on
 ```
 
-Ask several questions:
-
-```json
-{
-  "questions": [
-    {
-      "id": "scope",
-      "question": "What scope should I use?",
-      "options": ["Minimal", "Complete"]
-    },
-    {
-      "id": "checks",
-      "question": "Which checks should I run?",
-      "options": ["Typecheck", "Tests", "Runtime smoke"],
-      "multiSelect": true
-    }
-  ]
-}
-```
+The mode guides the agent to check available evidence and ask one blocking question at a time. The agent puts its suggested answer first. The agent can continue with obvious, low-risk steps.
 
-## Behavior notes
-
-- Options should be ordered from most recommended to least recommended.
-- Do not include a custom-answer option; the UI adds one.
-- Multi-select results include `selectedOptions` in `details.answers`; tool text and the Review tab show an unambiguous JSON array. The existing comma-joined `answer` field remains available.
-- `ask_question` uses its full keyboard UI in TUI mode and sequential Pi dialogs in RPC mode.
-- RPC multi-select dialogs mark selected choices with ☑ and unselected choices with ☐; choose a checked choice again to remove it, including a custom answer.
-- TUI questions appear over the current screen, temporarily covering the footer and widgets while preserving the editor draft. Long lists scroll by complete wrapped choices with Up/Down.
-- PageUp/PageDown let you read a question, choice, or answer review longer than the screen; Shift+PageUp/Shift+PageDown also work in fullscreen. While typing a custom answer, the list shows only that choice; Escape returns to the list.
-- Saved answers have a one-line preview while choosing; the Review tab retains their full text.
-- Each `ask_question` call has one five-minute limit, shared across all questions and dialogs. Answering part of a question set does not restart the timer.
-- At timeout, the tool returns: “Mitch is currently AFK. Use your best judgement to choose the option Mitch would choose.” It reports `timedOut: true`, not cancellation, and does not select an option or invent a user answer.
-- Saved answers and multi-select choices are preserved on timeout; unfinished custom-answer text is not submitted.
-- The timeout closes the TUI question and stops server-side waiting in RPC mode. RPC clients are responsible for dismissing their own dialogs; Pi does not send a dismissal event.
-- Blank RPC custom answers return to option selection, matching TUI behavior; dismissing the input cancels.
-- Print and JSON modes return a tool error because they cannot collect user input.
-- `/grill-me` state is saved in the current session branch and survives `/reload`.
-- The footer status is cleared when `/grill-me` is disabled.
-- The configured selection-cancel binding cancels and reports cancellation to the model.
-
-## Development
+Use `/grill-me` to toggle the mode. Use `/grill-me off` to disable the mode. Use `/grill-me status` to check the mode.
 
-```bash
-npm install --ignore-scripts
-npm run check:compat # all behavior tests + typecheck + pack dry-run
-```
+The terminal footer shows `grill-mode` when enabled. Pi saves the setting in your current session branch. The setting survives `/reload`.
+
+In print and JSON modes, the agent asks questions in normal text.
 
-The lockfile is a reproducible development snapshot, not a release-qualification target. CI resolves the latest stable official Pi and the maintained fork's `main` commit once per run, then freezes those identities across tests, types, packing, and native Git/npm CLI checks. Shared automation selects each host's actual SDK and companion dependency graph; tests resolve that selected host from the isolated checkout's `node_modules`. Runtime host peers remain wildcard as required by Pi packages, and no production build or `prepare` is needed. Both default fullscreen and regular mode use the host renderer; no additional fork TUI APIs are required.
+## Reference
 
-The repository's main-only `npm-release.yml` pipeline publishes intentional stable version bumps with nonempty versioned changelog notes only after both frozen host qualifications pass. Publishing stays off unless the repository variable `NPM_RELEASE_ENABLED` is `true`; release planning and publishing use the same host inputs.
+[Tool reference](docs/reference.md#tool-shape) covers input examples, result fields, and UI details. [Cooperative TUI answers](docs/reference.md#cooperative-tui-answers) documents the event protocol for trusted extensions.
 
-`tests/native-tui.test.ts` loads the extension through Pi's native SDK and runs `InteractiveMode` with an in-memory `Terminal`. It checks answer, Escape, caller abort in default fullscreen and regular mode, short-terminal choices and editing, paging, resize, and widget overlap, plus draft and keyboard ownership restoration and native grill-mode tree/fork/resume/reload restoration. It does not touch the process terminal or clipboard, use provider credentials, or make model calls. Have `fd` and `rg` on PATH for native TUI initialization without downloads. Unit tests retain timeout, custom answer, multi-select, and grill-mode coverage. `tests/rpc-ui.test.ts` exercises actual bundled-CLI RPC selection, custom input, multi-select, cancellation and reload recovery without provider calls.
+[Development](docs/development.md) covers local tests, host compatibility, and publication. See the [changelog](CHANGELOG.md) for changes. [Report an issue](https://github.com/fitchmultz/pi-ask-question/issues) if the extension fails.
 
-Key file:
+## License
 
-- `extensions/ask-question.ts` — publishable extension implementation
+[MIT](LICENSE), Mitch Fultz.

package/extensions/ask-question.ts

@@ -1,6 +1,8 @@
+import { randomUUID } from "node:crypto";
 import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { CURSOR_MARKER, Editor, Key, matchesKey, sliceByColumn, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi, type AutocompleteItem, type Keybinding } from "@earendil-works/pi-tui";
+import { CURSOR_MARKER, Editor, Key, matchesKey, sliceByColumn, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi, type AutocompleteItem, type Keybinding, type OverlayHandle, type TuiMouseEvent } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
+import { createQuestionObserver, type QuestionObserver } from "./lib/question-observer.ts";
 
 type Question = {
   id?: string;
@@ -44,6 +46,8 @@ const DONE_OPTION = "Done selecting";
 const GRILL_ME_STATE_TYPE = "ask-question.grill-me";
 const GRILL_ME_STATUS_KEY = "ask-question.grill-me";
 const GRILL_ME_ARGUMENTS = ["on", "off", "status"];
+const MAX_REMOTE_ANSWER_LENGTH = 16_384;
+const MAX_REMOTE_REQUESTS = 1024;
 
 function grillMePrompt(useTool: boolean): string {
   return `IMPORTANT: /grill-me mode is active.
@@ -170,10 +174,23 @@ function summarize(questions: NormalizedQuestion[], answers: Map<string, Answer>
 async function askWithKeyboard(
   questions: NormalizedQuestion[],
   ui: ExtensionContext["ui"],
+  pi: ExtensionAPI,
+  observer: QuestionObserver,
+  deadline: number,
   signal?: AbortSignal,
 ): Promise<{ answers: Answer[]; cancelled: boolean }> {
   if (signal?.aborted) return { answers: [], cancelled: true };
+  const promptId = randomUUID();
+  let disposeBridge = () => {};
+  let announceBridge = () => {};
+  let overlayHandle: OverlayHandle | undefined;
   return ui.custom<{ answers: Answer[]; cancelled: boolean }>((tui, theme, keys, done) => {
+    let reservedRows = 0;
+    const widgetKey = `ask-question.${promptId}`;
+    ui.setWidget(widgetKey, () => ({
+      render: () => Array(reservedRows).fill(""),
+      invalidate() {},
+    }));
     const answers = new Map<string, Answer>();
     const multiAnswers = new Map<string, Set<string>>();
     const customAnswers = new Map<string, string>();
@@ -205,6 +222,10 @@ async function askWithKeyboard(
     let reviewScroll: number | undefined;
     let reviewPageRows = 0;
     let maxReviewScroll = 0;
+    let readingContext = false;
+    let contextHintStart = 0;
+    let contextHintEnd = 0;
+    let contextHintWidth = 0;
 
     const submitTab = questions.length;
     const showTabs = questions.length > 1 || questions.some((question) => question.multiSelect);
@@ -216,15 +237,130 @@ async function askWithKeyboard(
       cachedLines = undefined;
       tui.requestRender();
     };
+    const toggleContext = () => {
+      if (!overlayHandle) return;
+      readingContext = !readingContext;
+      if (readingContext) {
+        reservedRows = 0;
+        overlayHandle.unfocus({ target: null });
+      } else {
+        overlayHandle.focus();
+      }
+      refresh();
+    };
+    const unsubscribeInput = tui.addInputListener((data) => {
+      if (matchesKey(data, Key.ctrl("o")) && (readingContext || overlayHandle?.isFocused())) {
+        toggleContext();
+        return { consume: true };
+      }
+      return undefined;
+    });
     let finished = false;
+    let revision = 0;
+    let publishQueued = false;
+    let closed = false;
+    let announced = false;
+    const acceptedRequests = new Set<string>();
+    function waitingState() {
+      const question = current();
+      if (!announced || finished || signal?.aborted || editing || !question || Date.now() >= deadline) return undefined;
+      return {
+        status: "waiting" as const, ...observer.identity(), promptId, questionId: question.id, revision, deadline,
+        question: question.question, options: [...question.options], multiSelect: question.multiSelect,
+      };
+    }
+    const unwatch = observer.watch(waitingState);
+    function publishState() {
+      const waiting = waitingState();
+      if (!waiting) {
+        if (!closed) pi.events.emit("pi-ask-question:state", { status: "closed", promptId });
+        closed = true;
+        return;
+      }
+      closed = false;
+      pi.events.emit("pi-ask-question:state", waiting);
+    }
+    function stateChanged() {
+      revision += 1;
+      if (publishQueued) return;
+      publishQueued = true;
+      queueMicrotask(() => {
+        publishQueued = false;
+        publishState();
+      });
+    }
     const finish = (cancelled: boolean) => {
       if (finished) return;
-      finished = true;
-      signal?.removeEventListener("abort", abort);
+      if (readingContext) overlayHandle?.focus();
+      disposeBridge();
       done({ answers: orderedAnswers(questions, answers), cancelled });
     };
     const abort = () => finish(true);
+    const unsubscribeAnswer = pi.events.on("pi-ask-question:answer", (data) => {
+      if (data === null || typeof data !== "object") return;
+      const request = data as Record<string, unknown>;
+      if (typeof request.requestId !== "string" || !request.requestId.trim() || request.requestId.length > 128) return;
+      // Other live owners on the shared bus must not acknowledge this prompt.
+      if (request.promptId !== promptId) return;
+      const receipt = (status: "answered" | "stale" | "invalid") =>
+        pi.events.emit("pi-ask-question:result", { requestId: request.requestId, promptId, status });
+      const question = current();
+      if (finished || signal?.aborted || editing || !question || request.questionId !== question.id ||
+          request.revision !== revision || acceptedRequests.has(request.requestId) ||
+          !observer.matches(request, deadline) || Date.now() >= deadline) {
+        receipt("stale");
+        return;
+      }
+      const answer = request.answer;
+      const validText = typeof answer === "string" && answer.length <= MAX_REMOTE_ANSWER_LENGTH && Boolean(clean(answer));
+      const validOptions = Array.isArray(answer) && question.multiSelect && answer.length > 0 &&
+        answer.length <= question.options.length && new Set(answer).size === answer.length &&
+        Array.from(answer).every((value) => typeof value === "string" && question.options.includes(value)) &&
+        answer.reduce((size, value) => size + value.length, 0) <= MAX_REMOTE_ANSWER_LENGTH;
+      // ponytail: bound deduplication to 1024 commits per prompt; raise with a higher-volume client.
+      if ((!validText && !validOptions) || acceptedRequests.size >= MAX_REMOTE_REQUESTS) {
+        receipt("invalid");
+        return;
+      }
+      const target = { promptId, questionId: question.id, revision, deadline };
+      acceptedRequests.add(request.requestId);
+      if (typeof answer === "string") {
+        if (question.multiSelect) {
+          saveMultiCustomAnswer(question, answer.trim());
+          moveForwardIfAnswered(question);
+        } else saveSingleAnswer(answer.trim(), true);
+      } else {
+        const selected = selectedSet(question);
+        selected.clear();
+        customAnswers.delete(question.id);
+        for (const choice of answer as string[]) selected.add(choice);
+        syncMultiAnswer(question);
+        moveForwardIfAnswered(question);
+      }
+      if (allAnswered()) finish(false);
+      observer.accept(target, request.requestId, answer as string | string[]);
+      receipt("answered");
+    });
+    const unsubscribeShutdown = pi.on("session_shutdown", abort);
+    disposeBridge = () => {
+      if (finished) return;
+      finished = true;
+      signal?.removeEventListener("abort", abort);
+      unwatch();
+      unsubscribeAnswer();
+      unsubscribeShutdown();
+      unsubscribeInput();
+      ui.setWidget(widgetKey, undefined);
+      publishState();
+    };
     signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) finish(true);
+    // Advertise only after the native host has installed this component.
+    announceBridge = () => {
+      announced = true;
+      if (signal?.aborted) abort();
+      else publishState();
+    };
 
     function moveTab(next: number) {
       tab = (next + questions.length + 1) % (questions.length + 1);
@@ -235,6 +371,7 @@ async function askWithKeyboard(
       reviewScroll = undefined;
       editing = false;
       editor.setText("");
+      stateChanged();
       refresh();
     }
 
@@ -248,6 +385,7 @@ async function askWithKeyboard(
     }
 
     function syncMultiAnswer(question: NormalizedQuestion) {
+      stateChanged();
       const selected = [...selectedSet(question)];
       if (!selected.length) {
         answers.delete(question.id);
@@ -280,6 +418,7 @@ async function askWithKeyboard(
       labelScroll = 0;
       optionScroll = 0;
       questionScroll = 0;
+      stateChanged();
       refresh();
     }
 
@@ -302,6 +441,7 @@ async function askWithKeyboard(
       const question = current();
       if (!question) return;
       answers.set(question.id, { id: question.id, question: question.question, answer, wasCustom });
+      stateChanged();
       if (questions.length === 1) finish(false);
       else moveTab(Math.min(tab + 1, submitTab));
     }
@@ -312,6 +452,7 @@ async function askWithKeyboard(
       editing = false;
       editor.setText("");
       if (!answer || !question) {
+        stateChanged();
         refresh();
         return;
       }
@@ -320,6 +461,7 @@ async function askWithKeyboard(
     };
 
     function handleInput(data: string) {
+      if (finished) return;
       if (editing) {
         if (maxQuestionScroll && matchesKey(data, Key.shift("pageUp"))) {
           questionScroll = Math.max(0, questionScroll - Math.max(1, questionPageRows - 1));
@@ -334,6 +476,7 @@ async function askWithKeyboard(
         if (keys.matches(data, "tui.select.cancel")) {
           editing = false;
           editor.setText("");
+          stateChanged();
           refresh();
           return;
         }
@@ -409,6 +552,13 @@ async function askWithKeyboard(
     }
 
     function render(width: number): string[] {
+      if (readingContext) {
+        const hint = truncateToWidth("ctrl+o return to question • scroll conversation", width, "…");
+        contextHintStart = 0;
+        contextHintEnd = 1;
+        contextHintWidth = visibleWidth(hint);
+        return [theme.fg("dim", hint)];
+      }
       const height = tui.terminal.rows;
       if (cachedLines && cachedWidth === width && cachedHeight === height) return cachedLines;
       if (cachedWidth !== width) {
@@ -533,7 +683,8 @@ async function askWithKeyboard(
             : `${keyText("tui.select.up")}/${keyText("tui.select.down")} options • ${keyText("tui.select.confirm")} select • ${keyText("tui.select.cancel")} cancel`,
         { style: (text) => theme.fg("dim", text) },
       );
-      add(border);
+      const contextHint = truncateToWidth("ctrl+o read context", width, "…");
+      add(`${theme.fg("dim", contextHint)}${theme.fg("accent", "─".repeat(Math.max(0, width - visibleWidth(contextHint))))}`);
 
       if (tab !== submitTab) {
         const questionLines = lines.slice(questionStart, questionEnd);
@@ -603,6 +754,13 @@ async function askWithKeyboard(
       cachedWidth = width;
       cachedHeight = height;
       cachedLines = lines;
+      contextHintStart = lines.length - 1;
+      contextHintEnd = lines.length;
+      contextHintWidth = visibleWidth(contextHint);
+      if (reservedRows !== lines.length) {
+        reservedRows = lines.length;
+        tui.requestRender();
+      }
       return lines;
     }
 
@@ -616,10 +774,26 @@ async function askWithKeyboard(
       },
       render,
       handleInput,
+      handleMouse(event: TuiMouseEvent) {
+        if (event.type === "click" && event.button === "left" &&
+            event.y >= contextHintStart && event.y < contextHintEnd &&
+            event.x < contextHintWidth) {
+          toggleContext();
+          return { handled: true };
+        }
+        return undefined;
+      },
       invalidate: () => { cachedLines = undefined; },
-      dispose: () => signal?.removeEventListener("abort", abort),
+      dispose: () => finish(true),
     };
-  }, { overlay: true, overlayOptions: { width: "100%", maxHeight: "100%", anchor: "bottom-center" } });
+  }, {
+    overlay: true,
+    overlayOptions: { width: "100%", maxHeight: "100%", anchor: "bottom-center" },
+    onHandle: (handle) => {
+      overlayHandle = handle;
+      announceBridge();
+    },
+  }).finally(() => disposeBridge());
 }
 
 async function askWithDialogs(
@@ -711,7 +885,7 @@ function restoreGrillMeState(entries: Iterable<unknown>): boolean {
   return enabled;
 }
 
-const askQuestionTool = defineTool({
+const askQuestionTool = (pi: ExtensionAPI, observer: QuestionObserver) => defineTool({
   name: "ask_question",
   label: "Ask Question",
   description: "Ask the user one or more clarifying questions through pi's UI. After 5 minutes, returns an AFK reply so you can continue using your best judgement.",
@@ -729,12 +903,14 @@ const askQuestionTool = defineTool({
     if (!questions.length) throw new Error("ask_question needs either question or questions[].");
     if (!ctx.hasUI) throw new Error("ask_question needs Pi TUI or RPC UI support.");
 
+    observer.identify(ctx);
     const timeout = new AbortController();
+    const deadline = Date.now() + QUESTION_TIMEOUT_MS;
     const timer = setTimeout(() => timeout.abort(), QUESTION_TIMEOUT_MS);
     const questionSignal = signal ? AbortSignal.any([signal, timeout.signal]) : timeout.signal;
     try {
       const result = ctx.mode === "tui"
-        ? await askWithKeyboard(questions, ctx.ui, questionSignal)
+        ? await askWithKeyboard(questions, ctx.ui, pi, observer, deadline, questionSignal)
         : await askWithDialogs(questions, ctx.ui, questionSignal);
       const answers = new Map(result.answers.map((answer) => [answer.id, answer]));
       const timedOut = result.cancelled && timeout.signal.aborted && !signal?.aborted;
@@ -838,6 +1014,6 @@ function registerGrillMe(pi: ExtensionAPI) {
 }
 
 export default function askQuestion(pi: ExtensionAPI) {
-  pi.registerTool(askQuestionTool);
+  pi.registerTool(askQuestionTool(pi, createQuestionObserver(pi)));
   registerGrillMe(pi);
 }

package/extensions/lib/question-observer.ts

@@ -0,0 +1,93 @@
+import { createHash, randomUUID } from "node:crypto";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+type Target = {
+  promptId: string;
+  questionId: string;
+  revision: number;
+  deadline: number;
+};
+
+type Waiting = Target & {
+  status: "waiting";
+  question: string;
+  options: string[];
+  multiSelect: boolean;
+};
+
+function record(data: unknown): Record<string, unknown> | undefined {
+  return data !== null && typeof data === "object" ? data as Record<string, unknown> : undefined;
+}
+
+function validId(value: unknown): value is string {
+  return typeof value === "string" && Boolean(value.trim()) && value.length <= 128;
+}
+
+// Runtime-local receipts attest application only. They are not a durable answer queue.
+export function createQuestionObserver(pi: ExtensionAPI) {
+  const ownerGeneration = randomUUID();
+  const protocolVersion = 1;
+  const accepted = new Map<string, Target & { requestId: string; answerFingerprint: string }>();
+  let nativeRoot: string | undefined;
+  let mode: ExtensionContext["mode"] | undefined;
+  let current: (() => Waiting | undefined) | undefined;
+
+  const identity = () => ({ protocolVersion, ownerGeneration, nativeRoot });
+  const identify = (ctx: ExtensionContext) => {
+    nativeRoot = ctx.sessionManager.getSessionId();
+    mode = ctx.mode;
+  };
+  const unsubscribeQuery = pi.events.on("pi-ask-question:query", (data) => {
+    const query = record(data);
+    if (!query || !validId(query.queryId)) return;
+    const waiting = query.protocolVersion === protocolVersion && mode === "tui" ? current?.() : undefined;
+    pi.events.emit("pi-ask-question:snapshot", {
+      queryId: query.queryId, ...identity(), mode,
+      status: query.protocolVersion !== protocolVersion || mode !== "tui" ? "unsupported" : "idle",
+      ...waiting,
+    });
+  });
+  const unsubscribeLookup = pi.events.on("pi-ask-question:lookup", (data) => {
+    const query = record(data);
+    if (!query || !validId(query.queryId) || !validId(query.requestId) || typeof query.promptId !== "string") return;
+    const status = query.protocolVersion !== protocolVersion || mode !== "tui" ? "unsupported"
+      : query.ownerGeneration !== ownerGeneration || query.nativeRoot !== nativeRoot ? "stale" : undefined;
+    const receipt = status ? undefined : accepted.get(JSON.stringify([query.promptId, query.requestId]));
+    pi.events.emit("pi-ask-question:lookup-result", {
+      queryId: query.queryId, ...identity(), promptId: query.promptId, requestId: query.requestId,
+      status: status ?? (receipt ? "answered" : "unknown"), ...receipt,
+    });
+  });
+  pi.on("session_start", (_event, ctx) => { identify(ctx); });
+  pi.on("session_shutdown", () => {
+    current = undefined;
+    accepted.clear();
+    unsubscribeQuery();
+    unsubscribeLookup();
+  });
+
+  return {
+    identify,
+    identity,
+    watch(getState: () => Waiting | undefined) {
+      current = getState;
+      return () => { if (current === getState) current = undefined; };
+    },
+    matches(request: Record<string, unknown>, deadline: number) {
+      // Existing unversioned clients keep their original prompt/revision contract.
+      return request.protocolVersion === undefined ||
+        (request.protocolVersion === protocolVersion && request.ownerGeneration === ownerGeneration &&
+          request.nativeRoot === nativeRoot && request.deadline === deadline);
+    },
+    accept(target: Target, requestId: string, answer: string | string[]) {
+      const answerFingerprint = createHash("sha256")
+        .update(JSON.stringify([protocolVersion, ownerGeneration, nativeRoot, target.promptId,
+          target.questionId, target.revision, target.deadline, answer]))
+        .digest("hex");
+      accepted.set(JSON.stringify([target.promptId, requestId]), { ...target, requestId, answerFingerprint });
+      if (accepted.size > 1024) accepted.delete(accepted.keys().next().value!);
+    },
+  };
+}
+
+export type QuestionObserver = ReturnType<typeof createQuestionObserver>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitchmultz/pi-ask-question",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Pi extension that adds an interactive ask_question tool and /grill-me pressure-test mode",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",
   "license": "MIT",
@@ -63,8 +63,8 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "1.0.0",
-    "@earendil-works/pi-tui": "1.0.0",
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@earendil-works/pi-tui": "1.4.0",
     "@types/node": "24.19.1",
     "typebox": "1.3.34",
     "typescript": "7.0.2"
@@ -72,5 +72,10 @@
   "packageManager": "npm@12.2.0",
   "publishConfig": {
     "access": "public"
+  },
+  "overrides": {
+    "@earendil-works/pi-coding-agent": {
+      "undici": "8.12.3"
+    }
   }
 }