feat(tool): decouple AskUserQuestion into standalone question channel

Add a dedicated question service and overlay instead of routing
AskUserQuestion through the permission system. Wire tab/arrow keybindings
in the standalone prompt and clarify the tool prompt with an explicit
parameter-structure example to reduce first-try schema errors.

src/components/question/QuestionPrompt.tsx

@@ -0,0 +1,245 @@
+import { c as _c } from "react/compiler-runtime";
+import React, { useCallback, useState } from "react";
+import type { Question } from "../../tools/AskUserQuestionTool/AskUserQuestionTool.js";
+import { questionService, type QuestionRequest } from "../../services/question/questionService.js";
+import { useMultipleChoiceState } from "../permissions/AskUserQuestionPermissionRequest/use-multiple-choice-state.js";
+import { QuestionView } from "../permissions/AskUserQuestionPermissionRequest/QuestionView.js";
+import { SubmitQuestionsView } from "../permissions/AskUserQuestionPermissionRequest/SubmitQuestionsView.js";
+import { useRegisterOverlay } from "../../context/overlayContext.js";
+import { useKeybindings } from "../../keybindings/useKeybinding.js";
+import type { PermissionDecision } from "../../utils/permissions/PermissionResult.js";
+
+const NO_PERMISSION: PermissionDecision = { behavior: "allow" } as PermissionDecision;
+
+type Props = {
+  request: QuestionRequest;
+  onResolved: () => void;
+};
+
+/**
+ * Standalone question overlay (decoupled from the permission system).
+ * Renders the same choice UI as AskUserQuestion but resolves the
+ * questionService pending request on reply/reject.
+ */
+export function QuestionPrompt(props: Props) {
+  const $ = _c(40);
+  const { request, onResolved } = props;
+  const questions = request.questions as unknown as Question[];
+  const [answers, setAnswers] = useState<Record<string, string>>({});
+  const state = useMultipleChoiceState();
+  const {
+    currentQuestionIndex,
+    questionStates,
+    isInTextInput,
+    nextQuestion,
+    prevQuestion,
+    updateQuestionState,
+    setAnswer,
+    setTextInputMode,
+  } = state;
+  const currentQuestion =
+    currentQuestionIndex < questions.length ? questions[currentQuestionIndex] : null;
+  const isInSubmitView = currentQuestionIndex === questions.length;
+  const allQuestionsAnswered = questions.every(q => q?.question && !!answers[q.question]);
+  const hideSubmitTab = questions.length === 1 && !questions[0]?.multiSelect;
+  const maxIndex = hideSubmitTab ? questions.length - 1 : questions.length;
+  useRegisterOverlay("question", true);
+  let t0;
+  if ($[0] !== answers || $[1] !== questions) {
+    t0 = questions.every(q_0 => q_0?.question && !!answers[q_0.question]) ?? false;
+    $[0] = answers;
+    $[1] = questions;
+    $[2] = t0;
+  } else {
+    t0 = $[2];
+  }
+  let t1;
+  if ($[3] !== answers) {
+    t1 = (q_1: string, a: string | string[], textInput?: string, shouldAdvance?: boolean) => {
+      const isMulti = Array.isArray(a);
+      const value = isMulti ? (a as string[]).join(", ") : (a as string);
+      const next = { ...answers, [q_1]: value };
+      setAnswers(next);
+      setAnswer(q_1, value, shouldAdvance);
+      if (!isMulti && shouldAdvance !== false && questions.length === 1) {
+        void reply([value]);
+      }
+    };
+    $[3] = answers;
+    $[4] = t1;
+  } else {
+    t1 = $[4];
+  }
+  const handleAnswer = t1;
+  let t2;
+  if ($[5] === Symbol.for("react.memo_cache_sentinel")) {
+    t2 = (q_2: string) => {
+      const next = { ...answers };
+      delete next[q_2];
+      setAnswers(next);
+    };
+    $[5] = t2;
+  } else {
+    t2 = $[5];
+  }
+  const handleCancel = t2;
+  let t3;
+  if ($[6] !== answers || $[7] !== questions) {
+    t3 = (final: "submit" | "cancel") => {
+      if (final === "cancel") {
+        handleCancelReply();
+        return;
+      }
+      const result = questions.map(q_3 => {
+        const a = answers[q_3.question];
+        return a ? (q_3.multiSelect ? a.split(", ") : [a]) : [];
+      });
+      void reply(result);
+    };
+    $[6] = answers;
+    $[7] = questions;
+    $[8] = t3;
+  } else {
+    t3 = $[8];
+  }
+  const handleFinal = t3;
+  let t4;
+  if ($[9] === Symbol.for("react.memo_cache_sentinel")) {
+    t4 = () => {
+      questionService.reject(request.id);
+      onResolved();
+    };
+    $[9] = t4;
+  } else {
+    t4 = $[9];
+  }
+  const handleCancelReply = t4;
+  let t5;
+  if ($[10] !== answers || $[11] !== questions) {
+    t5 = async (result: string[][]) => {
+      questionService.reply({ requestID: request.id, answers: result });
+      onResolved();
+    };
+    $[10] = answers;
+    $[11] = questions;
+    $[12] = t5;
+  } else {
+    t5 = $[12];
+  }
+  const reply = t5;
+  let t6;
+  if ($[13] !== currentQuestionIndex || $[14] !== maxIndex || $[15] !== nextQuestion) {
+    t6 = () => {
+      if (currentQuestionIndex < maxIndex) nextQuestion();
+    };
+    $[13] = currentQuestionIndex;
+    $[14] = maxIndex;
+    $[15] = nextQuestion;
+    $[16] = t6;
+  } else {
+    t6 = $[16];
+  }
+  const handleTabNext = t6;
+  let t7;
+  if ($[17] !== currentQuestionIndex || $[18] !== prevQuestion) {
+    t7 = () => {
+      if (currentQuestionIndex > 0) prevQuestion();
+    };
+    $[17] = currentQuestionIndex;
+    $[18] = prevQuestion;
+    $[19] = t7;
+  } else {
+    t7 = $[19];
+  }
+  const handleTabPrev = t7;
+  useKeybindings(
+    { "tabs:previous": handleTabPrev, "tabs:next": handleTabNext },
+    { context: "Tabs", isActive: !(isInTextInput && !isInSubmitView) },
+  );
+  if (currentQuestion) {
+    let t8;
+    if (
+      $[20] !== answers ||
+      $[21] !== currentQuestion ||
+      $[22] !== currentQuestionIndex ||
+      $[23] !== handleAnswer ||
+      $[24] !== handleCancel ||
+      $[25] !== handleTabNext ||
+      $[26] !== handleTabPrev ||
+      $[27] !== hideSubmitTab ||
+      $[28] !== nextQuestion ||
+      $[29] !== questions ||
+      $[30] !== questionStates ||
+      $[31] !== setTextInputMode ||
+      $[32] !== updateQuestionState
+    ) {
+      t8 = (
+        <QuestionView
+          question={currentQuestion}
+          questions={questions}
+          currentQuestionIndex={currentQuestionIndex}
+          answers={answers}
+          questionStates={questionStates}
+          hideSubmitTab={hideSubmitTab}
+          onUpdateQuestionState={updateQuestionState}
+          onAnswer={handleAnswer}
+          onTextInputFocus={setTextInputMode}
+          onCancel={handleCancelReply}
+          onSubmit={nextQuestion}
+          onTabPrev={handleTabPrev}
+          onTabNext={handleTabNext}
+          onRespondToClaude={handleCancelReply}
+          onFinishPlanInterview={handleCancelReply}
+        />
+      );
+      $[20] = answers;
+      $[21] = currentQuestion;
+      $[22] = currentQuestionIndex;
+      $[23] = handleAnswer;
+      $[24] = handleCancel;
+      $[25] = handleTabNext;
+      $[26] = handleTabPrev;
+      $[27] = hideSubmitTab;
+      $[28] = nextQuestion;
+      $[29] = questions;
+      $[30] = questionStates;
+      $[31] = setTextInputMode;
+      $[32] = updateQuestionState;
+      $[33] = t8;
+    } else {
+      t8 = $[33];
+    }
+    return t8;
+  }
+  if (isInSubmitView) {
+    let t9;
+    if (
+      $[34] !== allQuestionsAnswered ||
+      $[35] !== answers ||
+      $[36] !== currentQuestionIndex ||
+      $[37] !== questions ||
+      $[38] !== handleFinal
+    ) {
+      t9 = (
+        <SubmitQuestionsView
+          questions={questions}
+          currentQuestionIndex={currentQuestionIndex}
+          answers={answers}
+          allQuestionsAnswered={allQuestionsAnswered}
+          permissionResult={NO_PERMISSION}
+          onFinalResponse={handleFinal}
+        />
+      );
+      $[34] = allQuestionsAnswered;
+      $[35] = answers;
+      $[36] = currentQuestionIndex;
+      $[37] = questions;
+      $[38] = handleFinal;
+      $[39] = t9;
+    } else {
+      t9 = $[39];
+    }
+    return t9;
+  }
+  return null;
+}

