feat: add question tools (#1298)

* feat(agent): add question tool flow

* feat(mcp): implement real Apple Maps search using URL scheme (#1289)

* feat: support voice.ai (#1291)

* feat: remove custome tiptap (#1295)

* feat: settings auto scroll toggle (#1293)

* feat: settings auto scroll toggle

* feat: i18n support

* fix(renderer): remove specific event listeners instead of all

* feat: add tooltip for filling default API URL in settings (#1296)

* refactor(question): simplify question request UI to single-choice interface

* fix(chat): restore pending question state

* fix: review issues

---------

Co-authored-by: Qi Jin <jin.qi1@northeastern.edu>
Co-authored-by: xiaomo <wegi866@gmail.com>

Author: 3 people

src/main/presenter/agentPresenter/acp/agentToolManager.ts

@@ -9,6 +9,7 @@ import { presenter } from '@/presenter'
 import { AgentFileSystemHandler } from './agentFileSystemHandler'
 import { AgentBashHandler } from './agentBashHandler'
 import { SkillTools } from '../../skillPresenter/skillTools'
+import { questionToolSchema, QUESTION_TOOL_NAME } from '../tools/questionTool'
 import {
   ChatSettingsToolHandler,
   buildChatSettingsToolDefinitions,
@@ -278,6 +279,9 @@ export class AgentToolManager {
       defs.push(...fsDefs)
     }
 
+    // 2. Built-in question tool (all modes)
+    defs.push(...this.getQuestionToolDefinitions())
+
     // 3. Skill tools (agent mode only)
     if (isAgentMode && this.isSkillsEnabled()) {
       const skillDefs = this.getSkillToolDefinitions()
@@ -331,6 +335,21 @@ export class AgentToolManager {
     args: Record<string, unknown>,
     conversationId?: string
   ): Promise<AgentToolCallResult | string> {
+    if (toolName === QUESTION_TOOL_NAME) {
+      const validationResult = questionToolSchema.safeParse(args)
+      if (!validationResult.success) {
+        throw new Error(`Invalid arguments for question: ${validationResult.error.message}`)
+      }
+      return {
+        content: 'question_requested',
+        rawData: {
+          content: 'question_requested',
+          isError: false,
+          toolResult: validationResult.data
+        }
+      }
+    }
+
     // Route to FileSystem tools
     if (this.isFileSystemTool(toolName)) {
       if (!this.fileSystemHandler) {
@@ -610,6 +629,29 @@ export class AgentToolManager {
     ]
   }
 
+  private getQuestionToolDefinitions(): MCPToolDefinition[] {
+    return [
+      {
+        type: 'function',
+        function: {
+          name: QUESTION_TOOL_NAME,
+          description:
+            'Ask the user a structured question and pause the agent loop until the user responds.',
+          parameters: zodToJsonSchema(questionToolSchema) as {
+            type: string
+            properties: Record<string, unknown>
+            required?: string[]
+          }
+        },
+        server: {
+          name: 'agent-core',
+          icons: '❓',
+          description: 'Agent core tools'
+        }
+      }
+    ]
+  }
+
   private isFileSystemTool(toolName: string): boolean {
     const filesystemTools = [
       'read_file',

src/main/presenter/agentPresenter/index.ts

@@ -7,7 +7,7 @@ import type {
   ISQLitePresenter,
   MESSAGE_METADATA
 } from '@shared/presenter'
-import type { AssistantMessage } from '@shared/chat'
+import type { AssistantMessage, AssistantMessageBlock, UserMessageContent } from '@shared/chat'
 import { eventBus, SendTarget } from '@/eventbus'
 import { STREAM_EVENTS } from '@/events'
 import { presenter } from '@/presenter'
@@ -161,6 +161,12 @@ export class AgentPresenter implements IAgentPresenter {
       this.buildMessageMetadata(conversation)
     )
 
+    try {
+      await this.resolvePendingQuestionIfNeeded(agentId, userMessage.id, content)
+    } catch (error) {
+      console.warn('[AgentPresenter] Failed to auto-resolve pending question:', error)
+    }
+
     const assistantMessage = await this.streamGenerationHandler.generateAIResponse(
       agentId,
       userMessage.id
@@ -301,6 +307,25 @@ export class AgentPresenter implements IAgentPresenter {
     )
   }
 
+  async resolveQuestion(
+    messageId: string,
+    toolCallId: string,
+    answerText: string,
+    answerMessageId?: string
+  ): Promise<void> {
+    await this.handleQuestionResolution(messageId, toolCallId, {
+      resolution: 'replied',
+      answerText,
+      answerMessageId
+    })
+  }
+
+  async rejectQuestion(messageId: string, toolCallId: string): Promise<void> {
+    await this.handleQuestionResolution(messageId, toolCallId, {
+      resolution: 'rejected'
+    })
+  }
+
   async getMessageRequestPreview(agentId: string, messageId?: string): Promise<unknown> {
     if (!messageId) {
       return null
@@ -309,6 +334,115 @@ export class AgentPresenter implements IAgentPresenter {
     return this.utilityHandler.getMessageRequestPreview(messageId)
   }
 
+  private async handleQuestionResolution(
+    messageId: string,
+    toolCallId: string,
+    payload: {
+      resolution: 'replied' | 'rejected'
+      answerText?: string
+      answerMessageId?: string
+    }
+  ): Promise<void> {
+    if (!messageId || !toolCallId) {
+      return
+    }
+
+    const message = await this.messageManager.getMessage(messageId)
+    if (!message || message.role !== 'assistant') {
+      throw new Error(`Message not found or not assistant (${messageId})`)
+    }
+
+    const content = message.content as AssistantMessageBlock[]
+    const questionBlock = content.find(
+      (block) =>
+        block.type === 'action' &&
+        block.action_type === 'question_request' &&
+        block.tool_call?.id === toolCallId
+    )
+
+    if (!questionBlock) {
+      throw new Error(
+        `Question block not found (messageId: ${messageId}, toolCallId: ${toolCallId})`
+      )
+    }
+
+    if (questionBlock.status !== 'pending') {
+      return
+    }
+
+    const isReplied = payload.resolution === 'replied'
+    questionBlock.status = isReplied ? 'success' : 'denied'
+    questionBlock.extra = {
+      ...questionBlock.extra,
+      needsUserAction: false,
+      questionResolution: payload.resolution,
+      ...(isReplied && payload.answerText ? { answerText: payload.answerText } : {}),
+      ...(isReplied && payload.answerMessageId ? { answerMessageId: payload.answerMessageId } : {})
+    }
+
+    const generatingState = this.generatingMessages.get(messageId)
+    if (generatingState) {
+      const questionIndex = generatingState.message.content.findIndex(
+        (block) =>
+          block.type === 'action' &&
+          block.action_type === 'question_request' &&
+          block.tool_call?.id === toolCallId
+      )
+      if (questionIndex !== -1) {
+        const stateBlock = generatingState.message.content[questionIndex]
+        generatingState.message.content[questionIndex] = {
+          ...stateBlock,
+          ...questionBlock,
+          extra: questionBlock.extra ? { ...questionBlock.extra } : undefined,
+          tool_call: questionBlock.tool_call ? { ...questionBlock.tool_call } : undefined
+        }
+      }
+    }
+
+    await this.messageManager.editMessage(messageId, JSON.stringify(content))
+    presenter.sessionManager.clearPendingQuestion(message.conversationId)
+    presenter.sessionManager.setStatus(message.conversationId, 'idle')
+  }
+
+  private async resolvePendingQuestionIfNeeded(
+    conversationId: string,
+    userMessageId: string,
+    rawContent: string
+  ): Promise<void> {
+    const session = await this.sessionManager.getSession(conversationId)
+    const pendingQuestion = session.runtime?.pendingQuestion
+    if (!pendingQuestion?.messageId || !pendingQuestion.toolCallId) {
+      return
+    }
+
+    const answerText = this.extractUserMessageText(rawContent)
+    if (!answerText.trim()) {
+      return
+    }
+
+    await this.handleQuestionResolution(pendingQuestion.messageId, pendingQuestion.toolCallId, {
+      resolution: 'replied',
+      answerText,
+      answerMessageId: userMessageId
+    })
+  }
+
+  private extractUserMessageText(rawContent: string): string {
+    if (!rawContent) return ''
+    try {
+      const parsed = JSON.parse(rawContent) as UserMessageContent
+      if (typeof parsed.text === 'string') {
+        return parsed.text
+      }
+      if (Array.isArray(parsed.content)) {
+        return parsed.content.map((block) => block.content || '').join('')
+      }
+    } catch (error) {
+      console.warn('[AgentPresenter] Failed to parse user message content:', error)
+    }
+    return rawContent
+  }
+
   private buildMessageMetadata(conversation: CONVERSATION): MESSAGE_METADATA {
     const { providerId, modelId } = conversation.settings
     return {
@@ -416,6 +550,7 @@ export class AgentPresenter implements IAgentPresenter {
     this.sessionManager.updateRuntime(state.conversationId, { userStopRequested: true })
     this.sessionManager.setStatus(state.conversationId, 'paused')
     this.sessionManager.clearPendingPermission(state.conversationId)
+    this.sessionManager.clearPendingQuestion(state.conversationId)
     state.isCancelled = true
 
     if (state.adaptiveBuffer) {

src/main/presenter/agentPresenter/loop/toolCallHandler.ts

@@ -1,4 +1,5 @@
 import type { AssistantMessageBlock } from '@shared/chat'
+import type { QuestionInfo } from '@shared/types/core/question'
 import { finalizeAssistantMessageBlocks } from '@shared/chat/messageBlocks'
 import type {
   LLMAgentEventData,
@@ -215,6 +216,44 @@ export class ToolCallHandler {
     }
   }
 
+  async processQuestionRequest(
+    state: GeneratingMessageState,
+    event: LLMAgentEventData,
+    currentTime: number
+  ): Promise<void> {
+    const payload = event.question_request as QuestionInfo | undefined
+    if (!payload) return
+
+    this.finalizeLastBlock(state)
+
+    state.message.content.push({
+      type: 'action',
+      content: '',
+      status: 'pending',
+      timestamp: currentTime,
+      action_type: 'question_request',
+      tool_call: {
+        id: event.tool_call_id,
+        name: event.tool_call_name,
+        params: event.tool_call_params || '',
+        server_name: event.tool_call_server_name,
+        server_icons: event.tool_call_server_icons,
+        server_description: event.tool_call_server_description
+      },
+      extra: {
+        needsUserAction: true,
+        questionHeader: payload.header ?? '',
+        questionText: payload.question,
+        questionOptions: payload.options,
+        questionMultiple: Boolean(payload.multiple),
+        questionCustom: payload.custom !== false,
+        questionResolution: 'asked'
+      }
+    })
+
+    state.pendingToolCall = undefined
+  }
+
   async processMcpUiResourcesFromToolCall(
     state: GeneratingMessageState,
     event: LLMAgentEventData,

src/main/presenter/agentPresenter/loop/toolCallProcessor.ts

@@ -10,6 +10,7 @@ import fs from 'fs/promises'
 import path from 'path'
 import { isNonRetryableError } from './errorClassification'
 import { resolveToolOffloadPath } from '../../sessionPresenter/sessionPaths'
+import { parseQuestionToolArgs, QUESTION_TOOL_NAME } from '../tools/questionTool'
 
 interface ToolCallProcessorOptions {
   getAllToolDefinitions: (context: ToolCallExecutionContext) => Promise<MCPToolDefinition[]>
@@ -42,6 +43,7 @@ interface ToolCallProcessResult {
 
 const TOOL_OUTPUT_OFFLOAD_THRESHOLD = 5000
 const TOOL_OUTPUT_PREVIEW_LENGTH = 1024
+const QUESTION_ERROR_KEY = 'common.error.invalidQuestionRequest'
 
 // Tools that require offload when output exceeds threshold
 // Tools not in this list will never trigger offload (e.g., read_file has its own pagination)
@@ -75,7 +77,7 @@ export class ToolCallProcessor {
       return toolDefinitions.find((tool) => tool.function.name === toolName)
     }
 
-    for (const toolCall of context.toolCalls) {
+    for (const [index, toolCall] of context.toolCalls.entries()) {
       if (context.abortSignal.aborted) break
 
       if (toolCallCount >= context.maxToolCalls) {
@@ -145,6 +147,70 @@ export class ToolCallProcessor {
         conversationId: context.conversationId
       }
 
+      if (toolCall.name === QUESTION_TOOL_NAME) {
+        const isStandalone = context.toolCalls.length === 1
+        const isLast = index === context.toolCalls.length - 1
+        if (!isStandalone || !isLast) {
+          notifyToolCallFinished('error')
+          this.appendToolError(
+            context.conversationMessages,
+            context.modelConfig,
+            toolCall,
+            'Question tool must be the only tool call in a turn.'
+          )
+          yield {
+            type: 'response',
+            data: {
+              eventId: context.eventId,
+              question_error: QUESTION_ERROR_KEY,
+              tool_call_id: toolCall.id,
+              tool_call_name: toolCall.name
+            }
+          }
+          continue
+        }
+
+        const parsedQuestion = parseQuestionToolArgs(toolCall.arguments || '')
+        if (!parsedQuestion.success) {
+          notifyToolCallFinished('error')
+          this.appendToolError(
+            context.conversationMessages,
+            context.modelConfig,
+            toolCall,
+            `Invalid question tool arguments: ${parsedQuestion.error}`
+          )
+          yield {
+            type: 'response',
+            data: {
+              eventId: context.eventId,
+              question_error: QUESTION_ERROR_KEY,
+              tool_call_id: toolCall.id,
+              tool_call_name: toolCall.name
+            }
+          }
+          continue
+        }
+
+        notifyToolCallFinished('success')
+        yield {
+          type: 'response',
+          data: {
+            eventId: context.eventId,
+            tool_call: 'question-required',
+            tool_call_id: toolCall.id,
+            tool_call_name: toolCall.name,
+            tool_call_params: toolCall.arguments,
+            tool_call_server_name: toolDef.server.name,
+            tool_call_server_icons: toolDef.server.icons,
+            tool_call_server_description: toolDef.server.description,
+            question_request: parsedQuestion.data
+          }
+        }
+
+        needContinueConversation = false
+        break
+      }
+
       yield {
         type: 'response',
         data: {