fix review findings: polish ask-user question

2026-07-07 14:57:06 +08:00
parent 510e80e447
commit cebf781d69
51 changed files with 665 additions and 419 deletions
--- a/packages/core/user-interaction/README.md
+++ b/packages/core/user-interaction/README.md
@@ -11,11 +11,13 @@ Abstract user-interaction seam. It owns `ctx.userInteraction`, the service a mod

 ### Key Types

- `AskUserQuestionRequest` — `{ question, header?, options?, allowCustom?, agent?, signal? }`.
- `AskUserQuestionOption` — `{ label, value?, description?, recommended? }`.
- `AskUserQuestionAnswer` — `{ answer, option? }`.
+- `AskUserQuestionRequest` — `{ questions: [{ id, question, header?, options?, multiSelect? }], agent?, signal? }`.
+- `AskUserQuestionOption` — `{ label, description? }`.
+- `AskUserQuestionAnswer` — `{ answers: [{ id, selected, custom? }] }`.
 - `UserInteractionProvider` — UI implementation with `ask(request)`.
- `UserInteractionError` — `HarnessError` subclass with codes such as `NO_PROVIDER`, `DUPLICATE_PROVIDER`, and `ASK_ABORTED`.
+- `UserInteractionError` — `HarnessError` subclass with codes such as `EMPTY_QUESTIONS`, `NO_PROVIDER`, `DUPLICATE_PROVIDER`, and `ASK_ABORTED`.
+
+When an answer includes `custom`, `selected` is empty; custom text is an override rather than a supplement to selected choices.

 ## Role