src/screens/REPL.tsx

@@ -1556,6 +1556,19 @@ export function REPL({
       reject: (error: Error) => void
     }>
   >([])
+  const [questionRequest, setQuestionRequest] =
+    useState<import('../services/question/questionService.js').QuestionRequest | null>(null)
+  useEffect(() => {
+    const { questionService } = require('../services/question/questionService.js') as typeof import('../services/question/questionService.js')
+    const onAsked = (request: import('../services/question/questionService.js').QuestionRequest) => {
+      setQuestionRequest(request)
+    }
+    questionService.events.on('asked', onAsked)
+    return () => {
+      questionService.events.off('asked', onAsked)
+    }
+  }, [])
+
 
   // Track bridge cleanup functions for sandbox permission requests so the
   // local dialog handler can cancel the remote prompt when the local user
@@ -2672,6 +2685,7 @@ export function REPL({
     | 'sandbox-permission'
     | 'tool-permission'
     | 'prompt'
+    | 'question'
     | 'worker-sandbox-permission'
     | 'elicitation'
     | 'cost'
@@ -2706,6 +2720,7 @@ export function REPL({
     if (allowDialogsWithAnimation && toolUseConfirmQueue[0])
       return 'tool-permission'
     if (allowDialogsWithAnimation && promptQueue[0]) return 'prompt'
+    if (allowDialogsWithAnimation && questionRequest) return 'question'
     // Worker sandbox permission prompts (network access) from swarm workers
     if (allowDialogsWithAnimation && workerSandboxPermissions.queue[0])
       return 'worker-sandbox-permission'
@@ -2789,7 +2804,8 @@ export function REPL({
   useEffect(() => {
     if (!isLoading) return
 
-    const isPaused = focusedInputDialog === 'tool-permission'
+    const isPaused =
+      focusedInputDialog === 'tool-permission' || focusedInputDialog === 'question'
     const now = Date.now()
 
     if (isPaused && pauseStartTimeRef.current === null) {
@@ -2813,8 +2829,12 @@ export function REPL({
   // no 1-frame flash of the wrong scroll position.
   const prevDialogRef = useRef(focusedInputDialog)
   useLayoutEffect(() => {
-    const was = prevDialogRef.current === 'tool-permission'
-    const now = focusedInputDialog === 'tool-permission'
+    const was =
+      prevDialogRef.current === 'tool-permission' ||
+      prevDialogRef.current === 'question'
+    const now =
+      focusedInputDialog === 'tool-permission' ||
+      focusedInputDialog === 'question'
     if (was !== now) repinScroll()
     prevDialogRef.current = focusedInputDialog
   }, [focusedInputDialog, repinScroll])
@@ -6062,6 +6082,19 @@ export function REPL({
       />
     ) : null
 
+  // Standalone question overlay (decoupled from the permission system).
+  // Reuses the AskUserQuestion choice UI but resolves questionService.
+  const QuestionPromptBox = require('../components/question/QuestionPrompt.js').QuestionPrompt
+
+  const questionOverlay =
+    focusedInputDialog === 'question' && questionRequest ? (
+      <QuestionPromptBox
+        key={questionRequest.id}
+        request={questionRequest}
+        onResolved={() => setQuestionRequest(null)}
+      />
+    ) : null
+
   // Narrow terminals: companion collapses to a one-liner that REPL stacks
   // on its own row (above input in fullscreen, below in scrollback) instead
   // of row-beside. Wide terminals keep the row layout with sprite on the right.
@@ -6150,7 +6183,7 @@ export function REPL({
       >
         <FullscreenLayout
           scrollRef={scrollRef}
-          overlay={toolPermissionOverlay}
+          overlay={toolPermissionOverlay || questionOverlay}
           bottomFloat={
             feature('BUDDY') && companionVisible && !companionNarrow ? (
               <CompanionFloatingBubble />

src/services/question/questionService.ts

@@ -0,0 +1,102 @@
+import { EventEmitter } from '../../ink/events/emitter.js'
+
+export interface QuestionOption {
+  label: string
+  description?: string
+  preview?: string
+}
+
+export interface QuestionInfo {
+  question: string
+  header?: string
+  options: QuestionOption[]
+  multiSelect?: boolean
+  custom?: boolean
+}
+
+export interface QuestionRequest {
+  id: string
+  questions: QuestionInfo[]
+  tool?: {
+    messageID: string
+    callID: string
+  }
+}
+
+export type QuestionAnswer = string[]
+
+export type ReplyInput = {
+  requestID: string
+  answers: QuestionAnswer[]
+}
+
+interface Pending {
+  readonly request: QuestionRequest
+  resolve: (answers: ReadonlyArray<QuestionAnswer>) => void
+  reject: (reason?: Error) => void
+}
+
+class RejectedError extends Error {
+  constructor() {
+    super('The user dismissed this question')
+    this.name = 'QuestionV2.RejectedError'
+  }
+}
+
+/**
+ * Standalone question channel, decoupled from the permission system.
+ * Mirrors opencode's QuestionV2 service: a tool's `call` awaits `ask`,
+ * the TUI renders an independent overlay, and `reply`/`reject` resolve it.
+ */
+class QuestionService {
+  private pending = new Map<string, Pending>()
+  private seq = 0
+  readonly events = new EventEmitter()
+
+  private nextID(): string {
+    this.seq += 1
+    return `que_${Date.now().toString(36)}_${this.seq}`
+  }
+
+  ask(questions: QuestionInfo[]): Promise<ReadonlyArray<QuestionAnswer>> {
+    const id = this.nextID()
+    const request: QuestionRequest = { id, questions }
+    return new Promise<ReadonlyArray<QuestionAnswer>>((resolve, reject) => {
+      this.pending.set(id, { request, resolve, reject })
+      this.events.emit('asked', request)
+    })
+  }
+
+  reply(input: ReplyInput): boolean {
+    const existing = this.pending.get(input.requestID)
+    if (!existing) return false
+    this.events.emit('replied', {
+      requestID: existing.request.id,
+      answers: input.answers.map(a => [...a]),
+    })
+    existing.resolve(input.answers)
+    this.pending.delete(input.requestID)
+    return true
+  }
+
+  reject(requestID: string): boolean {
+    const existing = this.pending.get(requestID)
+    if (!existing) return false
+    this.events.emit('rejected', { requestID: existing.request.id })
+    existing.reject(new RejectedError())
+    this.pending.delete(requestID)
+    return true
+  }
+
+  list(): QuestionRequest[] {
+    return Array.from(this.pending.values(), p => p.request)
+  }
+
+  current(): QuestionRequest | undefined {
+    const all = this.list()
+    return all[all.length - 1]
+  }
+}
+
+export const questionService = new QuestionService()
+export { RejectedError }

src/tools/AskUserQuestionTool/AskUserQuestionTool.tsx

@@ -10,6 +10,7 @@ import { Box, Text } from '../../ink.js';
 import type { Tool } from '../../Tool.js';
 import { buildTool, type ToolDef } from '../../Tool.js';
 import { lazySchema } from '../../utils/lazySchema.js';
+import { questionService, type QuestionInfo } from '../../services/question/questionService.js';
 import { ASK_USER_QUESTION_TOOL_CHIP_WIDTH, ASK_USER_QUESTION_TOOL_NAME, ASK_USER_QUESTION_TOOL_PROMPT, DESCRIPTION, PREVIEW_FEATURE_PROMPT } from './prompt.js';
 const questionOptionSchema = lazySchema(() => z.object({
   label: z.string().describe('The display text for this option that the user will see and select. Should be concise (1-5 words) and clearly describe the choice.'),
@@ -181,8 +182,7 @@ export const AskUserQuestionTool: Tool<InputSchema, Output> = buildTool({
   },
   async checkPermissions(input) {
     return {
-      behavior: 'ask' as const,
-      message: 'Answer questions?',
+      behavior: 'allow' as const,
       updatedInput: input
     };
   },
@@ -208,9 +208,27 @@ export const AskUserQuestionTool: Tool<InputSchema, Output> = buildTool({
   },
   async call({
     questions,
-    answers = {},
     annotations
   }, _context) {
+    const asked: QuestionInfo[] = questions.map(q => ({
+      question: q.question,
+      header: q.header,
+      options: q.options.map(o => ({
+        label: o.label,
+        description: o.description,
+        preview: o.preview
+      })),
+      multiSelect: q.multiSelect,
+      custom: true
+    }))
+    const result = await questionService.ask(asked)
+    const answers: Record<string, string> = {}
+    questions.forEach((q, i) => {
+      const answer = result[i]
+      if (answer && answer.length > 0) {
+        answers[q.question] = q.multiSelect ? answer.join(', ') : answer[0]
+      }
+    })
     return {
       data: {
         questions,

src/tools/AskUserQuestionTool/prompt.ts

@@ -39,6 +39,36 @@ Usage notes:
 - Users will always be able to select "Other" to provide custom text input
 - Use multiSelect: true to allow multiple answers to be selected for a question
 - If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label
+- Do NOT add an "Other" option yourself; it is provided automatically.
+
+Parameter structure (IMPORTANT):
+- \`questions\` is an array of 1-4 question objects.
+- Each option MUST be an object with a \`label\` (short text) and a \`description\` (what it means). Never pass options as plain strings.
+- Do not add any top-level keys other than \`questions\`.
+
+Example (ask two questions at once):
+\`\`\`json
+{
+  "questions": [
+    {
+      "question": "How should image rendering be implemented?",
+      "header": "Image",
+      "options": [
+        { "label": "Terminal inline", "description": "Render images inline in the terminal" },
+        { "label": "External viewer", "description": "Open images in an external previewer" }
+      ]
+    },
+    {
+      "question": "How should logs be stored?",
+      "header": "Logging",
+      "options": [
+        { "label": "File", "description": "Write logs to a file" },
+        { "label": "Database", "description": "Write logs to a database" }
+      ]
+    }
+  ]
+}
+\`\`\`
 
 Plan mode note: In plan mode, use this tool to clarify requirements or choose between approaches BEFORE finalizing your plan. Do NOT use this tool to ask "Is my plan ready?" or "Should I proceed?" - use ${EXIT_PLAN_MODE_TOOL_NAME} for plan approval. IMPORTANT: Do not reference "the plan" in your questions (e.g., "Do you have feedback about the plan?", "Does the plan look good?") because the user cannot see the plan in the UI until you call ${EXIT_PLAN_MODE_TOOL_NAME}. If you need plan approval, use ${EXIT_PLAN_MODE_TOOL_NAME} instead.
 `