fix(tools): 本会话允许审批 + 工具轮次触顶强制收尾

主助手多步 shell 任务会反复弹审批且 10 轮触顶后半截结束；增加「本会话允许」跳过同工具后续确认，并将 maxIterations 提到 32、触顶后强制无工具收尾。

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: shijianzhong

src/main/ipc/home.ts

@@ -36,6 +36,7 @@ import { getClient } from '../llm/retry'
 import { resolveThinkingConfig } from '../llm/thinking'
 import { listToolsForAgents } from '../tools/mcp'
 import { listMemoryKeysForPrompt } from '../tools/builtin/memory'
+import { resolveApprovalDecision } from '../tools/sessionApprovals'
 import {
   newRequestId,
   rejectAllUserInputs,
@@ -263,6 +264,7 @@ export function registerHomeHandlers(): void {
           }
         },
         // HITL 工具审批桥（shell_run / MCP always 工具）：approval_request 事件 + 挂起等用户确认
+        // 应答 approved / approved_session / denied（本会话允许写入 sessionApprovals）
         onApprove: async ({ toolName, args }) => {
           const requestId = newRequestId()
           const emit = (event: import('@shared/types').StreamEvent): void =>
@@ -271,7 +273,7 @@ export function registerHomeHandlers(): void {
           try {
             const response = await waitForUserInput(requestId, { nodeId: 'home', question: `approve ${toolName}` }, signal)
             emit({ type: 'approval_resolved', request_id: requestId, node_id: 'home', response })
-            return { approved: response === 'approved', reason: response === 'approved' ? undefined : response }
+            return resolveApprovalDecision(response, sid, toolName)
           } catch (e) {
             emit({ type: 'approval_resolved', request_id: requestId, node_id: 'home', response: '' })
             return { approved: false, reason: 'timeout or cancelled' }
@@ -345,7 +347,7 @@ export function registerHomeHandlers(): void {
                 throw e
               }
             },
-            // HITL 工具审批桥：approvalMode='always' → approval_request 事件 + 挂起等用户确认
+            // HITL 工具审批桥：approvalMode='always' → approval_request；支持本会话允许
             onApprove: async ({ toolName, args }) => {
               const requestId = newRequestId()
               const emit = (event: import('@shared/types').StreamEvent): void =>
@@ -354,7 +356,7 @@ export function registerHomeHandlers(): void {
               try {
                 const response = await waitForUserInput(requestId, { nodeId: node.id, question: `approve ${toolName}` }, signal)
                 emit({ type: 'approval_resolved', request_id: requestId, node_id: node.id, response })
-                return { approved: response === 'approved', reason: response === 'approved' ? undefined : response }
+                return resolveApprovalDecision(response, sid, toolName)
               } catch (e) {
                 emit({ type: 'approval_resolved', request_id: requestId, node_id: node.id, response: '' })
                 return { approved: false, reason: 'timeout or cancelled' }
@@ -418,6 +420,9 @@ export function registerHomeHandlers(): void {
       )
       finalText = result.finalText
       finalThinking = result.finalThinking
+      if (result.hitIterationLimit) {
+        logger.warn('[home] 主 Agent 达工具轮次上限，已强制无工具收尾')
+      }
 
       // 流结束：判定直答 vs 组队
       const decision = detector.decide()
@@ -463,8 +468,11 @@ export function registerHomeHandlers(): void {
         logger.warn('[l2] 精炼失败', e),
       )
 
-      // 10. 结束事件
-      emitStream({ type: 'message_stop', stop_reason: 'end_turn' })
+      // 10. 结束事件：触顶收尾用 max_iterations，便于前端/日志区分假 end_turn
+      emitStream({
+        type: 'message_stop',
+        stop_reason: result.hitIterationLimit ? 'max_iterations' : 'end_turn',
+      })
     } catch (e) {
       // 错误推到 AI 气泡位置（而非聊天区上方），含可重试提示
       const msg = e instanceof Error ? e.message : String(e)

src/main/ipc/orchestrate.ts

@@ -21,6 +21,7 @@ import { getSkill, getAgent, getDefaultProvider, resolveProviderCredentials } fr
 import { addMessage } from '../storage/sessions'
 import { SkillContextProvider } from '../skills/provider'
 import { listToolsForAgents } from '../tools/mcp'
+import { resolveApprovalDecision } from '../tools/sessionApprovals'
 import { resolveThinkingConfig } from '../llm/thinking'
 import type { AgentExecutorOptions } from '../orchestrator/patterns/agent'
 import { logger } from '../logger'
@@ -59,6 +60,8 @@ function makeResolveAgent(
   signal?: AbortSignal,
   /** R1/R2：builtin + 显式暴露的 MCP 工具快照（一次运行内固定） */
   agentTools: LlmToolDef[] = [],
+  /** 会话 id：本会话允许工具审批放行键；编辑器试跑可能为空 */
+  sessionId?: string,
 ): {
   resolveAgent: (node: GraphNode) => AgentExecutorOptions | null
   /** 本运行创建的全部 SkillContextProvider（运行结束统一 afterRun 审计，铁律22） */
@@ -139,6 +142,7 @@ function makeResolveAgent(
       config,
       llmOpts: { apiKey, baseURL, authHeader },
       toolCtx: {
+        sessionId,
         signal,
         // HITL 提问桥：ask_user → request_info 事件推前端 + 挂起等作答（userInput 队列）
         onAskUser: async ({ question, context }) => {
@@ -154,14 +158,14 @@ function makeResolveAgent(
             throw e
           }
         },
-        // HITL 工具审批桥：approvalMode='always' → approval_request 事件 + 挂起等用户确认
+        // HITL 工具审批桥：支持本会话允许（sessionId 有值时写入放行表）
         onApprove: async ({ toolName, args }) => {
           const requestId = newRequestId()
           emitStream({ type: 'approval_request', request_id: requestId, node_id: node.id, tool_name: toolName, args })
           try {
             const response = await waitForUserInput(requestId, { nodeId: node.id, question: `approve ${toolName}` }, signal)
             emitStream({ type: 'approval_resolved', request_id: requestId, node_id: node.id, response })
-            return { approved: response === 'approved', reason: response === 'approved' ? undefined : response }
+            return resolveApprovalDecision(response, sessionId, toolName)
           } catch (e) {
             emitStream({ type: 'approval_resolved', request_id: requestId, node_id: node.id, response: '' })
             return { approved: false, reason: 'timeout or cancelled' }
@@ -200,7 +204,7 @@ export function registerOrchestrateHandlers(): void {
       const { signal } = currentAbortController
       const agentTools = await listToolsForAgents()
       const { resolveAgent, skillProviders } = makeResolveAgent(
-        modelId, apiKey, baseURL, authHeader, enableThinking, apiFormat, signal, agentTools,
+        modelId, apiKey, baseURL, authHeader, enableThinking, apiFormat, signal, agentTools, sessionId,
       )
       const deps: BuildDeps = { resolveAgent }
 

src/main/ipc/sessions.ts

@@ -10,6 +10,7 @@ import {
   removeSession,
   renameSession,
 } from '../storage/sessions'
+import { clearSessionToolApprovals } from '../tools/sessionApprovals'
 
 // —— 会话历史 IPC（§八之二 B）——
 // 入参 Zod 校验：IPC 边界不做隐式 as 断言，畸形参数在入口处结构化报错（P1-12）。
@@ -31,7 +32,11 @@ const AddMessageSchema = z.object({
 export function registerSessionsHandlers(): void {
   withHandler<Session[]>('sessions:list', () => listSessions())
   withHandler<Session | null>('sessions:get', (_e, id) => getSession(IdSchema.parse(id)))
-  withHandler<void>('sessions:remove', (_e, id) => removeSession(IdSchema.parse(id)))
+  withHandler<void>('sessions:remove', (_e, id) => {
+    const sid = IdSchema.parse(id)
+    removeSession(sid)
+    clearSessionToolApprovals(sid) // 删会话时清掉「本会话允许」放行
+  })
   withHandler<void>('sessions:rename', (_e, id, title) =>
     renameSession(IdSchema.parse(id), z.string().min(1).parse(title)),
   )

src/main/orchestrator/agent-iterations.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+import type { LlmRequest, LlmResponse } from '@shared/types'
+import { Agent } from './agent'
+
+// —— maxIterations 触顶收尾：不能静默停在半截 tool_use ——
+
+const streamMock = vi.fn<(req: LlmRequest) => Promise<LlmResponse>>()
+
+vi.mock('../llm/retry', () => ({
+  getClient: () => ({ stream: (req: LlmRequest) => streamMock(req) }),
+}))
+
+vi.mock('../tools/registry', () => ({
+  executeTool: vi.fn(async (_name: string, _args: unknown, id: string) => ({
+    toolUseId: id,
+    content: JSON.stringify({ ok: true }),
+    isError: false,
+  })),
+  getToolDefs: () => [],
+}))
+
+function toolUseTurn(text: string, callId: string): LlmResponse {
+  return {
+    stopReason: 'tool_use',
+    content: [
+      ...(text ? [{ type: 'text' as const, text }] : []),
+      { type: 'tool_use' as const, id: callId, name: 'web_search', input: { q: 'x' } },
+    ],
+  }
+}
+
+describe('Agent maxIterations 收尾', () => {
+  beforeEach(() => {
+    streamMock.mockReset()
+  })
+
+  it('触顶且最后一轮仍是 tool_use → 再打一轮无工具收尾，不把半截话当终局', async () => {
+    // 2 轮 tool_use + 1 轮强制收尾
+    streamMock
+      .mockResolvedValueOnce(toolUseTurn('先查一下…', 'tu_0'))
+      .mockResolvedValueOnce(toolUseTurn('继续查…', 'tu_1'))
+      .mockResolvedValueOnce({
+        stopReason: 'end_turn',
+        content: [{ type: 'text', text: '根据已有结果，结论是这样。' }],
+      })
+
+    const agent = new Agent(
+      {
+        name: 'home',
+        instructions: '助手',
+        modelId: 'fake',
+        tools: [{ name: 'web_search', description: 's', input_schema: { type: 'object' } }],
+        defaultOptions: { maxTokens: 1024 },
+      },
+      { llmOpts: {} },
+    )
+
+    const result = await agent.run(
+      { messages: [{ role: 'user', content: '调研一下' }] },
+      {},
+      { maxIterations: 2 },
+    )
+
+    expect(streamMock).toHaveBeenCalledTimes(3)
+    // 收尾轮不得再挂 tools
+    const finalReq = streamMock.mock.calls[2][0]
+    expect(finalReq.tools).toBeUndefined()
+    expect(result.finalText).toBe('根据已有结果，结论是这样。')
+    expect(result.hitIterationLimit).toBe(true)
+  })
+
+  it('正常 end_turn 提前结束 → 不额外收尾轮，hitIterationLimit=false', async () => {
+    streamMock.mockResolvedValueOnce({
+      stopReason: 'end_turn',
+      content: [{ type: 'text', text: '直接答完' }],
+    })
+
+    const agent = new Agent(
+      {
+        name: 'a',
+        instructions: 'x',
+        modelId: 'fake',
+        defaultOptions: { maxTokens: 1024 },
+      },
+      { llmOpts: {} },
+    )
+
+    const result = await agent.run(
+      { messages: [{ role: 'user', content: 'hi' }] },
+      {},
+      { maxIterations: 2 },
+    )
+
+    expect(streamMock).toHaveBeenCalledTimes(1)
+    expect(result.finalText).toBe('直接答完')
+    expect(result.hitIterationLimit).toBe(false)
+  })
+})

src/main/orchestrator/agent.ts

@@ -18,8 +18,12 @@ import { logger } from '../logger'
 // Agent 管 context（messages/system/options），tool-use 循环借力 SDK
 // （循环在 LLMClient.stream 内由 stop_reason 驱动，这里只编排多轮）。
 // maxTokens 从 config.defaultOptions 取（铁律8）。
+//
+// maxIterations 是防死循环保险丝，不是「任务做完」信号：
+// 触顶且末轮仍是 tool_use 时，强制再打一轮无工具收尾，避免半截话当终局。
 
-const DEFAULT_MAX_ITERATIONS = 10
+/** 工具循环默认上限（原 10 对多步 shell/检索任务偏紧） */
+export const DEFAULT_MAX_ITERATIONS = 32
 
 /**
  * 运行时上下文注入（system 末尾）：当前本地时间 + 时区。
@@ -60,21 +64,29 @@ export class Agent {
    * 1. 组装 messages + system + tools + maxTokens（从 defaultOptions）
    * 2. stream LLM，逐 delta 回调
    * 3. 若 stop_reason='tool_use' → 执行工具 → 追加 tool_result → 继续循环
-   * 4. 直至 stop_reason 非 tool_use 或达上限
+   * 4. 直至 stop_reason 非 tool_use；若触顶仍停在 tool_result 后 → 强制无工具收尾轮
    */
   async run(
     input: AgentRunInput,
     callbacks: AgentRunCallbacks = {},
     limits: AgentLimits = {},
-  ): Promise<{ messages: LlmMessage[]; finalText: string; finalThinking: string }> {
+  ): Promise<{
+    messages: LlmMessage[]
+    finalText: string
+    finalThinking: string
+    /** 是否因 maxIterations 触顶而强制收尾（非正常 end_turn） */
+    hitIterationLimit: boolean
+  }> {
     const maxIter = limits.maxIterations ?? DEFAULT_MAX_ITERATIONS
     let functionCallCount = 0
     const messages = [...input.messages]
     const tools = this.resolveTools()
     const client = getClient(this.config.modelId, this.deps.llmOpts)
+    const system = injectRuntimeContext(this.config.instructions)
 
     let finalText = ''
     let finalThinking = ''
+    let hitIterationLimit = false
 
     for (let iter = 0; iter < maxIter; iter++) {
       if (input.signal?.aborted) {
@@ -84,7 +96,7 @@ export class Agent {
       logger.debug('[agent] thinking config:', this.config.thinking)
       const response = await client.stream({
         model: this.config.modelId,
-        system: injectRuntimeContext(this.config.instructions),
+        system,
         messages,
         tools: tools.length ? tools : undefined,
         maxTokens: this.config.defaultOptions.maxTokens, // 铁律8
@@ -166,9 +178,38 @@ export class Agent {
         finalText = JSON.stringify({ handoff_to: handoffTarget })
         break
       }
+
+      // 本轮是最后一轮迭代槽且刚执行完工具 → 循环将结束，标记需收尾
+      if (iter === maxIter - 1) {
+        hitIterationLimit = true
+      }
+    }
+
+    // 触顶停在 tool_result 之后：强制无工具收尾，让模型基于已有结果给最终答复
+    if (hitIterationLimit && needsToolResultFinalization(messages) && !input.signal?.aborted) {
+      logger.warn(
+        `[agent:${this.config.name}] 达 maxIterations=${maxIter}，强制无工具收尾轮`,
+      )
+      const response = await client.stream({
+        model: this.config.modelId,
+        system,
+        messages,
+        tools: undefined, // 禁止再调工具
+        maxTokens: this.config.defaultOptions.maxTokens,
+        temperature: this.config.defaultOptions.temperature,
+        thinking: this.config.thinking,
+        signal: input.signal,
+        onDelta: (delta: LlmDelta) => this.emitDelta(delta, callbacks),
+        onRetry: (info) => callbacks.onRetry?.(info),
+      })
+      messages.push({ role: 'assistant', content: response.content })
+      const text = extractText(response.content)
+      if (text) finalText = text
+      const thinkingText = extractThinking(response.content)
+      if (thinkingText) finalThinking = thinkingText
     }
 
-    return { messages, finalText, finalThinking }
+    return { messages, finalText, finalThinking, hitIterationLimit }
   }
 
   private resolveTools() {
@@ -196,4 +237,12 @@ function extractThinking(blocks: LlmContentBlock[]): string {
     .map((b) => b.thinking)
     .join('')
 }
+
+/** 末条是否为 tool_result user 消息（触顶后尚无最终 assistant 答复） */
+function needsToolResultFinalization(messages: LlmMessage[]): boolean {
+  const last = messages[messages.length - 1]
+  if (!last || last.role !== 'user' || typeof last.content === 'string') return false
+  return last.content.some((b) => b.type === 'tool_result')
+}
+
 export type { LlmResponse }

src/main/tools/builtin/shell.ts

@@ -7,8 +7,9 @@ import { logger } from '../../logger'
 // —— shell_run 工具（P1 · task.md 7.1）——
 // 让 AI 在用户确认后执行 shell 命令（安装 CLI、跑系统级操作、驱动无 MCP 封装的上游工具）。
 // 复刻 opencli_run / skill_run_script 的 async spawn 纪律（铁律 23）。
-// 安全：approvalMode='always'（P0 闸门执行）+ DANGER_PATTERNS 辅助硬拦（preCheck）+ env 敏感值过滤。
-// 正则黑名单可被绕过，真正边界是 P0 的每次确认 + 用户知情。
+// 安全：approvalMode='always'（P0 闸门）+ 可选「本会话允许」跳过后续弹窗
+// + DANGER_PATTERNS 辅助硬拦（preCheck，会话放行也不绕过）+ env 敏感值过滤。
+// 正则黑名单可被绕过，真正边界是 P0 确认（或会话级信任）+ 用户知情。
 
 const DEFAULT_TIMEOUT_MS = 120_000
 const MAX_TIMEOUT_SEC = 300