--- a/packages/core/user-interaction/src/index.ts
+++ b/packages/core/user-interaction/src/index.ts
@@ -21,36 +21,48 @@ declare module 'cordis' {
 export interface AskUserQuestionOption {
  /** User-facing label. */
  label: string
-  /** Value returned to the model when selected. Defaults to `label`. */
-  value?: string
  /** Optional extra context rendered by capable UIs. */
  description?: string
-  /** Marks the recommended/default option. */
-  recommended?: boolean
 }

-/** Request for a human answer. */
-export interface AskUserQuestionRequest {
+/** One question in an ask_user_question request. */
+export interface AskUserQuestionItem {
+  /** Stable model-provided question id, echoed in the answer. */
+  id: string
  /** The question to display. */
  question: string
  /** Optional short heading/group label. */
  header?: string
  /** Optional choices the UI can render as a menu. */
  options?: AskUserQuestionOption[]
-  /** Whether free-form answers are accepted. Defaults to `true`. */
-  allowCustom?: boolean
+  /** Whether more than one option may be selected. Defaults to single-select. */
+  multiSelect?: boolean
+}
+
+/** Request for a human answer. */
+export interface AskUserQuestionRequest {
+  /** Questions to display. */
+  questions: AskUserQuestionItem[]
  /** Calling agent, when the request came from an agent tool call. */
  agent?: Agent
  /** Abort signal for the owning tool/step. */
  signal?: AbortSignal
 }

+/** Answer to one question. */
+export interface AskUserQuestionAnswerItem {
+  /** The answered question id. */
+  id: string
+  /** Selected option labels. Empty when the answer is purely custom text. */
+  selected: string[]
+  /** Optional free-text "Other" answer. */
+  custom?: string
+}
+
 /** The human's answer. */
 export interface AskUserQuestionAnswer {
-  /** Model-facing answer text. */
-  answer: string
-  /** The selected option, when the answer came from `options`. */
-  option?: AskUserQuestionOption
+  /** Structured answers keyed by question id. */
+  answers: AskUserQuestionAnswerItem[]
 }

 /** UI-side provider for user questions. */
@@ -96,13 +108,16 @@ export class UserInteractionService extends Service {
  /**
   * Ask the active UI provider and wait for the user's answer.
   *
-   * @param request Question, options, owner agent, and abort signal.
+   * @param request Questions, owner agent, and abort signal.
   * @returns The answer chosen or typed by the human.
   */
  async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer> {
    if (request.signal?.aborted) {
      throw new UserInteractionError('ask_user_question was aborted before the user answered', 'ASK_ABORTED')
    }
+    if (request.questions.length === 0) {
+      throw new UserInteractionError('ask_user_question requires at least one question', 'EMPTY_QUESTIONS')
+    }
    if (this.provider === undefined) {
      throw new UserInteractionError('no user-interaction provider is registered', 'NO_PROVIDER')
    }
--- a/packages/core/user-interaction/tests/user-interaction.spec.ts
+++ b/packages/core/user-interaction/tests/user-interaction.spec.ts
@@ -12,7 +12,7 @@ function provider(answer = 'approved'): UserInteractionProvider & { seen: AskUse
    seen,
    async ask(request) {
      seen.push(request)
-      return { answer }
+      return { answers: [{ id: request.questions[0]?.id ?? 'missing', selected: [answer] }] }
    },
  }
 }
@@ -24,17 +24,17 @@ describe('UserInteractionService', () => {
    const p = provider('yes')
    ctx.userInteraction.registerProvider(p)

-    const result = await ctx.userInteraction.ask({ question: 'Proceed?' })
+    const result = await ctx.userInteraction.ask({ questions: [{ id: 'confirm', question: 'Proceed?' }] })

-    expect(result).toEqual({ answer: 'yes' })
-    expect(p.seen).toEqual([{ question: 'Proceed?' }])
+    expect(result).toEqual({ answers: [{ id: 'confirm', selected: ['yes'] }] })
+    expect(p.seen).toEqual([{ questions: [{ id: 'confirm', question: 'Proceed?' }] }])
  })

  it('rejects ask requests when no provider is registered', async () => {
    const ctx = new Context()
    await ctx.plugin(UserInteractionService)

-    await expect(ctx.userInteraction.ask({ question: 'Proceed?' }))
+    await expect(ctx.userInteraction.ask({ questions: [{ id: 'confirm', question: 'Proceed?' }] }))
      .rejects.toMatchObject({ name: 'UserInteractionError', code: 'NO_PROVIDER' })
  })

@@ -47,7 +47,7 @@ describe('UserInteractionService', () => {
    dispose()
    dispose()

-    await expect(ctx.userInteraction.ask({ question: 'Proceed?' }))
+    await expect(ctx.userInteraction.ask({ questions: [{ id: 'confirm', question: 'Proceed?' }] }))
      .rejects.toMatchObject({ code: 'NO_PROVIDER' })
  })

@@ -63,13 +63,24 @@ describe('UserInteractionService', () => {
  it('fails before reaching the provider when the signal is already aborted', async () => {
    const ctx = new Context()
    await ctx.plugin(UserInteractionService)
-    const p = { ask: vi.fn(async () => ({ answer: 'too late' })) }
+    const p = { ask: vi.fn(async () => ({ answers: [{ id: 'confirm', selected: ['too late'] }] })) }
    ctx.userInteraction.registerProvider(p)
    const controller = new AbortController()
    controller.abort()

-    await expect(ctx.userInteraction.ask({ question: 'Proceed?', signal: controller.signal }))
+    await expect(ctx.userInteraction.ask({ questions: [{ id: 'confirm', question: 'Proceed?' }], signal: controller.signal }))
      .rejects.toMatchObject({ code: 'ASK_ABORTED' })
    expect(p.ask).not.toHaveBeenCalled()
  })
+
+  it('rejects empty question batches before reaching the provider', async () => {
+    const ctx = new Context()
+    await ctx.plugin(UserInteractionService)
+    const p = { ask: vi.fn(async () => ({ answers: [] })) }
+    ctx.userInteraction.registerProvider(p)
+
+    await expect(ctx.userInteraction.ask({ questions: [] }))
+      .rejects.toMatchObject({ name: 'UserInteractionError', code: 'EMPTY_QUESTIONS' })
+    expect(p.ask).not.toHaveBeenCalled()
+  })
 })
--- a/packages/ui/acp/README.md
+++ b/packages/ui/acp/README.md
@@ -30,7 +30,7 @@ The `initialize` handshake reports a fixed server identity (`agentInfo: { name:
 | `session/prompt` | `agent.send()` | supports ACP `text` and `resource_link` blocks; rejects image/audio/embedded resource and empty prompts; one in-flight prompt PER session (independent); settles on the OWNING turn's end (a turn that ends in `error` rejects the RPC) |
 | `session/cancel` | `agent.cancel()` | the queue-aware cancel: aborts a running step, clears queued + steering work, and drops a turn about to start, then settles the prompt `cancelled` — for ONLY that session (a cancel never touches another session's stream or prompt) |
 | `session/update` | `session/event` | `agent_message_chunk` (text-delta), `agent_thought_chunk` (reasoning-delta), `user_message_chunk` (load replay), `tool_call`/`tool_call_update` (the render intent — a `card`-tagged `ToolCallView`/`ToolResultView` — owned by the TOOL via `presentCall`/`presentResult`, which the bridge switches on to build the wire shape — see Tool-call presentation) |
-| `elicitation/create` | `ctx.userInteraction.ask()` | maps `ask_user_question` requests to ACP form elicitations; recommended options become defaults, option descriptions are shown in enum titles, optionless requests remain free-form even when `allowCustom` is false |
+| `elicitation/create` | `ctx.userInteraction.ask()` | maps `ask_user_question` questions to ACP form elicitations; option descriptions are shown in enum titles, `multi_select` uses ACP array enums, optionless requests use a required `custom` field, and a non-empty custom answer overrides any selected choice |

 ## Multi-session

--- a/packages/ui/acp/src/index.ts
+++ b/packages/ui/acp/src/index.ts
@@ -77,6 +77,8 @@ import type {} from '@deepseek-ai/dsh-session-persistence'
 import {
  UserInteractionError,
  type AskUserQuestionAnswer,
+  type AskUserQuestionAnswerItem,
+  type AskUserQuestionItem,
  type AskUserQuestionOption,
  type AskUserQuestionRequest,
 } from '@deepseek-ai/dsh-user-interaction'
@@ -120,27 +122,12 @@ function sameWorkspaceCwd(left: string, right: string): boolean {
  return resolvePath(left) === resolvePath(right)
 }

-function optionAnswer(option: AskUserQuestionOption): string {
-  return option.value ?? option.label
-}
-
-function orderedOptions(options: readonly AskUserQuestionOption[] | undefined): AskUserQuestionOption[] {
-  return [...(options ?? [])].sort((a, b) => Number(Boolean(b.recommended)) - Number(Boolean(a.recommended)))
-}
-
 function optionDescription(option: AskUserQuestionOption): string {
  return option.description === undefined
    ? option.label
    : `${option.label}: ${option.description}`
 }

-function selectedOption(
-  options: readonly AskUserQuestionOption[],
-  answer: string,
-): AskUserQuestionOption | undefined {
-  return options.find(option => optionAnswer(option) === answer)
-}
-
 function requireStringContent(
  content: Record<string, ElicitationContentValue> | null | undefined,
  key: string,
@@ -177,62 +164,74 @@ function withAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined): Pro

 function elicitationForQuestion(
  sessionId: SessionId,
-  request: AskUserQuestionRequest,
+  question: AskUserQuestionItem,
  options: AskUserQuestionOption[],
 ): CreateElicitationRequest {
-  const allowCustom = options.length === 0 || (request.allowCustom ?? true)
-  const title = request.header ?? 'Question'
+  const title = question.header ?? 'Question'
  if (options.length === 0) {
    return {
      sessionId,
      mode: 'form',
-      message: request.question,
+      message: question.question,
      requestedSchema: {
        type: 'object',
        title,
        properties: {
-          answer: { type: 'string', title: request.question },
+          custom: { type: 'string', title: question.question },
        },
-        required: ['answer'],
+        required: ['custom'],
      },
    }
  }

  const choiceOptions: EnumOption[] = options.map(option => ({
-    const: optionAnswer(option),
+    const: option.label,
    title: optionDescription(option),
  }))
-  const recommended = options.find(option => option.recommended)
+  const choice = question.multiSelect === true
+    ? {
+      type: 'array' as const,
+      title: question.question,
+      description: 'Choose one or more options, or fill a custom answer below.',
+      items: {
+        anyOf: choiceOptions,
+      },
+    }
+    : {
+      type: 'string' as const,
+      title: question.question,
+      description: 'Choose one option, or fill a custom answer below.',
+      oneOf: choiceOptions,
+    }
  return {
    sessionId,
    mode: 'form',
-    message: request.question,
+    message: question.question,
    requestedSchema: {
      type: 'object',
      title,
      properties: {
-        choice: {
+        choice,
+        custom: {
          type: 'string',
-          title: request.question,
-          description: allowCustom ? 'Choose one option, or fill a custom answer below.' : 'Choose one option.',
-          oneOf: choiceOptions,
-          ...recommended !== undefined ? { default: optionAnswer(recommended) } : {},
+          title: 'Custom answer',
+          description: 'Optional free-form answer. Leave empty to use the selected option.',
        },
-        ...allowCustom
-          ? {
-            custom_answer: {
-              type: 'string' as const,
-              title: 'Custom answer',
-              description: 'Optional free-form answer. Leave empty to use the selected option.',
-            },
-          }
-          : {},
      },
-      required: allowCustom ? [] : ['choice'],
+      required: [],
    },
  }
 }

+function stringArrayContent(
+  content: Record<string, ElicitationContentValue> | null | undefined,
+  key: string,
+): string[] {
+  const value = content?.[key]
+  if (Array.isArray(value)) return value.filter((item): item is string => typeof item === 'string' && item.length > 0)
+  return typeof value === 'string' && value.length > 0 ? [value] : []
+}
+
 /** Plugin config: the agent template ACP sessions are created from. */
 export interface AcpConfig {
  /** Model name for created agents (must have a registered adapter). */
@@ -373,25 +372,30 @@ export function apply(ctx: Context, config: AcpConfig): void {
      if (sessionId === undefined) {
        throw new UserInteractionError('ACP user question has no matching session', 'NO_SESSION')
      }
-      const options = orderedOptions(request.options)
-      const response = await withAbort(conn.unstable_createElicitation(
-        elicitationForQuestion(sessionId, request, options),
-      ), request.signal).catch((error: unknown) => {
-        if (error instanceof UserInteractionError) throw error
-        throw new UserInteractionError('ACP elicitation request failed', 'ASK_FAILED', { cause: error })
-      })
-      if (response.action !== 'accept') {
-        throw new UserInteractionError('ask_user_question was cancelled by the user', 'ASK_CANCELLED')
+      const answers: AskUserQuestionAnswerItem[] = []
+      for (const question of request.questions) {
+        const options = question.options ?? []
+        const response = await withAbort(conn.unstable_createElicitation(
+          elicitationForQuestion(sessionId, question, options),
+        ), request.signal).catch((error: unknown) => {
+          if (error instanceof UserInteractionError) throw error
+          throw new UserInteractionError('ACP elicitation request failed', 'ASK_FAILED', { cause: error })
+        })
+        if (response.action !== 'accept') {
+          throw new UserInteractionError('ask_user_question was cancelled by the user', 'ASK_CANCELLED')
+        }
+        const custom = requireStringContent(response.content, 'custom')
+        const selected = stringArrayContent(response.content, 'choice')
+        if (custom === undefined && selected.length === 0) {
+          throw new UserInteractionError('ask_user_question returned no answer', 'NO_ANSWER')
+        }
+        answers.push({
+          id: question.id,
+          selected: custom === undefined ? selected : [],
+          ...custom !== undefined ? { custom } : {},
+        })
      }
-      const customAnswer = requireStringContent(response.content, 'custom_answer')
-      if (customAnswer !== undefined) return { answer: customAnswer }
-
-      const answer = requireStringContent(response.content, options.length === 0 ? 'answer' : 'choice')
-      if (answer === undefined) {
-        throw new UserInteractionError('ask_user_question returned no answer', 'NO_ANSWER')
-      }
-      const option = selectedOption(options, answer)
-      return option === undefined ? { answer } : { answer, option }
+      return { answers }
    },
  })

--- a/packages/ui/acp/tests/bridge.spec.ts
+++ b/packages/ui/acp/tests/bridge.spec.ts
@@ -59,18 +59,20 @@ describe('acp bridge', () => {
      withAskUser: true,
      script: [
        toolCallResponse('ask-1', 'ask_user_question', {
-          header: 'Project config',
-          question: 'Which language should I use?',
-          options: [
-            { label: 'TypeScript', value: 'ts', description: 'Good for UI apps' },
-            { label: 'Python', value: 'py', description: 'Good for scripts', recommended: true },
-          ],
-          allow_custom: false,
+          questions: [{
+            id: 'language',
+            header: 'Project config',
+            question: 'Which language should I use?',
+            options: [
+              { label: 'TypeScript', description: 'Good for UI apps' },
+              { label: 'Python', description: 'Good for scripts' },
+            ],
+          }],
        }),
        textResponse('Python it is.'),
      ],
    })
-    harness.onElicitation = () => ({ action: 'accept', content: { choice: 'py' } })
+    harness.onElicitation = () => ({ action: 'accept', content: { choice: 'Python' } })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })

@@ -86,18 +88,20 @@ describe('acp bridge', () => {
        title: 'Project config',
        properties: {
          choice: {
-            default: 'py',
            oneOf: [
-              { const: 'py', title: 'Python: Good for scripts' },
-              { const: 'ts', title: 'TypeScript: Good for UI apps' },
+              { const: 'TypeScript', title: 'TypeScript: Good for UI apps' },
+              { const: 'Python', title: 'Python: Good for scripts' },
            ],
          },
+          custom: { type: 'string' },
        },
-        required: ['choice'],
+        required: [],
      },
    })
    const toolResult = harness.ctx.agents.get(AgentId(sessionId))!.session.events.find(event => event.type === 'tool/result')
-    expect(JSON.stringify(toolResult)).toContain('py')
+    const toolResultBlock = toolResult?.type === 'tool/result' ? toolResult.data.content[0] : undefined
+    const toolResultText = toolResultBlock?.type === 'text' ? toolResultBlock.text : undefined
+    expect(toolResultText).toBe('{"answers":[{"id":"language","selected":["Python"]}]}')
  })

  it('routes optionless ask_user_question through an ACP free-form answer field', async () => {
@@ -106,13 +110,12 @@ describe('acp bridge', () => {
      withAskUser: true,
      script: [
        toolCallResponse('ask-1', 'ask_user_question', {
-          question: 'What should I name it?',
-          allow_custom: false,
+          questions: [{ id: 'name', question: 'What should I name it?' }],
        }),
        textResponse('Name recorded.'),
      ],
    })
-    harness.onElicitation = () => ({ action: 'accept', content: { answer: 'apollo' } })
+    harness.onElicitation = () => ({ action: 'accept', content: { custom: 'apollo' } })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })

@@ -120,8 +123,8 @@ describe('acp bridge', () => {

    expect(harness.elicitationRequests[0]).toMatchObject({
      requestedSchema: {
-        properties: { answer: { type: 'string', title: 'What should I name it?' } },
-        required: ['answer'],
+        properties: { custom: { type: 'string', title: 'What should I name it?' } },
+        required: ['custom'],
      },
    })
    const toolResult = harness.ctx.agents.get(AgentId(sessionId))!.session.events.find(event => event.type === 'tool/result')
@@ -130,18 +133,21 @@ describe('acp bridge', () => {

  it('supports ACP custom answers alongside choices', async () => {
    harness = await makeBridgeHarness({ storageDir, withAskUser: true })
-    harness.onElicitation = () => ({ action: 'accept', content: { custom_answer: 'Use Zig' } })
+    harness.onElicitation = () => ({ action: 'accept', content: { custom: 'Use Zig' } })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
    const agent = harness.ctx.agents.get(AgentId(sessionId))!

    const result = await harness.ctx.userInteraction.ask({
      agent,
-      question: 'Which language?',
-      options: [{ label: 'TypeScript' }],
+      questions: [{
+        id: 'language',
+        question: 'Which language?',
+        options: [{ label: 'TypeScript' }],
+      }],
    })

-    expect(result).toEqual({ answer: 'Use Zig' })
+    expect(result).toEqual({ answers: [{ id: 'language', selected: [], custom: 'Use Zig' }] })
    expect(harness.elicitationRequests[0]).toMatchObject({
      requestedSchema: {
        properties: {
@@ -149,26 +155,46 @@ describe('acp bridge', () => {
            description: 'Choose one option, or fill a custom answer below.',
            oneOf: [{ const: 'TypeScript', title: 'TypeScript' }],
          },
-          custom_answer: { type: 'string' },
+          custom: { type: 'string' },
        },
        required: [],
      },
    })
  })

-  it('returns raw ACP answers when they do not match a provided option', async () => {
+  it('treats ACP custom answers as overriding selected choices', async () => {
    harness = await makeBridgeHarness({ storageDir, withAskUser: true })
-    harness.onElicitation = () => ({ action: 'accept', content: { choice: 'something else' } })
+    harness.onElicitation = () => ({ action: 'accept', content: { choice: 'TypeScript', custom: 'Use Zig' } })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
    const agent = harness.ctx.agents.get(AgentId(sessionId))!

    await expect(harness.ctx.userInteraction.ask({
      agent,
-      question: 'Pick',
-      options: [{ label: 'A', value: 'a' }],
-      allowCustom: false,
-    })).resolves.toEqual({ answer: 'something else' })
+      questions: [{
+        id: 'language',
+        question: 'Which language?',
+        options: [{ label: 'TypeScript' }],
+      }],
+    })).resolves.toEqual({ answers: [{ id: 'language', selected: [], custom: 'Use Zig' }] })
+  })
+
+  it('supports ACP multi-select answers', async () => {
+    harness = await makeBridgeHarness({ storageDir, withAskUser: true })
+    harness.onElicitation = () => ({ action: 'accept', content: { choice: ['Tests', 'Docs'] } })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+    const agent = harness.ctx.agents.get(AgentId(sessionId))!
+
+    await expect(harness.ctx.userInteraction.ask({
+      agent,
+      questions: [{
+        id: 'targets',
+        question: 'Pick',
+        options: [{ label: 'Tests' }, { label: 'Docs' }],
+        multiSelect: true,
+      }],
+    })).resolves.toEqual({ answers: [{ id: 'targets', selected: ['Tests', 'Docs'] }] })
  })

  it('reports ACP ask-user routing and answer failures as structured errors', async () => {
@@ -177,21 +203,21 @@ describe('acp bridge', () => {
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
    const agent = harness.ctx.agents.get(AgentId(sessionId))!

-    await expect(harness.ctx.userInteraction.ask({ question: 'No agent?' }))
+    await expect(harness.ctx.userInteraction.ask({ questions: [{ id: 'x', question: 'No agent?' }] }))
      .rejects.toMatchObject({ name: 'UserInteractionError', code: 'NO_AGENT' })
-    await expect(harness.ctx.userInteraction.ask({ agent: { id: 'other' } as typeof agent, question: 'No session?' }))
+    await expect(harness.ctx.userInteraction.ask({ agent: { id: 'other' } as typeof agent, questions: [{ id: 'x', question: 'No session?' }] }))
      .rejects.toMatchObject({ code: 'NO_SESSION' })

    harness.onElicitation = () => ({ action: 'cancel' })
-    await expect(harness.ctx.userInteraction.ask({ agent, question: 'Cancel?' }))
+    await expect(harness.ctx.userInteraction.ask({ agent, questions: [{ id: 'x', question: 'Cancel?' }] }))
      .rejects.toMatchObject({ code: 'ASK_CANCELLED' })

    harness.onElicitation = () => ({ action: 'accept', content: {} })
-    await expect(harness.ctx.userInteraction.ask({ agent, question: 'Empty?' }))
+    await expect(harness.ctx.userInteraction.ask({ agent, questions: [{ id: 'x', question: 'Empty?' }] }))
      .rejects.toMatchObject({ code: 'NO_ANSWER' })

    harness.onElicitation = () => { throw new Error('client boom') }
-    await expect(harness.ctx.userInteraction.ask({ agent, question: 'Client fails?', signal: new AbortController().signal }))
+    await expect(harness.ctx.userInteraction.ask({ agent, questions: [{ id: 'x', question: 'Client fails?' }], signal: new AbortController().signal }))
      .rejects.toMatchObject({ code: 'ASK_FAILED' })
  })

@@ -203,7 +229,7 @@ describe('acp bridge', () => {

    const alreadyAborted = new AbortController()
    alreadyAborted.abort()
-    await expect(harness.ctx.userInteraction.ask({ agent, question: 'Already?', signal: alreadyAborted.signal }))
+    await expect(harness.ctx.userInteraction.ask({ agent, questions: [{ id: 'x', question: 'Already?' }], signal: alreadyAborted.signal }))
      .rejects.toMatchObject({ code: 'ASK_ABORTED' })

    let abortedReads = 0
@@ -216,18 +242,18 @@ describe('acp bridge', () => {
      reason: undefined,
      throwIfAborted() {},
    } as AbortSignal
-    await expect(harness.ctx.userInteraction.ask({ agent, question: 'Raced?', signal: racingAbort }))
+    await expect(harness.ctx.userInteraction.ask({ agent, questions: [{ id: 'x', question: 'Raced?' }], signal: racingAbort }))
      .rejects.toMatchObject({ code: 'ASK_ABORTED' })

-    let release: ((value: { action: 'accept'; content: { answer: string } }) => void) | undefined
+    let release: ((value: { action: 'accept'; content: { custom: string } }) => void) | undefined
    harness.onElicitation = () => new Promise((resolve) => { release = resolve })
    const pendingAbort = new AbortController()
-    const ask = harness.ctx.userInteraction.ask({ agent, question: 'Pending?', signal: pendingAbort.signal })
+    const ask = harness.ctx.userInteraction.ask({ agent, questions: [{ id: 'x', question: 'Pending?' }], signal: pendingAbort.signal })
    await new Promise(resolve => setImmediate(resolve))
    pendingAbort.abort()

    await expect(ask).rejects.toMatchObject({ code: 'ASK_ABORTED' })
-    release?.({ action: 'accept', content: { answer: 'too late' } })
+    release?.({ action: 'accept', content: { custom: 'too late' } })
  })

  it('allows multiple concurrent sessions, each with a distinct id', async () => {
--- a/packages/ui/stdio-agent/src/stdio-chat.ts
+++ b/packages/ui/stdio-agent/src/stdio-chat.ts
@@ -23,6 +23,8 @@ import { AgentId } from '@deepseek-ai/dsh-agent'
 import {
  UserInteractionError,
  type AskUserQuestionAnswer,
+  type AskUserQuestionAnswerItem,
+  type AskUserQuestionItem,
  type AskUserQuestionOption,
  type AskUserQuestionRequest,
 } from '@deepseek-ai/dsh-user-interaction'
@@ -63,27 +65,20 @@ function isTTYPair(input: Readable, output: Writable): boolean {
  return Boolean((input as { isTTY?: boolean }).isTTY && (output as { isTTY?: boolean }).isTTY)
 }

-function optionAnswer(option: AskUserQuestionOption): string {
-  return option.value ?? option.label
-}
-
-function displayOptions(options: AskUserQuestionOption[] = []): AskUserQuestionOption[] {
-  return options
-    .map((option, index) => ({ option, index }))
-    .sort((left, right) => {
-      if (left.option.recommended === right.option.recommended) return left.index - right.index
-      return left.option.recommended ? -1 : 1
-    })
-    .map(({ option }) => option)
-}
-
 interface PendingQuestion {
  request: AskUserQuestionRequest
+  questionIndex: number
+  answers: AskUserQuestionAnswerItem[]
  resolve(answer: AskUserQuestionAnswer): void
  reject(error: unknown): void
  onAbort: () => void
 }

+type OptionSelection =
+  | { kind: 'selected'; options: AskUserQuestionOption[] }
+  | { kind: 'custom' }
+  | { kind: 'invalid' }
+
 /**
 * The plugin body, parameterized over its I/O runtime. `apply` is the thin
 * production wrapper that binds the real `process` streams; tests call this
@@ -205,12 +200,16 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt
      if (status === 'idle') maybeExit()
    })

+    const activeQuestionItem = (pending: PendingQuestion): AskUserQuestionItem =>
+      pending.request.questions[pending.questionIndex] as AskUserQuestionItem
+
    const renderQuestion = (pending: PendingQuestion): void => {
-      const { request } = pending
+      const question = activeQuestionItem(pending)
+      const options = question.options ?? []
      output.write('\n')
-      output.write(request.header ? `[${request.header}] ${request.question}\n` : `[question] ${request.question}\n`)
-      displayOptions(request.options).forEach((option, index) => {
-        output.write(`  ${index + 1}. ${option.label}${option.recommended ? ' (recommended)' : ''}\n`)
+      output.write(question.header ? `[${question.header}] ${question.question}\n` : `${question.question}\n`)
+      options.forEach((option, index) => {
+        output.write(`  ${index + 1}. ${option.label}\n`)
        if (option.description) output.write(`     ${option.description}\n`)
      })
      output.write('> ')
@@ -249,41 +248,64 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt
      }
    }

-    const finishQuestion = (pending: PendingQuestion, answer: AskUserQuestionAnswer): void => {
-      removeAbortListener(pending)
+    const finishQuestion = (pending: PendingQuestion): void => {
      activeQuestion = undefined
-      pending.resolve(answer)
+      removeAbortListener(pending)
+      pending.resolve({ answers: pending.answers })
      output.write('\n')
      startNextQuestion()
    }

+    const answerCurrentQuestion = (pending: PendingQuestion, answer: AskUserQuestionAnswerItem): void => {
+      pending.answers.push(answer)
+      pending.questionIndex += 1
+      if (pending.questionIndex >= pending.request.questions.length) {
+        finishQuestion(pending)
+        return
+      }
+      renderQuestion(pending)
+    }
+
+    const selectedOptions = (text: string, options: AskUserQuestionOption[], multiSelect: boolean): OptionSelection => {
+      if (text === '') return { kind: 'invalid' }
+      if (!multiSelect) {
+        if (!/^\d+$/.test(text)) return { kind: 'custom' }
+        const selected = options[Number(text) - 1]
+        return selected === undefined ? { kind: 'invalid' } : { kind: 'selected', options: [selected] }
+      }
+      const indices = text.split(/[,\s]+/).filter(Boolean)
+      if (indices.length === 0) return { kind: 'invalid' }
+      if (indices.some(part => !/^\d+$/.test(part))) return { kind: 'custom' }
+      const uniqueIndices = [...new Set(indices)]
+      const selected = uniqueIndices.map(part => options[Number(part) - 1])
+      return selected.some(option => option === undefined)
+        ? { kind: 'invalid' }
+        : { kind: 'selected', options: selected as AskUserQuestionOption[] }
+    }
+
    const answerQuestion = (line: string): void => {
      const pending = activeQuestion as PendingQuestion
+      const question = activeQuestionItem(pending)

      const text = line.trim()
-      const options = displayOptions(pending.request.options)
-      const selectedIndex = /^\d+$/.test(text) ? Number(text) - 1 : -1
-      const selected = selectedIndex >= 0 ? options[selectedIndex] : undefined
-      if (selected !== undefined) {
-        finishQuestion(pending, { answer: optionAnswer(selected), option: selected })
+      const options = question.options ?? []
+      const selection = options.length > 0
+        ? selectedOptions(text, options, question.multiSelect ?? false)
+        : { kind: text === '' ? 'invalid' : 'custom' } as OptionSelection
+      if (selection.kind === 'selected') {
+        answerCurrentQuestion(pending, { id: question.id, selected: selection.options.map(option => option.label) })
        return
      }

-      const recommended = options.find(option => option.recommended)
-      if (text === '' && recommended !== undefined) {
-        finishQuestion(pending, { answer: optionAnswer(recommended), option: recommended })
-        return
-      }
-
-      const allowCustom = options.length === 0 || (pending.request.allowCustom ?? true)
-      if (allowCustom && text !== '') {
-        finishQuestion(pending, { answer: text })
+      if (selection.kind === 'custom' && text !== '') {
+        answerCurrentQuestion(pending, { id: question.id, selected: [], custom: text })
        return
      }

      output.write(options.length > 0
        ? 'Please enter one of the option numbers'
-          + (allowCustom ? ' or a custom answer' : '')
+          + (question.multiSelect ? ' (comma or space separated)' : '')
+          + ' or a custom answer'
          + '.\n> '
        : 'Please enter an answer.\n> ')
    }
@@ -298,6 +320,8 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt
        return new Promise<AskUserQuestionAnswer>((resolve, reject) => {
          const pending: PendingQuestion = {
            request,
+            questionIndex: 0,
+            answers: [],
            resolve,
            reject,
            onAbort: () => {
--- a/packages/ui/stdio-agent/tests/stdio-chat.spec.ts
+++ b/packages/ui/stdio-agent/tests/stdio-chat.spec.ts
@@ -1,4 +1,4 @@
-import { Readable } from 'node:stream'
+import { Readable, Writable } from 'node:stream'
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
@@ -107,6 +107,30 @@ describe('createStdioChat rendering', () => {
    // And it drives the default agent id 'main'.
  })

+  it('detects readline terminal mode from both stream TTY flags', async () => {
+    for (const [inputTTY, outputTTY] of [[true, false], [true, true]] as const) {
+      const ctx = new Context()
+      await ctx.plugin(AgentRegistry)
+      await ctx.plugin(UserInteractionService)
+      let text = ''
+      const output = new Writable({
+        write(chunk, _encoding, callback) {
+          text += String(chunk)
+          callback()
+        },
+      }) as Writable & { isTTY?: boolean }
+      const { runtime } = makeRuntime({ output })
+      ;(runtime.input as Readable & { isTTY?: boolean }).isTTY = inputTTY
+      output.isTTY = outputTTY
+      const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+        createStdioChat(inner, CONFIG, runtime)
+      }, { inject: ['agents', 'userInteraction'] }))
+
+      expect(text).toContain('hi there')
+      await fiber.dispose()
+    }
+  })
+
  it('renders text-delta chunks verbatim', async () => {
    const { ctx, out } = await setup()
    ctx.emit('session/event', makeSession('main'), chunkEvent({ type: 'text-delta', index: 0, text: 'hello' }))
@@ -273,150 +297,229 @@ describe('createStdioChat input', () => {
    ctx.agents.register(agent)

    const answer = ctx.userInteraction.ask({
-      header: 'Confirm',
-      question: 'Proceed with the edit?',
-      options: [{ label: 'Yes', value: 'Proceed', description: 'Apply the edit now.', recommended: true }],
+      questions: [{
+        id: 'confirm',
+        header: 'Confirm',
+        question: 'Proceed with the edit?',
+        options: [{ label: 'Yes', description: 'Apply the edit now.' }],
+      }],
    })
    await new Promise(r => setImmediate(r))
    input.feed('Use a smaller change')

-    await expect(answer).resolves.toEqual({ answer: 'Use a smaller change' })
+    await expect(answer).resolves.toEqual({ answers: [{ id: 'confirm', selected: [], custom: 'Use a smaller change' }] })
    expect(agent.sent).toEqual([])
    expect(out.text()).toContain('[Confirm] Proceed with the edit?')
-    expect(out.text()).toContain('1. Yes (recommended)')
+    expect(out.text()).toContain('1. Yes')
    expect(out.text()).toContain('Apply the edit now.')
  })

  it('answers a pending user question by numeric option selection', async () => {
    const { ctx, input } = await setup()
    const answer = ctx.userInteraction.ask({
-      question: 'Which mode?',
-      options: [
-        { label: 'Safe', value: 'Use safe mode', recommended: true },
-        { label: 'Fast', value: 'Use fast mode' },
-      ],
-      allowCustom: false,
+      questions: [{
+        id: 'mode',
+        question: 'Which mode?',
+        options: [
+          { label: 'Safe' },
+          { label: 'Fast' },
+        ],
+      }],
    })
    await new Promise(r => setImmediate(r))
    input.feed('2')

    await expect(answer).resolves.toEqual({
-      answer: 'Use fast mode',
-      option: { label: 'Fast', value: 'Use fast mode' },
+      answers: [{ id: 'mode', selected: ['Fast'] }],
    })
  })

-  it('renders recommended options first and selects by displayed number', async () => {
+  it('renders options in input order and selects by displayed number', async () => {
    const { ctx, input, out } = await setup()
    const answer = ctx.userInteraction.ask({
-      question: 'Which topic?',
-      options: [
-        { label: 'Hobbies', value: 'hobbies' },
-        { label: 'Work', value: 'work', description: 'Questions about current projects.' },
-        { label: 'Casual', value: 'casual', recommended: true, description: 'Easy conversation.' },
-      ],
-      allowCustom: false,
+      questions: [{
+        id: 'topic',
+        question: 'Which topic?',
+        options: [
+          { label: 'Hobbies' },
+          { label: 'Work', description: 'Questions about current projects.' },
+          { label: 'Casual', description: 'Easy conversation.' },
+        ],
+      }],
    })
    await new Promise(r => setImmediate(r))

    expect(out.text()).toContain([
-      '[question] Which topic?',
-      '  1. Casual (recommended)',
-      '     Easy conversation.',
-      '  2. Hobbies',
-      '  3. Work',
+      'Which topic?',
+      '  1. Hobbies',
+      '  2. Work',
      '     Questions about current projects.',
+      '  3. Casual',
+      '     Easy conversation.',
    ].join('\n'))
-    input.feed('1')
+    input.feed('3')

    await expect(answer).resolves.toEqual({
-      answer: 'casual',
-      option: { label: 'Casual', value: 'casual', recommended: true, description: 'Easy conversation.' },
+      answers: [{ id: 'topic', selected: ['Casual'] }],
    })
  })

-  it('uses the recommended option when the user submits an empty answer', async () => {
+  it('answers a multi-select question with multiple numeric selections', async () => {
    const { ctx, input } = await setup()
    const answer = ctx.userInteraction.ask({
-      question: 'Continue?',
-      options: [
-        { label: 'No' },
-        { label: 'Yes', value: 'Continue', recommended: true },
-      ],
-      allowCustom: false,
+      questions: [{
+        id: 'targets',
+        question: 'What should I update?',
+        options: [{ label: 'Tests' }, { label: 'Docs' }, { label: 'Code' }],
+        multiSelect: true,
+      }],
    })
    await new Promise(r => setImmediate(r))
-    input.feed('')
+    input.feed('1 1, 3')

    await expect(answer).resolves.toEqual({
-      answer: 'Continue',
-      option: { label: 'Yes', value: 'Continue', recommended: true },
+      answers: [{ id: 'targets', selected: ['Tests', 'Code'] }],
    })
  })

-  it('re-prompts when options are required and the input is invalid', async () => {
-    const { ctx, input, out } = await setup()
+  it('accepts non-numeric multi-select input as a custom answer', async () => {
+    const { ctx, input } = await setup()
    const answer = ctx.userInteraction.ask({
-      question: 'Which mode?',
-      options: [{ label: 'Safe' }],
-      allowCustom: false,
+      questions: [{
+        id: 'targets',
+        question: 'What should I update?',
+        options: [{ label: 'Tests' }, { label: 'Docs' }],
+        multiSelect: true,
+      }],
    })
    await new Promise(r => setImmediate(r))
-    input.feed('custom')
+    input.feed('the release notes')
+
+    await expect(answer).resolves.toEqual({
+      answers: [{ id: 'targets', selected: [], custom: 'the release notes' }],
+    })
+  })
+
+  it('asks every question in a batch and returns answers by id', async () => {
+    const { ctx, input, out } = await setup()
+    const answer = ctx.userInteraction.ask({
+      questions: [
+        { id: 'language', question: 'Which language?', options: [{ label: 'Python' }, { label: 'TypeScript' }] },
+        { id: 'note', question: 'Any note?' },
+      ],
+    })
    await new Promise(r => setImmediate(r))
-    expect(out.text()).toContain('Please enter one of the option numbers.')
+    input.feed('2')
+    await new Promise(r => setImmediate(r))
+    expect(out.text()).toContain('\nAny note?\n')
+    input.feed('ship today')
+
+    await expect(answer).resolves.toEqual({
+      answers: [
+        { id: 'language', selected: ['TypeScript'] },
+        { id: 'note', selected: [], custom: 'ship today' },
+      ],
+    })
+  })
+
+  it('re-prompts when option input is invalid', async () => {
+    const { ctx, input, out } = await setup()
+    const answer = ctx.userInteraction.ask({
+      questions: [{
+        id: 'mode',
+        question: 'Which mode?',
+        options: [{ label: 'Safe' }],
+        multiSelect: true,
+      }],
+    })
+    await new Promise(r => setImmediate(r))
+    input.feed('2')
+    await new Promise(r => setImmediate(r))
+    expect(out.text()).toContain('Please enter one of the option numbers (comma or space separated) or a custom answer.')
    input.feed('1')

    await expect(answer).resolves.toEqual({
-      answer: 'Safe',
-      option: { label: 'Safe' },
+      answers: [{ id: 'mode', selected: ['Safe'] }],
    })
  })

-  it('re-prompts with custom-answer guidance when options also allow free-form input', async () => {
+  it('re-prompts when single-select option input is out of range', async () => {
    const { ctx, input, out } = await setup()
    const answer = ctx.userInteraction.ask({
-      question: 'Which mode?',
-      options: [{ label: 'Safe' }],
+      questions: [{
+        id: 'mode',
+        question: 'Which mode?',
+        options: [{ label: 'Safe' }],
+      }],
+    })
+    await new Promise(r => setImmediate(r))
+    input.feed('2')
+    await new Promise(r => setImmediate(r))
+    expect(out.text()).toContain('Please enter one of the option numbers or a custom answer.')
+    input.feed('1')
+
+    await expect(answer).resolves.toEqual({
+      answers: [{ id: 'mode', selected: ['Safe'] }],
+    })
+  })
+
+  it('re-prompts when multi-select input contains no option numbers', async () => {
+    const { ctx, input, out } = await setup()
+    const answer = ctx.userInteraction.ask({
+      questions: [{
+        id: 'mode',
+        question: 'Which mode?',
+        options: [{ label: 'Safe' }],
+        multiSelect: true,
+      }],
+    })
+    await new Promise(r => setImmediate(r))
+    input.feed(',')
+    await new Promise(r => setImmediate(r))
+    expect(out.text()).toContain('Please enter one of the option numbers (comma or space separated) or a custom answer.')
+    input.feed('1')
+
+    await expect(answer).resolves.toEqual({
+      answers: [{ id: 'mode', selected: ['Safe'] }],
+    })
+  })
+
+  it('re-prompts when an option question receives an empty answer', async () => {
+    const { ctx, input, out } = await setup()
+    const answer = ctx.userInteraction.ask({
+      questions: [{
+        id: 'mode',
+        question: 'Which mode?',
+        options: [{ label: 'Safe' }],
+      }],
    })
    await new Promise(r => setImmediate(r))
    input.feed('')
    await new Promise(r => setImmediate(r))
    expect(out.text()).toContain('Please enter one of the option numbers or a custom answer.')
-    input.feed('Use custom mode')
+    input.feed('1')

-    await expect(answer).resolves.toEqual({ answer: 'Use custom mode' })
+    await expect(answer).resolves.toEqual({
+      answers: [{ id: 'mode', selected: ['Safe'] }],
+    })
  })

-  it('re-prompts when a free-form question receives an empty answer', async () => {
+  it('re-prompts when a question receives an empty answer', async () => {
    const { ctx, input, out } = await setup()
-    const answer = ctx.userInteraction.ask({ question: 'What should I use?' })
+    const answer = ctx.userInteraction.ask({ questions: [{ id: 'path', question: 'What should I use?' }] })
    await new Promise(r => setImmediate(r))
    input.feed('')
    await new Promise(r => setImmediate(r))
    expect(out.text()).toContain('Please enter an answer.')
    input.feed('Use defaults')

-    await expect(answer).resolves.toEqual({ answer: 'Use defaults' })
-  })
-
-  it('accepts free-form input for an optionless question even when allowCustom is false', async () => {
-    const { ctx, input } = await setup()
-    const answer = ctx.userInteraction.ask({
-      question: 'Choose?',
-      allowCustom: false,
-    })
-    await new Promise(r => setImmediate(r))
-
-    input.feed('Use the default path')
-
-    await expect(answer).resolves.toEqual({ answer: 'Use the default path' })
+    await expect(answer).resolves.toEqual({ answers: [{ id: 'path', selected: [], custom: 'Use defaults' }] })
  })

  it('rejects an active question when its signal aborts', async () => {
    const { ctx } = await setup()
    const controller = new AbortController()
-    const answer = ctx.userInteraction.ask({ question: 'Continue?', signal: controller.signal })
+    const answer = ctx.userInteraction.ask({ questions: [{ id: 'continue', question: 'Continue?' }], signal: controller.signal })
    const rejected = expect(answer).rejects.toMatchObject({ code: 'ASK_ABORTED' })
    await new Promise(r => setImmediate(r))

@@ -428,40 +531,40 @@ describe('createStdioChat input', () => {
  it('continues to the next queued question when the active question aborts', async () => {
    const { ctx, input, out } = await setup()
    const controller = new AbortController()
-    const first = ctx.userInteraction.ask({ question: 'First?', signal: controller.signal })
+    const first = ctx.userInteraction.ask({ questions: [{ id: 'first', question: 'First?' }], signal: controller.signal })
    const firstRejected = expect(first).rejects.toMatchObject({ code: 'ASK_ABORTED' })
-    const second = ctx.userInteraction.ask({ question: 'Second?' })
+    const second = ctx.userInteraction.ask({ questions: [{ id: 'second', question: 'Second?' }] })
    await new Promise(r => setImmediate(r))

    controller.abort()
    await firstRejected
    await new Promise(r => setImmediate(r))
-    expect(out.text()).toContain('[question] Second?')
+    expect(out.text()).toContain('\nSecond?\n')
    input.feed('second answer')

-    await expect(second).resolves.toEqual({ answer: 'second answer' })
+    await expect(second).resolves.toEqual({ answers: [{ id: 'second', selected: [], custom: 'second answer' }] })
  })

  it('skips a queued question whose signal aborted before it became active', async () => {
    const { ctx, input, out } = await setup()
    const controller = new AbortController()
-    const first = ctx.userInteraction.ask({ question: 'First?' })
-    const second = ctx.userInteraction.ask({ question: 'Second?', signal: controller.signal })
+    const first = ctx.userInteraction.ask({ questions: [{ id: 'first', question: 'First?' }] })
+    const second = ctx.userInteraction.ask({ questions: [{ id: 'second', question: 'Second?' }], signal: controller.signal })
    const secondRejected = expect(second).rejects.toMatchObject({ code: 'ASK_ABORTED' })
    await new Promise(r => setImmediate(r))

    controller.abort()
    input.feed('first answer')

-    await expect(first).resolves.toEqual({ answer: 'first answer' })
+    await expect(first).resolves.toEqual({ answers: [{ id: 'first', selected: [], custom: 'first answer' }] })
    await secondRejected
-    expect(out.text()).not.toContain('[question] Second?')
+    expect(out.text()).not.toContain('\nSecond?\n')
  })

  it('rejects active and queued questions when the UI is disposed', async () => {
    const { ctx, fiber } = await setup()
-    const active = ctx.userInteraction.ask({ question: 'Active?' })
-    const queued = ctx.userInteraction.ask({ question: 'Queued?' })
+    const active = ctx.userInteraction.ask({ questions: [{ id: 'active', question: 'Active?' }] })
+    const queued = ctx.userInteraction.ask({ questions: [{ id: 'queued', question: 'Queued?' }] })
    const activeRejected = expect(active).rejects.toMatchObject({ code: 'ASK_ABORTED' })
    const queuedRejected = expect(queued).rejects.toMatchObject({ code: 'ASK_ABORTED' })
    await new Promise(r => setImmediate(r))
@@ -474,8 +577,8 @@ describe('createStdioChat input', () => {

  it('rejects active and queued questions when stdin closes before the user answers', async () => {
    const { ctx, input, exit } = await setup()
-    const active = ctx.userInteraction.ask({ question: 'Active?' })
-    const queued = ctx.userInteraction.ask({ question: 'Queued?' })
+    const active = ctx.userInteraction.ask({ questions: [{ id: 'active', question: 'Active?' }] })
+    const queued = ctx.userInteraction.ask({ questions: [{ id: 'queued', question: 'Queued?' }] })
    const activeRejected = expect(active).rejects.toMatchObject({ code: 'ASK_ABORTED' })
    const queuedRejected = expect(queued).rejects.toMatchObject({ code: 'ASK_ABORTED' })
    await new Promise(r => setImmediate(r))
@@ -494,7 +597,7 @@ describe('createStdioChat input', () => {
    await new Promise(r => setImmediate(r))
    const before = out.text()

-    const answer = ctx.userInteraction.ask({ question: 'Too late?' })
+    const answer = ctx.userInteraction.ask({ questions: [{ id: 'late', question: 'Too late?' }] })

    await expect(answer).rejects.toMatchObject({ code: 'ASK_ABORTED' })
    expect(out.text()).toBe(before)
--- a/packages/ui/tool-ask-user/README.md
+++ b/packages/ui/tool-ask-user/README.md
@@ -6,12 +6,14 @@ Model-facing `ask_user_question` tool over `ctx.userInteraction`. It lets the mo

 `ask_user_question` accepts:

- `question` — required question text.
+- `questions` — required non-empty array of question objects.
+- `id` — required stable id on each question, echoed in the answer.
+- `question` — required question text for each question.
 - `header` — optional short heading.
- `options` — optional choices with `label`, `value`, `description`, and `recommended`.
- `allow_custom` — whether free-form answers are allowed; defaults to the provider's normal `true` behavior.
+- `options` — optional choices with `label` and `description`.
+- `multi_select` — whether that question may return more than one selected option.

-The tool calls `ctx.userInteraction.ask()` and returns the selected option value or custom answer as a text tool result.
+The tool calls `ctx.userInteraction.ask()` and returns JSON text shaped as `{ "answers": [{ "id": "...", "selected": ["..."], "custom": "..." }] }`. `selected` contains option labels; `custom` is present only for a free-form answer and overrides selected choices.

 ## Role

--- a/packages/ui/tool-ask-user/src/index.ts
+++ b/packages/ui/tool-ask-user/src/index.ts
@@ -8,56 +8,64 @@

 import type { Context } from 'cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type {} from '@deepseek-ai/dsh-user-interaction'
+import '@deepseek-ai/dsh-user-interaction'

 export const name = 'tool-ask-user'
 export const inject = ['tools', 'userInteraction']

 const description = 'Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. '
-  + 'Use options when possible; mark the recommended option when one is safest.'
+  + 'Send one or more questions, each with a stable id that will be echoed in the answer.'

 export function apply(ctx: Context): void {
  ctx.tools.register(defineTool({
    name: 'ask_user_question',
    description,
    parameters: {
-      header: {
-        type: 'string',
-        description: 'Optional short heading for the question, such as "Confirm" or "Choose Mode".',
-      },
-      question: {
-        type: 'string',
-        required: true,
-        description: 'The specific question to ask the user.',
-      },
-      options: {
+      questions: {
        type: 'array',
-        description: 'Optional mutually exclusive choices to show the user.',
+        required: true,
+        description: 'Questions to ask the user before continuing.',
        items: {
          type: 'object',
          properties: {
-            label: { type: 'string', required: true, description: 'Short user-facing option label.' },
-            value: { type: 'string', description: 'Answer text returned to you if this option is selected. Defaults to label.' },
-            description: { type: 'string', description: 'One sentence explaining the tradeoff or impact.' },
-            recommended: { type: 'boolean', description: 'True for the recommended/default option.' },
+            id: { type: 'string', required: true, description: 'Stable id for this question; echoed in the answer.' },
+            question: { type: 'string', required: true, description: 'The specific question to ask the user.' },
+            header: {
+              type: 'string',
+              description: 'Optional short heading for the question, such as "Confirm" or "Choose Mode".',
+            },
+            options: {
+              type: 'array',
+              description: 'Optional choices to show the user.',
+              items: {
+                type: 'object',
+                properties: {
+                  label: { type: 'string', required: true, description: 'Short user-facing option label.' },
+                  description: { type: 'string', description: 'One sentence explaining the tradeoff or impact.' },
+                },
+              },
+            },
+            multi_select: {
+              type: 'boolean',
+              description: 'Whether the user may select more than one option. Defaults to false.',
+            },
          },
        },
      },
-      allow_custom: {
-        type: 'boolean',
-        description: 'Whether the user may type a free-form answer instead of selecting an option. Defaults to true.',
-      },
    },
    async execute(args, exec) {
      const result = await ctx.userInteraction.ask({
-        question: args.question,
-        ...args.header !== undefined ? { header: args.header } : {},
-        ...args.options !== undefined ? { options: args.options } : {},
-        ...args.allow_custom !== undefined ? { allowCustom: args.allow_custom } : {},
+        questions: args.questions.map(question => ({
+          id: question.id,
+          question: question.question,
+          ...question.header !== undefined ? { header: question.header } : {},
+          ...question.options !== undefined ? { options: question.options } : {},
+          ...question.multi_select !== undefined ? { multiSelect: question.multi_select } : {},
+        })),
        ...exec.agent !== undefined ? { agent: exec.agent } : {},
        ...exec.signal !== undefined ? { signal: exec.signal } : {},
      })
-      return [{ type: 'text', text: result.answer }]
+      return [{ type: 'text', text: JSON.stringify(result) }]
    },
  }))
 }
--- a/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts
+++ b/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts
@@ -9,9 +9,15 @@ import * as toolAskUser from '@deepseek-ai/dsh-tool-ask-user'

 interface OptionSchemaShape {
  properties: {
-    options: {
+    questions: {
      items: {
-        properties: Record<string, { type: string }>
+        properties: {
+          options: {
+            items: {
+              properties: Record<string, { type: string }>
+            }
+          }
+        } & Record<string, unknown>
      }
    }
  }
@@ -36,29 +42,35 @@ describe('ask_user_question tool', () => {
      parameters: {
        type: 'object',
        properties: {
-          question: { type: 'string' },
-          options: { type: 'array' },
-          allow_custom: { type: 'boolean' },
+          questions: { type: 'array' },
        },
-        required: ['question'],
+        required: ['questions'],
      },
    })
    const parameters = schema?.parameters as unknown as OptionSchemaShape
-    expect(parameters.properties.options.items.properties).toMatchObject({
-      description: { type: 'string' },
-      recommended: { type: 'boolean' },
+    expect(parameters.properties.questions.items.properties).toMatchObject({
+      id: { type: 'string' },
+      question: { type: 'string' },
+      header: { type: 'string' },
+      options: { type: 'array' },
+      multi_select: { type: 'boolean' },
    })
-    expect(parameters.properties.options.items.properties).not.toHaveProperty('desc')
+    expect(parameters.properties.questions.items.properties.options.items.properties).toMatchObject({
+      label: { type: 'string' },
+      description: { type: 'string' },
+    })
+    expect(parameters.properties.questions.items.properties.options.items.properties).not.toHaveProperty('value')
+    expect(parameters.properties.questions.items.properties.options.items.properties).not.toHaveProperty('recommended')
+    expect(parameters.properties.questions.items.properties.options.items.properties).not.toHaveProperty('preview')
  })

-  it('asks the registered user-interaction provider and returns the answer text', async () => {
+  it('asks the registered user-interaction provider and projects structured answers to text', async () => {
    const ctx = await setup()
    const seen: AskUserQuestionRequest[] = []
    ctx.userInteraction.registerProvider({
      async ask(request) {
        seen.push(request)
-        const option = request.options?.[0]
-        return option === undefined ? { answer: 'Use pnpm' } : { answer: 'Use pnpm', option }
+        return { answers: [{ id: 'pkg', selected: ['pnpm'] }] }
      },
    })

@@ -66,20 +78,59 @@ describe('ask_user_question tool', () => {
      callId: CallId('ask-1'),
      name: 'ask_user_question',
      arguments: {
-        question: 'Which package manager should I use?',
-        options: [{ label: 'pnpm', value: 'Use pnpm', recommended: true }],
-        allow_custom: false,
+        questions: [{
+          id: 'pkg',
+          question: 'Which package manager should I use?',
+          options: [{ label: 'pnpm', description: 'Use pnpm workspaces.' }],
+        }],
      },
    })

    expect(result).toMatchObject({
      isError: false,
-      content: [{ type: 'text', text: 'Use pnpm' }],
+      content: [{ type: 'text', text: '{"answers":[{"id":"pkg","selected":["pnpm"]}]}' }],
    })
    expect(seen).toMatchObject([{
-      question: 'Which package manager should I use?',
-      options: [{ label: 'pnpm', value: 'Use pnpm', recommended: true }],
-      allowCustom: false,
+      questions: [{
+        id: 'pkg',
+        question: 'Which package manager should I use?',
+        options: [{ label: 'pnpm', description: 'Use pnpm workspaces.' }],
+      }],
+    }])
+  })
+
+  it('projects custom answers and multi-select choices', async () => {
+    const ctx = await setup()
+    ctx.userInteraction.registerProvider({
+      async ask() {
+        return {
+          answers: [
+            { id: 'targets', selected: ['tests', 'docs'] },
+            { id: 'notes', selected: [], custom: 'ship today' },
+          ],
+        }
+      },
+    })
+
+    const result = await ctx.tools.execute({
+      callId: CallId('ask-multi'),
+      name: 'ask_user_question',
+      arguments: {
+        questions: [
+          {
+            id: 'targets',
+            question: 'What should I update?',
+            options: [{ label: 'tests' }, { label: 'docs' }],
+            multi_select: true,
+          },
+          { id: 'notes', question: 'Any note?' },
+        ],
+      },
+    })
+
+    expect(result.content).toEqual([{
+      type: 'text',
+      text: '{"answers":[{"id":"targets","selected":["tests","docs"]},{"id":"notes","selected":[],"custom":"ship today"}]}',
    }])
  })

@@ -89,7 +140,7 @@ describe('ask_user_question tool', () => {
    ctx.userInteraction.registerProvider({
      async ask(request) {
        seen.push(request)
-        return { answer: 'ok' }
+        return { answers: [{ id: 'continue', selected: ['ok'] }] }
      },
    })
    const controller = new AbortController()
@@ -97,7 +148,7 @@ describe('ask_user_question tool', () => {
    await ctx.tools.execute({
      callId: CallId('ask-2'),
      name: 'ask_user_question',
-      arguments: { question: 'Continue?' },
+      arguments: { questions: [{ id: 'continue', question: 'Continue?' }] },
      signal: controller.signal,
    })

@@ -110,7 +161,7 @@ describe('ask_user_question tool', () => {
    ctx.userInteraction.registerProvider({
      async ask(request) {
        seen.push(request)
-        return { answer: 'ok' }
+        return { answers: [{ id: 'continue', selected: ['ok'] }] }
      },
    })
    const agent = { id: 'main' } as unknown as Agent
@@ -118,12 +169,12 @@ describe('ask_user_question tool', () => {
    const result = await ctx.tools.execute({
      callId: CallId('ask-3'),
      name: 'ask_user_question',
-      arguments: { header: 'Confirm', question: 'Continue?' },
+      arguments: { questions: [{ id: 'continue', header: 'Confirm', question: 'Continue?' }] },
      agent,
    })

-    expect(result.content).toEqual([{ type: 'text', text: 'ok' }])
-    expect(seen[0]).toMatchObject({ header: 'Confirm', agent })
+    expect(result.content).toEqual([{ type: 'text', text: '{"answers":[{"id":"continue","selected":["ok"]}]}' }])
+    expect(seen[0]).toMatchObject({ questions: [{ id: 'continue', header: 'Confirm', question: 'Continue?' }], agent })
  })

  it('returns structured user-interaction errors through tool execution', async () => {
@@ -132,7 +183,7 @@ describe('ask_user_question tool', () => {
    const result = await ctx.tools.execute({
      callId: CallId('ask-no-provider'),
      name: 'ask_user_question',
-      arguments: { question: 'Continue?' },
+      arguments: { questions: [{ id: 'continue', question: 'Continue?' }] },
    })

    expect(result).toMatchObject({
@@ -141,48 +192,19 @@ describe('ask_user_question tool', () => {
    })
  })

-  it('uses an option label when the selected option has no explicit value', async () => {
+  it('returns a structured error for empty question batches', async () => {
    const ctx = await setup()
-    ctx.userInteraction.registerProvider({
-      async ask(request) {
-        const option = request.options?.[0]
-        if (option === undefined) throw new Error('missing option')
-        return { answer: option.label, option }
-      },
-    })

    const result = await ctx.tools.execute({
-      callId: CallId('ask-4'),
+      callId: CallId('ask-empty'),
      name: 'ask_user_question',
-      arguments: {
-        question: 'Pick one',
-        options: [{ label: 'Fallback label' }],
-      },
+      arguments: { questions: [] },
    })

-    expect(result.content).toEqual([{ type: 'text', text: 'Fallback label' }])
-  })
-
-  it('returns the provider-computed answer even when option metadata is present', async () => {
-    const ctx = await setup()
-    ctx.userInteraction.registerProvider({
-      async ask(request) {
-        const option = request.options?.[0]
-        if (option === undefined) throw new Error('missing option')
-        return { answer: `selected ${option.value}`, option }
-      },
+    expect(result).toMatchObject({
+      isError: true,
+      error: { name: 'UserInteractionError', code: 'EMPTY_QUESTIONS' },
    })
-
-    const result = await ctx.tools.execute({
-      callId: CallId('ask-5'),
-      name: 'ask_user_question',
-      arguments: {
-        question: 'Pick one',
-        options: [{ label: 'A', value: 'a' }],
-      },
-    })
-
-    expect(result.content).toEqual([{ type: 'text', text: 'selected a' }])
  })

  it('unregisters the tool when its plugin fiber is disposed', async () => {