@shawnstack/quickforge 1.7.11 → 1.8.0

package/server/agent-manager.mjs

@@ -13,7 +13,7 @@ import {
   composeSubagentSystemPrompt,
   formatSubagentTask,
 } from './subagents.mjs'
-import { agentProfileSnapshot, getAgentProfile } from './agent-profiles.mjs'
+import { agentProfileSnapshot, getAgentProfile, listSubagentProfiles } from './agent-profiles.mjs'
 import { modelBindingFromModel, resolveImplicitModelPreference, resolveModelBinding } from './model-catalog.mjs'
 import { agentProfileFromMarkdown } from './agent-profile-files.mjs'
 import {
@@ -52,11 +52,27 @@ import {
   readAutoCompactSettings,
 } from './auto-compaction.mjs'
 import {
+  formatAgentCommandPrompt,
+  formatSkillCommandPrompt,
   handleInternalCommand,
   parseInternalCommandInvocation,
   resolveCustomCommandInvocation,
 } from './custom-commands.mjs'
+import { mergeSkills, normalizeSkillNames } from './skills.mjs'
+import {
+  contextReferencesFromMessage,
+  contextReferencesPrompt,
+  validatePromptContextReferences,
+  validateContextReferences,
+  withCanonicalContextReferences,
+} from './context-references.mjs'
 import { serverConvertToLlm, messageText, lastAssistantText } from './message-converters.mjs'
+import {
+  normalizeSelectedCapabilities,
+  selectedCapabilitiesFromMessage,
+  selectedCapabilityPrompt,
+  withCanonicalSelectedCapabilities,
+} from './selected-capabilities.mjs'
 import { mergeQuickForgeTiming, wrapToolDefinition, wrapMcpToolDefinition, wrapPluginToolDefinition, sessionSkillsContext } from './tool-wiring.mjs'
 import {
   APPROVAL_TIMEOUT_MS,
@@ -68,6 +84,15 @@ import {
   commandToolPermissionError,
   createCommandToolPermissions,
 } from './approval-store.mjs'
+import {
+  ASK_TIMEOUT_MS,
+  pendingAsks,
+  getPendingAskForSession,
+  normalizeAskQuestions,
+  formatAskResult,
+} from './ask-store.mjs'
+
+export { getPendingAskForSession, normalizeAskQuestions } from './ask-store.mjs'
 
 // ---------------------------------------------------------------------------
 // Tool definitions (server-side, no REST roundtrip)
@@ -88,8 +113,25 @@ function wrapSubagentToolDefinition(definition, parentSessionId) {
   }
 }
 
+function wrapAskUserToolDefinition(definition, parentSessionId) {
+  return {
+    ...definition,
+    execute: async (toolCallId, params) => {
+      const session = agentSessions.get(parentSessionId)
+      if (!session) {
+        return {
+          content: [{ type: 'text', text: 'No active session for ask_user.' }],
+          details: { askId: null, skipped: true },
+        }
+      }
+      return createAskUserPromise(session, toolCallId, params || {})
+    },
+  }
+}
+
 function wrapWorkspaceToolDefinition(definition, context, toolPermissions, options = {}) {
   if (definition.name === 'run_subagent') return wrapSubagentToolDefinition(definition, options.parentSessionId)
+  if (definition.name === 'ask_user') return wrapAskUserToolDefinition(definition, options.parentSessionId)
   return wrapToolDefinition(definition, context, toolPermissions)
 }
 
@@ -304,8 +346,83 @@ function createApprovalPromise(session, toolCallId, toolName, args, source) {
   })
 }
 
-function createAcpApprovalPromise(session, request) {
-  return new Promise((resolve, reject) => {
+/**
+ * Create a Promise that resolves when the user answers (or skips) an ask_user
+ * tool call. The tool's execute blocks on this promise, pausing the agent loop
+ * until the user responds.
+ */
+function createAskUserPromise(session, toolCallId, params) {
+  const questions = normalizeAskQuestions(params)
+  if (!questions.length) {
+    return Promise.resolve({
+      content: [{ type: 'text', text: formatAskResult(questions, null, true, 'no-questions') }],
+      details: { askId: null, skipped: true },
+    })
+  }
+  const askId = randomUUID()
+  return new Promise((resolve) => {
+    let settled = false
+    const requestedAt = Date.now()
+    const expiresAt = requestedAt + ASK_TIMEOUT_MS
+
+    const timeout = setTimeout(() => {
+      if (settled) return
+      finish({ skipped: true, reason: 'timeout' })
+    }, ASK_TIMEOUT_MS)
+
+    let onAbort = null
+
+    const finish = (payload) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timeout)
+      if (onAbort && session.agent.signal) session.agent.signal.removeEventListener('abort', onAbort)
+      pendingAsks.delete(askId)
+      const answers = payload.skipped ? null : payload.answers
+      resolve({
+        content: [{ type: 'text', text: formatAskResult(questions, answers, payload.skipped, payload.reason) }],
+        details: { askId, questions, answers, skipped: !!payload.skipped, ...(payload.reason ? { skipReason: payload.reason } : {}) },
+      })
+      emitSessionEvent(session, {
+        type: 'ask_user_answered',
+        sessionId: session.sessionId,
+        askId,
+        toolCallId,
+        skipped: !!payload.skipped,
+        answers: answers || [],
+      })
+    }
+
+    const signal = session.agent.signal
+    if (signal) {
+      if (signal.aborted) {
+        finish({ skipped: true, reason: 'aborted' })
+        return
+      }
+      onAbort = () => finish({ skipped: true, reason: 'aborted' })
+      signal.addEventListener('abort', onAbort, { once: true })
+    }
+
+    pendingAsks.set(askId, {
+      finish: (payload) => finish(payload),
+      sessionId: session.sessionId,
+      toolCallId,
+      questions,
+      requestedAt,
+      expiresAt,
+    })
+
+    emitSessionEvent(session, {
+      type: 'ask_user_required',
+      sessionId: session.sessionId,
+      askId,
+      toolCallId,
+      questions,
+    })
+  })
+}
+
+function createAcpApprovalPromise(session, request) {  return new Promise((resolve, reject) => {
     let settled = false
     const requestedAt = Date.now()
     const expiresAt = requestedAt + APPROVAL_TIMEOUT_MS
@@ -1035,10 +1152,103 @@ function planCommandState(userMessage, args) {
   }
 }
 
+function parseSlashNameAndTask(args) {
+  const trimmed = String(args || '').trim()
+  if (!trimmed) return { name: '', task: '' }
+  const match = trimmed.match(/^(\S+)(?:\s+([\s\S]*))?$/)
+  return { name: match?.[1] || '', task: (match?.[2] || '').trim() }
+}
+
+async function enabledSkillsForSession(session) {
+  // Same sources as the activate_skill tool (loadSkillToolContext), resolved
+  // from the session's captured skill selections and workspace.
+  const skillContext = await loadSkillToolContext({
+    ...sessionSkillsContext(session),
+    workspaceRoot: session.projectContext?.workspaceRoot,
+  })
+  return mergeSkills(skillContext.globalSkills, skillContext.projectSkills)
+}
+
+function enabledSkillsLine(enabledSkills) {
+  if (enabledSkills.length === 0) return 'No skills are currently enabled.'
+  return `Enabled skills: ${enabledSkills.map((skill) => skill.name).join(', ')}.`
+}
+
+function availableSubagentsLine(profiles) {
+  return `Available subagents: ${profiles.map((profile) => profile.name).join(', ')}.`
+}
+
+async function skillCommandState(session, userMessage, args) {
+  const { name, task } = parseSlashNameAndTask(args)
+  const enabledSkills = await enabledSkillsForSession(session)
+
+  if (!name) {
+    return { textResponse: ['Usage: /skill <name> [task]', '', enabledSkillsLine(enabledSkills)].join('\n') }
+  }
+
+  const skillName = normalizeSkillNames([name])[0]
+  const skill = skillName ? enabledSkills.find((item) => item.name === skillName) : null
+  if (!skill) {
+    return {
+      textResponse: [
+        `Unknown or disabled skill: ${name}`,
+        '',
+        'Usage: /skill <name> [task]',
+        '',
+        enabledSkillsLine(enabledSkills),
+      ].join('\n'),
+    }
+  }
+
+  return {
+    userMessage,
+    commandPrompt: formatSkillCommandPrompt(skill.name, task),
+    commandName: 'skill',
+  }
+}
+
+async function agentCommandState(session, userMessage, args) {
+  const { name, task } = parseSlashNameAndTask(args)
+  const profileOptions = { workspaceRoot: session.projectContext?.workspaceRoot }
+
+  if (!name) {
+    const profiles = await listSubagentProfiles(profileOptions)
+    return { textResponse: ['Usage: /agent <name> <task>', '', availableSubagentsLine(profiles)].join('\n') }
+  }
+  if (!task) {
+    return { textResponse: 'Usage: /agent <name> <task>' }
+  }
+
+  const profile = await getAgentProfile(name, profileOptions)
+  if (!profile || profile.enabledAsSubagent !== true) {
+    const profiles = await listSubagentProfiles(profileOptions)
+    return {
+      textResponse: [
+        `Unknown subagent: ${name}`,
+        '',
+        'Usage: /agent <name> <task>',
+        '',
+        availableSubagentsLine(profiles),
+      ].join('\n'),
+    }
+  }
+
+  return {
+    userMessage,
+    commandPrompt: formatAgentCommandPrompt(profile.name, task),
+    commandName: 'agent',
+  }
+}
+
 async function resolveCommandState(session, userMessage, promptCommand = null) {
   const command = normalizedPromptCommand(promptCommand) || promptCommandFromMessage(userMessage)
+  const internalInvocation = internalInvocationForPromptCommand(userMessage, command)
+  // /skill and /agent need session context (enabled skills, workspace-rooted
+  // agent profiles), so they are resolved here before handleInternalCommand.
+  if (internalInvocation?.type === 'skill') return skillCommandState(session, userMessage, internalInvocation.args)
+  if (internalInvocation?.type === 'agent') return agentCommandState(session, userMessage, internalInvocation.args)
   const internalResponse = await handleInternalCommand(
-    internalInvocationForPromptCommand(userMessage, command),
+    internalInvocation,
     session.projectContext?.workspaceRoot,
     session.projectContext?.project?.commandDir,
   )
@@ -1066,6 +1276,14 @@ async function resolveCommandState(session, userMessage, promptCommand = null) {
       commandName: 'review',
     }
   }
+  if (internalResponse?.commit) {
+    return {
+      userMessage,
+      commandPrompt: formatCommitCommandPrompt(internalResponse.args),
+      permissions: { allowEdit: false, allowCommands: true, allowSubagents: false },
+      commandName: 'commit',
+    }
+  }
 
   if (!session.projectContext?.workspaceRoot) {
     // Even without a project, user-level custom commands (~/.quickforge/commands/) are available
@@ -1175,6 +1393,24 @@ ${taskText}
 </plan_command_invocation>`
 }
 
+function formatCommitCommandPrompt(message) {
+  const messageText = String(message || '').trim() || '(none; generate a message from the diff and repository style)'
+  return `<commit_command_invocation name="commit">
+This /commit command applies only to the current user request. Create at most one local commit for the current task.
+
+Rules for this turn:
+- Inspect the current task's Git changes and commit only files related to this task; do not mix in unrelated changes.
+- Never use \`git add .\`, \`git add -A\`, or \`git add --all\`; stage only explicit task-related paths.
+- Run relevant validation before committing and stop if it fails. Do not modify code, bypass hooks, or alter unrelated changes.
+- Create at most one local commit. Do not push, tag, release, publish, or otherwise affect a remote.
+- Use the requested message below, or generate one from the diff and repository conventions when none is provided.
+- Report the commit hash and message, validations run, and any remaining working tree changes.
+
+Requested commit message:
+${messageText}
+</commit_command_invocation>`
+}
+
 function formatReviewCommandPrompt(scope) {
   const scopeText = String(scope || '').trim() || '(none; review the repository changes that appear relevant for a pre-commit check)'
   return `<review_command_invocation name="review">
@@ -1541,30 +1777,6 @@ function textFromMessageContent(content) {
   return ''
 }
 
-function selectedCapabilityPrompt(capabilities) {
-  if (!Array.isArray(capabilities) || capabilities.length === 0) return null
-  const normalized = capabilities
-    .filter((capability) => capability && typeof capability === 'object')
-    .map((capability) => ({
-      type: String(capability.type || '').slice(0, 32),
-      pluginName: String(capability.pluginName || '').slice(0, 120),
-      name: String(capability.name || '').slice(0, 120),
-      label: String(capability.label || capability.name || '').slice(0, 160),
-      description: String(capability.description || '').slice(0, 400),
-    }))
-    .filter((capability) => capability.type && capability.pluginName && capability.name)
-    .slice(0, 4)
-  if (normalized.length === 0) return null
-
-  const lines = normalized.map((capability) => {
-    const toolHint = capability.type === 'tool' ? ` Tool name: plugin__${capability.pluginName}__${capability.name}.` : ''
-    const description = capability.description ? ` Description: ${capability.description}` : ''
-    return `- ${capability.label} (${capability.type}, plugin: ${capability.pluginName}, name: ${capability.name}).${toolHint}${description}`
-  }).join('\n')
-
-  return `The user selected the following QuickForge plugin capability mentions for this turn. Treat them as an explicit preference for routing and context. Use the selected capability when relevant, but do not force it if it is unrelated to the actual request.\n\n${lines}`
-}
-
 function applyActiveCapabilityPrompt(messages, capabilityPrompt) {
   if (!capabilityPrompt) return messages
 
@@ -1880,6 +2092,8 @@ export async function createAgent(sessionId, config = {}) {
       if (commandPermissionError) return { block: true, reason: commandPermissionError }
       const isSkillTool = toolName === 'activate_skill' || toolName === 'read_skill_resource'
       if (isSkillTool) return undefined
+      // ask_user only waits for the user's answer; it changes nothing and needs no approval.
+      if (toolName === 'ask_user') return undefined
       if (profileToolNames && !profileToolNames.includes(toolName)) return { block: true, reason: `Agent profile ${agentProfile.name} is not allowed to use ${toolName}.` }
       if (toolName === 'manage_global_memory') return undefined
       if (toolName === 'run_subagent') {
@@ -2592,14 +2806,11 @@ async function refreshSessionModelBinding(session) {
  * Send a user message to the agent and start the agent loop.
  * Returns immediately; events are streamed via the event bus.
  */
-export async function runPrompt(sessionId, message, selectedCapabilities = [], promptCommand = null, transientContextPrompt = null, modelAccessContext = null) {
+export async function runPrompt(sessionId, message, selectedCapabilities = [], promptCommand = null, transientContextPrompt = null, modelAccessContext = null, contextReferences = undefined) {
   let session = await syncSessionFromStorage(sessionId)
   if (!session) {
     throw Object.assign(new Error('Session not found'), { statusCode: 404 })
   }
-  if (modelAccessContext) session.modelAccessContext = modelAccessContext
-  if (session.harness === AGENT_HARNESS_QUICKFORGE) await refreshSessionModelBinding(session)
-
   if (session.agent.state.isStreaming || session.abortPending) {
     throw Object.assign(new Error('Generation is still running. Stop it or wait until it finishes.'), {
       statusCode: 409,
@@ -2607,17 +2818,27 @@ export async function runPrompt(sessionId, message, selectedCapabilities = [], p
     })
   }
 
-  if (session.harness === AGENT_HARNESS_QUICKFORGE) await refreshMemoryState(session)
-  resetIdleTimer(session)
-
-  // Build user message
+  // Validate references before model refresh, memory refresh, idle timers, title,
+  // message persistence, or agent_start side effects.
   const initialUserMessage = typeof message === 'string'
     ? { role: 'user', content: message, timestamp: new Date().toISOString() }
     : message
+  const canonicalContextReferences = await validatePromptContextReferences(contextReferences, session)
+  const canonicalSelectedCapabilities = normalizeSelectedCapabilities(selectedCapabilities)
+  const canonicalInitialUserMessage = withCanonicalSelectedCapabilities(
+    withCanonicalContextReferences(initialUserMessage, canonicalContextReferences),
+    canonicalSelectedCapabilities,
+  )
+
+  if (modelAccessContext) session.modelAccessContext = modelAccessContext
+  if (session.harness === AGENT_HARNESS_QUICKFORGE) await refreshSessionModelBinding(session)
+  if (session.harness === AGENT_HARNESS_QUICKFORGE) await refreshMemoryState(session)
+  resetIdleTimer(session)
+
   const commandState = session.harness === AGENT_HARNESS_QUICKFORGE
-    ? await resolveCommandState(session, initialUserMessage, promptCommand)
-    : { userMessage: initialUserMessage }
-  const resolvedUserMessage = commandState.userMessage ?? initialUserMessage
+    ? await resolveCommandState(session, canonicalInitialUserMessage, promptCommand)
+    : { userMessage: canonicalInitialUserMessage }
+  const resolvedUserMessage = commandState.userMessage ?? canonicalInitialUserMessage
 
   if (session.harness === AGENT_HARNESS_OPENCODE) {
     session.agent.validatePrompt(resolvedUserMessage)
@@ -2626,7 +2847,7 @@ export async function runPrompt(sessionId, message, selectedCapabilities = [], p
   if (commandState.textResponse) {
     session.agent.state.messages = [
       ...session.agent.state.messages,
-      initialUserMessage,
+      canonicalInitialUserMessage,
       assistantTextMessage(commandState.textResponse, session.model),
     ]
     await persistSession(session)
@@ -2641,11 +2862,11 @@ export async function runPrompt(sessionId, message, selectedCapabilities = [], p
   }
 
   if (commandState.summary) {
-    return summarySession(session, initialUserMessage, commandState.summary)
+    return summarySession(session, canonicalInitialUserMessage, commandState.summary)
   }
 
   if (commandState.compact) {
-    return compactSession(session, initialUserMessage, commandState.compact)
+    return compactSession(session, canonicalInitialUserMessage, commandState.compact)
   }
 
   const userMessage = session.harness === AGENT_HARNESS_QUICKFORGE
@@ -2665,10 +2886,12 @@ export async function runPrompt(sessionId, message, selectedCapabilities = [], p
   session.activeCommandName = commandState.commandName ?? null
   session.activeCommandPermissions = commandState.permissions ?? null
   session.activeCommandPrompt = commandState.commandPrompt ?? null
-  session.activeCapabilityPrompt = selectedCapabilityPrompt(selectedCapabilities)
-  session.activeTransientContextPrompt = typeof transientContextPrompt === 'string' && transientContextPrompt.trim()
-    ? transientContextPrompt
-    : null
+  session.activeCapabilityPrompt = selectedCapabilityPrompt(canonicalSelectedCapabilities)
+  const referencePrompt = contextReferencesPrompt(canonicalContextReferences)
+  session.activeTransientContextPrompt = [
+    typeof transientContextPrompt === 'string' && transientContextPrompt.trim() ? transientContextPrompt : null,
+    referencePrompt,
+  ].filter(Boolean).join('\n\n') || null
 
   // Fire and forget — events come through eventBus
   session.agent.prompt(userMessage).catch((err) => {
@@ -2744,8 +2967,14 @@ export async function continueSession(sessionId, modelAccessContext = null) {
   }
 
   const lastUserMessage = messages[lastUserIndex]
-  const commandState = await resolveCommandState(session, lastUserMessage)
-  const continuedUserMessage = prepareCloudUserMessage(session, commandState.userMessage ?? lastUserMessage)
+  const canonicalContextReferences = await validateContextReferences(contextReferencesFromMessage(lastUserMessage), session)
+  const canonicalSelectedCapabilities = normalizeSelectedCapabilities(selectedCapabilitiesFromMessage(lastUserMessage))
+  const canonicalLastUserMessage = withCanonicalSelectedCapabilities(
+    withCanonicalContextReferences(lastUserMessage, canonicalContextReferences),
+    canonicalSelectedCapabilities,
+  )
+  const commandState = await resolveCommandState(session, canonicalLastUserMessage)
+  const continuedUserMessage = prepareCloudUserMessage(session, commandState.userMessage ?? canonicalLastUserMessage)
   const trimmedMessages = messages.slice(0, lastUserIndex).concat(continuedUserMessage)
   updateSessionMessages(session, trimmedMessages)
   const compactedUpToIndex = Number(session.contextCompaction?.compactedUpToIndex) || 0
@@ -2764,7 +2993,8 @@ export async function continueSession(sessionId, modelAccessContext = null) {
   session.activeCommandName = commandState.commandName ?? null
   session.activeCommandPermissions = commandState.permissions ?? null
   session.activeCommandPrompt = commandState.commandPrompt ?? null
-  session.activeCapabilityPrompt = null
+  session.activeCapabilityPrompt = selectedCapabilityPrompt(canonicalSelectedCapabilities)
+  session.activeTransientContextPrompt = contextReferencesPrompt(canonicalContextReferences)
 
   session.agent.continue().catch((err) => {
     logger.error(`Agent continue error for session ${sessionId}:`, err, { sessionId })
@@ -2774,6 +3004,7 @@ export async function continueSession(sessionId, modelAccessContext = null) {
     session.activeCommandPermissions = null
     session.activeCommandPrompt = null
     session.activeCapabilityPrompt = null
+    session.activeTransientContextPrompt = null
   })
 
   return { sessionId, status: 'running' }
@@ -2972,6 +3203,7 @@ export function getSessionState(sessionId) {
     contextUsage: getSessionContextUsage(session),
     pendingToolApproval: getPendingApprovalForSession(session.sessionId),
     pendingAutoCompactApproval: getPendingAutoCompactApprovalForSession(session.sessionId),
+    pendingAsk: getPendingAskForSession(session.sessionId),
     acpSession: session.harness === AGENT_HARNESS_OPENCODE ? session.agent.state.acpSession : undefined,
     isStreaming: session.abortPending ? false : session.agent.state.isStreaming,
     errorMessage: session.agent.state.errorMessage,
@@ -3228,6 +3460,30 @@ export function rejectAutoCompact(sessionId, approvalId) {
   return { rejected: true, approvalId }
 }
 
+/**
+ * Resolve a pending ask_user call with the user's answers (or a skip).
+ * `answers` is an array aligned with the ask's questions:
+ * `[{ choices: string[], custom?: string }]`.
+ */
+export function answerAsk(sessionId, askId, { answers, skipped = false } = {}) {
+  const ask = pendingAsks.get(askId)
+  if (!ask || ask.sessionId !== sessionId) {
+    throw Object.assign(new Error('No pending ask for this session'), { statusCode: 404 })
+  }
+  const normalizedAnswers = (Array.isArray(answers) ? answers : []).slice(0, ask.questions.length).map((answer) => ({
+    choices: (Array.isArray(answer?.choices) ? answer.choices : [])
+      .filter((choice) => typeof choice === 'string')
+      .map((choice) => choice.slice(0, 500))
+      .slice(0, 8),
+    ...(typeof answer?.custom === 'string' && answer.custom.trim()
+      ? { custom: answer.custom.slice(0, 4000) }
+      : {}),
+  }))
+  if (skipped) ask.finish({ skipped: true })
+  else ask.finish({ answers: normalizedAnswers })
+  return { answered: true, askId, skipped: !!skipped }
+}
+
 export function abortToolCall(sessionId, toolCallId) {
   const session = agentSessions.get(sessionId)
   if (!session) {

package/server/approval-store.mjs

@@ -31,6 +31,7 @@ export const planAllowedTools = new Set([
   'activate_skill',
   'read_skill_resource',
   'run_subagent',
+  'ask_user',
 ])
 
 export const safeReadTools = new Set([

package/server/ask-store.mjs

@@ -0,0 +1,78 @@
+/**
+ * Ask-user store — shared pending-question state.
+ *
+ * The Promise-based ask flow (createAskUserPromise) lives in agent-manager.mjs
+ * because it depends on the agent event buses; this module only holds the
+ * pending queue, mirroring approval-store.mjs.
+ */
+
+// Waiting for a user decision is not a security gate — allow generous time
+// before resolving as skipped so the agent can continue on its own.
+export const ASK_TIMEOUT_MS = 30 * 60 * 1000 // 30 minutes
+
+/** askId → { finish, sessionId, toolCallId, questions, requestedAt, expiresAt } */
+export const pendingAsks = new Map()
+
+export function getPendingAskForSession(sessionId) {
+  for (const [askId, ask] of pendingAsks) {
+    if (ask.sessionId === sessionId) {
+      return {
+        askId,
+        toolCallId: ask.toolCallId,
+        questions: ask.questions,
+        requestedAt: ask.requestedAt,
+        expiresAt: ask.expiresAt,
+      }
+    }
+  }
+  return null
+}
+
+// ---------------------------------------------------------------------------
+// Pure helpers (no dependencies — unit-tested directly)
+// ---------------------------------------------------------------------------
+
+/** Normalize ask_user params into a bounded questions list (robust against model shorthand). */
+export function normalizeAskQuestions(params) {
+  const rawQuestions = Array.isArray(params?.questions)
+    ? params.questions
+    : (typeof params?.question === 'string' ? [{ ...params }] : [])
+  return rawQuestions
+    .filter((q) => q && typeof q.question === 'string' && q.question.trim())
+    .slice(0, 4)
+    .map((q) => ({
+      question: String(q.question),
+      multiSelect: q.multiSelect === true,
+      allowCustom: q.allowCustom === false ? false : true,
+      options: (Array.isArray(q.options) ? q.options : [])
+        .filter((option) => option && typeof option.label === 'string' && option.label.trim())
+        .slice(0, 4)
+        .map((option) => ({
+          label: String(option.label),
+          ...(typeof option.description === 'string' && option.description ? { description: option.description } : {}),
+        })),
+    }))
+}
+
+/** Render the tool-result text returned to the model. */
+export function formatAskResult(questions, answers, skipped, reason) {
+  if (skipped) {
+    const note = reason === 'timeout'
+      ? '（等待超时）'
+      : reason === 'aborted'
+        ? '（运行被停止）'
+        : reason === 'no-questions'
+          ? '（问题列表无效）'
+          : '（用户跳过）'
+    return `用户没有回答这些问题${note}。请按你的默认方案继续，不要再重复追问。`
+  }
+  const lines = questions.map((q, index) => {
+    const answer = answers?.[index]
+    if (!answer) return `${index + 1}. ${q.question} → 用户未回答`
+    const choiceText = Array.isArray(answer.choices) && answer.choices.length ? answer.choices.join('、') : ''
+    const customText = typeof answer.custom === 'string' && answer.custom.trim() ? answer.custom.trim() : ''
+    const text = [choiceText, customText].filter(Boolean).join('　补充：')
+    return `${index + 1}. ${q.question} → ${text || '用户未回答'}`
+  })
+  return `用户的回答：\n${lines.join('\n')}`
+}