wave-agent-sdk 0.18.3 → 0.18.4

package/src/managers/aiManager.ts

@@ -21,7 +21,7 @@ import type { ToolContext, ToolResult } from "../tools/types.js";
 import type { MessageManager } from "./messageManager.js";
 import type { BackgroundTaskManager } from "./backgroundTaskManager.js";
 import { ChatCompletionMessageFunctionToolCall } from "openai/resources.js";
-import type { ChatCompletionMessageParam } from "openai/resources.js";
+
 import type { HookManager } from "./hookManager.js";
 import type { ExtendedHookExecutionContext } from "../types/hooks.js";
 import type { PermissionManager } from "./permissionManager.js";
@@ -297,12 +297,11 @@ export class AIManager {
     }
   }
 
-  private async maybeInjectTaskReminderIntoMessages(
-    messages: ChatCompletionMessageParam[],
+  private async maybeGetTaskReminderText(
     toolNames: Set<string>,
-  ): Promise<void> {
+  ): Promise<string | null> {
     // Guard: no task tools available
-    if (!toolNames.has("TaskUpdate")) return;
+    if (!toolNames.has("TaskUpdate")) return null;
 
     const internalMessages = this.messageManager.getMessages();
     const turnCounts = getTaskReminderTurnCounts(internalMessages);
@@ -313,11 +312,11 @@ export class AIManager {
       turnCounts.turnsSinceLastReminder <
         TASK_REMINDER_CONFIG.TURNS_BETWEEN_REMINDERS
     ) {
-      return;
+      return null;
     }
 
     const tasks = await this.taskManager.listTasks();
-    maybeInjectTaskReminder(messages, turnCounts, tasks);
+    return maybeInjectTaskReminder(turnCounts, tasks);
   }
 
   public setIsLoading(isLoading: boolean): void {
@@ -743,481 +742,531 @@ export class AIManager {
     } = {},
   ): Promise<void> {
     const { recursionDepth = 0, model, allowedRules, maxTokens } = options;
+    let turnOffset = recursionDepth;
 
-    // OpenTelemetry: start interaction span for this turn (initial call only)
-    let turnSequence = 0;
-    if (recursionDepth === 0) {
-      const messages = this.messageManager.getMessages();
-      turnSequence = messages.filter((m) => m.role === "user").length;
-      const lastUserMessage = [...messages]
-        .reverse()
-        .find((m) => m.role === "user");
-      const userPromptText =
-        lastUserMessage?.blocks.find((b) => b.type === "text")?.content || "";
-      startInteractionSpan(userPromptText, turnSequence);
-
-      // Log user_prompt event
-      logOTelEvent("user_prompt", {
-        prompt_length: String(userPromptText.length),
-      }).catch(() => {}); // Non-blocking
-    }
+    outer: while (true) {
+      let shouldRestart = false;
+
+      // OpenTelemetry: start interaction span for this turn (initial call only)
+      let turnSequence = 0;
+      if (turnOffset === 0) {
+        const messages = this.messageManager.getMessages();
+        turnSequence = messages.filter((m) => m.role === "user").length;
+        const lastUserMessage = [...messages]
+          .reverse()
+          .find((m) => m.role === "user");
+        const userPromptText =
+          lastUserMessage?.blocks.find((b) => b.type === "text")?.content || "";
+        startInteractionSpan(userPromptText, turnSequence);
+
+        // Log user_prompt event
+        logOTelEvent("user_prompt", {
+          prompt_length: String(userPromptText.length),
+        }).catch(() => {}); // Non-blocking
+      }
 
-    // Set loading state early for the initial call, before any async work
-    if (recursionDepth === 0) {
-      this.setIsLoading(true);
-      if (allowedRules && allowedRules.length > 0) {
-        this.permissionManager?.addTemporaryRules(allowedRules);
+      // Set loading state early for the initial call, before any async work
+      if (turnOffset === 0) {
+        this.setIsLoading(true);
+        if (allowedRules && allowedRules.length > 0) {
+          this.permissionManager?.addTemporaryRules(allowedRules);
+        }
       }
-    }
 
-    // Scan for file mentions in the last user message
-    if (recursionDepth === 0) {
-      const messages = this.messageManager.getMessages();
-      const lastMessage = messages[messages.length - 1];
-      if (lastMessage && lastMessage.role === "user") {
-        for (const block of lastMessage.blocks) {
-          if (block.type === "text") {
-            const content = block.content;
-            const fileMentionRegex = /(?:^|\s)@([\w.\-/]+)/g;
-            let match;
-            while ((match = fileMentionRegex.exec(content)) !== null) {
-              const filePath = match[1];
-              this.messageManager.touchFile(filePath);
+      // Scan for file mentions in the last user message to trigger conditional rules
+      if (turnOffset === 0) {
+        const messages = this.messageManager.getMessages();
+        const lastMessage = messages[messages.length - 1];
+        if (lastMessage && lastMessage.role === "user") {
+          for (const block of lastMessage.blocks) {
+            if (block.type === "text") {
+              const content = block.content;
+              const fileMentionRegex = /(?:^|\s)@([\w.\-/]+)/g;
+              let match;
+              while ((match = fileMentionRegex.exec(content)) !== null) {
+                const filePath = match[1];
+                this.messageManager.triggerFileRead(filePath);
+              }
             }
           }
         }
       }
-    }
-
-    // Save session in each recursion to ensure message persistence
-    await this.messageManager.saveSession();
 
-    // Only create new AbortControllers for the initial call (recursionDepth === 0)
-    // For recursive calls, reuse existing controllers to maintain abort signal
-    let abortController: AbortController;
-    let toolAbortController: AbortController;
+      // Only create new AbortControllers for the initial call (turnOffset === 0)
+      // For restarts, reuse existing controllers to maintain abort signal
+      let abortController: AbortController;
+      let toolAbortController: AbortController;
 
-    if (recursionDepth === 0) {
-      // Create new AbortControllers for initial call
-      abortController = new AbortController();
-      this.abortController = abortController;
+      if (turnOffset === 0) {
+        // Create new AbortControllers for initial call
+        abortController = new AbortController();
+        this.abortController = abortController;
 
-      toolAbortController = new AbortController();
-      this.toolAbortController = toolAbortController;
-    } else {
-      // Reuse existing controllers for recursive calls
-      abortController = this.abortController!;
-      toolAbortController = this.toolAbortController!;
-    }
-
-    // Get current permission mode
-    const currentMode = this.permissionManager?.getCurrentEffectiveMode(
-      this.getModelConfig().permissionMode,
-    );
+        toolAbortController = new AbortController();
+        this.toolAbortController = toolAbortController;
+      } else {
+        // Reuse existing controllers
+        abortController = this.abortController!;
+        toolAbortController = this.toolAbortController!;
+      }
 
-    // Add plan mode reminder as persistent meta message before getting messages
-    this.maybeAddPlanModeMessage(currentMode);
+      let turnDepth = turnOffset;
 
-    // Get recent message history
-    const rawMessages = this.messageManager.getMessages();
-    const recentMessages = convertMessagesForAPI(rawMessages);
+      inner: while (true) {
+        try {
+          // Save session in each iteration to ensure message persistence
+          await this.messageManager.saveSession();
 
-    try {
-      // Get combined memory content
-      const combinedMemory = await this.messageManager.getCombinedMemory();
+          // Get current permission mode
+          const currentMode = this.permissionManager?.getCurrentEffectiveMode(
+            this.getModelConfig().permissionMode,
+          );
 
-      // Track if assistant message has been created
-      let assistantMessageCreated = false;
+          // Add plan mode reminder as persistent meta message before getting messages
+          this.maybeAddPlanModeMessage(currentMode);
 
-      logger?.debug("modelConfig in sendAIMessage", this.getModelConfig());
+          // Process conditional rules triggered by file reads (persist as meta messages)
+          const triggeredRules = this.messageManager.processTriggeredRules();
+          for (const rule of triggeredRules) {
+            this.messageManager.addUserMessage({
+              content: `<!-- rule: ${rule.id} -->\n<system-reminder>\nThe following rules from .wave/rules apply to your work. Be sure to adhere to these instructions.\n\n${rule.content}\n</system-reminder>`,
+              isMeta: true,
+            });
+          }
 
-      const toolsConfig = this.getFilteredToolsConfig();
-      const toolNames = new Set(toolsConfig.map((t) => t.function.name));
-      const filteredToolPlugins = this.toolManager
-        .getTools()
-        .filter((t) => toolNames.has(t.name));
+          // Get recent message history
+          const rawMessages = this.messageManager.getMessages();
+          const recentMessages = convertMessagesForAPI(rawMessages);
 
-      let autoMemoryOptions: { directory: string; content: string } | undefined;
+          // Track if assistant message has been created
+          let assistantMessageCreated = false;
 
-      if (this.getAutoMemoryEnabled()) {
-        const directory = this.memoryService.getAutoMemoryDirectory(
-          this.getWorkdir(),
-        );
-        const content = await this.memoryService.getAutoMemoryContent(
-          this.getWorkdir(),
-        );
-        autoMemoryOptions = { directory, content };
-      }
+          logger?.debug("modelConfig in sendAIMessage", this.getModelConfig());
 
-      // Call AI service with streaming callbacks if enabled
-      const callAgentOptions: CallAgentOptions = {
-        gatewayConfig: this.getGatewayConfig(),
-        modelConfig: this.getModelConfig(),
-        messages: recentMessages,
-        sessionId: this.messageManager.getSessionId(),
-        abortSignal: abortController.signal,
-        workdir: this.getWorkdir(), // Pass working directory
-        tools: toolsConfig, // Pass filtered tool configuration
-        model: model, // Use passed model
-        systemPrompt: buildSystemPrompt(
-          this.systemPrompt,
-          filteredToolPlugins,
-          {
-            workdir: this.getWorkdir(),
-            originalWorkdir: this.getOriginalWorkdir(),
-            memory: combinedMemory,
-            language: this.getLanguage(),
-            isSubagent: !!this.subagentType,
-            autoMemory: autoMemoryOptions,
-            permissionMode: currentMode,
-          },
-        ), // Pass custom system prompt
-        maxTokens: maxTokens, // Pass max tokens override
-        toolChoice: this.toolChoiceOverride, // Pass tool_choice override
-      };
+          const toolsConfig = this.getFilteredToolsConfig();
+          const toolNames = new Set(toolsConfig.map((t) => t.function.name));
+          const filteredToolPlugins = this.toolManager
+            .getTools()
+            .filter((t) => toolNames.has(t.name));
 
-      // Inject task reminder if needed (not persisted, regenerated each turn)
-      await this.maybeInjectTaskReminderIntoMessages(
-        callAgentOptions.messages,
-        toolNames,
-      );
+          let autoMemoryOptions:
+            | { directory: string; content: string }
+            | undefined;
 
-      // Add streaming callbacks only if streaming is enabled
-      if (this.stream) {
-        callAgentOptions.onContentUpdate = (content: string) => {
-          // Create assistant message on first chunk if not already created
-          if (!assistantMessageCreated) {
-            this.messageManager.addAssistantMessage();
-            assistantMessageCreated = true;
-          }
-          this.messageManager.updateCurrentMessageContent(content);
-        };
-        callAgentOptions.onToolUpdate = (toolCall) => {
-          // Create assistant message on first tool update if not already created
-          if (!assistantMessageCreated) {
-            this.messageManager.addAssistantMessage();
-            assistantMessageCreated = true;
+          if (this.getAutoMemoryEnabled()) {
+            const directory = this.memoryService.getAutoMemoryDirectory(
+              this.getWorkdir(),
+            );
+            const content = await this.memoryService.getAutoMemoryContent(
+              this.getWorkdir(),
+            );
+            autoMemoryOptions = { directory, content };
           }
 
-          // Use parametersChunk as compact param for better performance
-          // No need to extract params or generate compact params during streaming
-
-          // Update tool block with streaming parameters using parametersChunk as compact param
-          this.messageManager.updateToolBlock({
-            id: toolCall.id,
-            name: toolCall.name,
-            parameters: toolCall.parameters,
-            parametersChunk: toolCall.parametersChunk,
-            stage: toolCall.stage || "streaming", // Default to streaming if stage not provided
-          });
-        };
-        callAgentOptions.onReasoningUpdate = (reasoning: string) => {
-          // Create assistant message on first reasoning update if not already created
-          if (!assistantMessageCreated) {
-            this.messageManager.addAssistantMessage();
-            assistantMessageCreated = true;
+          // Get memory for message-array injection (not system prompt)
+          const { prependContent } =
+            await this.messageManager.getMemoryForInjection();
+
+          // Call AI service with streaming callbacks if enabled
+          const callAgentOptions: CallAgentOptions = {
+            gatewayConfig: this.getGatewayConfig(),
+            modelConfig: this.getModelConfig(),
+            messages: recentMessages,
+            sessionId: this.messageManager.getSessionId(),
+            abortSignal: abortController.signal,
+            workdir: this.getWorkdir(), // Pass working directory
+            tools: toolsConfig, // Pass filtered tool configuration
+            model: model, // Use passed model
+            systemPrompt: buildSystemPrompt(
+              this.systemPrompt,
+              filteredToolPlugins,
+              {
+                workdir: this.getWorkdir(),
+                originalWorkdir: this.getOriginalWorkdir(),
+                language: this.getLanguage(),
+                isSubagent: !!this.subagentType,
+                autoMemory: autoMemoryOptions,
+              },
+            ), // Pass custom system prompt
+            maxTokens: maxTokens, // Pass max tokens override
+            toolChoice: this.toolChoiceOverride, // Pass tool_choice override
+          };
+
+          // Prepend: AGENTS.md + user memory + unconditional rules as system-reminder
+          if (prependContent.trim()) {
+            callAgentOptions.messages.unshift({
+              role: "user",
+              content: `<system-reminder>\n${prependContent}\n</system-reminder>`,
+            });
           }
-          this.messageManager.updateCurrentMessageReasoning(reasoning);
-        };
-      }
-
-      startLLMRequestSpan(model || this.getModelConfig().model || "");
 
-      const result = await aiService.callAgent(callAgentOptions);
-
-      // End LLM span with usage data
-      endLLMRequestSpan({
-        model: model || this.getModelConfig().model || "",
-        success: true,
-        hasToolCall: !!(result.tool_calls && result.tool_calls.length > 0),
-      });
-
-      const createdByStreaming = assistantMessageCreated;
-
-      // For non-streaming mode, create assistant message after callAgent returns
-      // Also create if streaming mode but no streaming callbacks were called (e.g., when content comes directly in result)
-      if (
-        !this.stream ||
-        (!assistantMessageCreated &&
-          (result.content || result.tool_calls || result.reasoning_content))
-      ) {
-        this.messageManager.addAssistantMessage();
-        assistantMessageCreated = true;
-      }
+          // Task reminder: persist as meta message (conditional rules already persisted above)
+          const taskReminderText =
+            await this.maybeGetTaskReminderText(toolNames);
+          if (taskReminderText) {
+            this.messageManager.addUserMessage({
+              content: taskReminderText,
+              isMeta: true,
+            });
+          }
 
-      // Log finish reason and response headers if available
-      if (result.finish_reason) {
-        // Log warning headers when finish reason is length
-        if (result.finish_reason === "length") {
-          logger?.warn(
-            "AI response truncated due to length limit. Response headers:",
-            result.response_headers,
-          );
-        }
-      }
+          // Add streaming callbacks only if streaming is enabled
+          if (this.stream) {
+            callAgentOptions.onContentUpdate = (content: string) => {
+              // Create assistant message on first chunk if not already created
+              if (!assistantMessageCreated) {
+                this.messageManager.addAssistantMessage();
+                assistantMessageCreated = true;
+              }
+              this.messageManager.updateCurrentMessageContent(content);
+            };
+            callAgentOptions.onToolUpdate = (toolCall) => {
+              // Create assistant message on first tool update if not already created
+              if (!assistantMessageCreated) {
+                this.messageManager.addAssistantMessage();
+                assistantMessageCreated = true;
+              }
 
-      if (
-        result.additionalFields &&
-        Object.keys(result.additionalFields).length > 0
-      ) {
-        this.messageManager.mergeAssistantAdditionalFields(
-          result.additionalFields,
-        );
-      }
+              // Use parametersChunk as compact param for better performance
+              // No need to extract params or generate compact params during streaming
 
-      // Handle result reasoning content from non-streaming mode
-      if (result.reasoning_content && !createdByStreaming) {
-        this.messageManager.updateCurrentMessageReasoning(
-          result.reasoning_content,
-        );
-      }
+              // Update tool block with streaming parameters using parametersChunk as compact param
+              this.messageManager.updateToolBlock({
+                id: toolCall.id,
+                name: toolCall.name,
+                parameters: toolCall.parameters,
+                parametersChunk: toolCall.parametersChunk,
+                stage: toolCall.stage || "streaming", // Default to streaming if stage not provided
+              });
+            };
+            callAgentOptions.onReasoningUpdate = (reasoning: string) => {
+              // Create assistant message on first reasoning update if not already created
+              if (!assistantMessageCreated) {
+                this.messageManager.addAssistantMessage();
+                assistantMessageCreated = true;
+              }
+              this.messageManager.updateCurrentMessageReasoning(reasoning);
+            };
+          }
 
-      // Handle result content from non-streaming mode
-      if (result.content && !createdByStreaming) {
-        this.messageManager.updateCurrentMessageContent(result.content);
-      }
+          startLLMRequestSpan(model || this.getModelConfig().model || "");
 
-      // Handle usage tracking for agent operations
-      let usage: Usage | undefined;
-      if (result.usage) {
-        usage = {
-          prompt_tokens: result.usage.prompt_tokens,
-          completion_tokens: result.usage.completion_tokens,
-          total_tokens: result.usage.total_tokens,
-          model: model || this.getModelConfig().model,
-          operation_type: "agent",
-          // Preserve cache fields if present
-          ...(result.usage.cache_read_input_tokens !== undefined && {
-            cache_read_input_tokens: result.usage.cache_read_input_tokens,
-          }),
-          ...(result.usage.cache_creation_input_tokens !== undefined && {
-            cache_creation_input_tokens:
-              result.usage.cache_creation_input_tokens,
-          }),
-          ...(result.usage.cache_creation && {
-            cache_creation: result.usage.cache_creation,
-          }),
-        };
-      }
+          const result = await aiService.callAgent(callAgentOptions);
 
-      // Set usage on the assistant message if available
-      if (usage) {
-        const messages = this.messageManager.getMessages();
-        const lastMessage = messages[messages.length - 1];
-        if (lastMessage && lastMessage.role === "assistant") {
-          lastMessage.usage = usage;
-          this.messageManager.setMessages(messages);
-        }
+          // End LLM span with usage data
+          endLLMRequestSpan({
+            model: model || this.getModelConfig().model || "",
+            success: true,
+            hasToolCall: !!(result.tool_calls && result.tool_calls.length > 0),
+          });
 
-        // Notify Agent to add to usage tracking
-        if (this.callbacks?.onUsageAdded) {
-          this.callbacks.onUsageAdded(usage);
-        }
-      }
+          const createdByStreaming = assistantMessageCreated;
 
-      // Collect tool calls for processing
-      const toolCalls: ChatCompletionMessageFunctionToolCall[] = [];
-      if (result.tool_calls) {
-        for (const toolCall of result.tool_calls) {
-          if (toolCall.type === "function") {
-            toolCalls.push(toolCall);
+          // For non-streaming mode, create assistant message after callAgent returns
+          // Also create if streaming mode but no streaming callbacks were called (e.g., when content comes directly in result)
+          if (
+            !this.stream ||
+            (!assistantMessageCreated &&
+              (result.content || result.tool_calls || result.reasoning_content))
+          ) {
+            this.messageManager.addAssistantMessage();
+            assistantMessageCreated = true;
           }
-        }
-      }
 
-      if (toolCalls.length > 0) {
-        // Partition tool calls into batches: consecutive concurrency-safe
-        // tools run in parallel, non-safe tools (Edit, Write, MCP) run one
-        // at a time to prevent read-modify-write races on the same file.
-        const batches: {
-          calls: ChatCompletionMessageFunctionToolCall[];
-          safe: boolean;
-        }[] = [];
-        for (const call of toolCalls) {
-          const toolName = call.function?.name || "";
-          const safe = this.toolManager.isConcurrencySafe(toolName);
-          const lastBatch = batches[batches.length - 1];
-          if (lastBatch && lastBatch.safe && safe) {
-            lastBatch.calls.push(call);
-          } else {
-            batches.push({ calls: [call], safe });
+          // Log finish reason and response headers if available
+          if (result.finish_reason) {
+            // Log warning headers when finish reason is length
+            if (result.finish_reason === "length") {
+              logger?.warn(
+                "AI response truncated due to length limit. Response headers:",
+                result.response_headers,
+              );
+            }
           }
-        }
 
-        // Execute batches sequentially; within a safe batch, tools run in parallel
-        for (const batch of batches) {
           if (
-            abortController.signal.aborted ||
-            toolAbortController.signal.aborted
+            result.additionalFields &&
+            Object.keys(result.additionalFields).length > 0
           ) {
-            break;
-          }
-          if (batch.calls.length === 1) {
-            await this.executeToolCall(
-              batch.calls[0],
-              abortController,
-              toolAbortController,
-              result.finish_reason,
+            this.messageManager.mergeAssistantAdditionalFields(
+              result.additionalFields,
             );
-          } else {
-            await Promise.all(
-              batch.calls.map((call) =>
-                this.executeToolCall(
-                  call,
-                  abortController,
-                  toolAbortController,
-                  result.finish_reason,
-                ),
-              ),
+          }
+
+          // Handle result reasoning content from non-streaming mode
+          if (result.reasoning_content && !createdByStreaming) {
+            this.messageManager.updateCurrentMessageReasoning(
+              result.reasoning_content,
             );
           }
-        }
-      }
 
-      // Handle token statistics and message compaction
-      await this.handleTokenUsageAndCompaction(result.usage, abortController);
+          // Handle result content from non-streaming mode
+          if (result.content && !createdByStreaming) {
+            this.messageManager.updateCurrentMessageContent(result.content);
+          }
 
-      // Finalize text/reasoning blocks for the final response (no tools)
-      this.messageManager.finalizeStreamingBlocks();
+          // Handle usage tracking for agent operations
+          let usage: Usage | undefined;
+          if (result.usage) {
+            usage = {
+              prompt_tokens: result.usage.prompt_tokens,
+              completion_tokens: result.usage.completion_tokens,
+              total_tokens: result.usage.total_tokens,
+              model: model || this.getModelConfig().model,
+              operation_type: "agent",
+              // Preserve cache fields if present
+              ...(result.usage.cache_read_input_tokens !== undefined && {
+                cache_read_input_tokens: result.usage.cache_read_input_tokens,
+              }),
+              ...(result.usage.cache_creation_input_tokens !== undefined && {
+                cache_creation_input_tokens:
+                  result.usage.cache_creation_input_tokens,
+              }),
+              ...(result.usage.cache_creation && {
+                cache_creation: result.usage.cache_creation,
+              }),
+            };
+          }
 
-      // Check if there are tool operations or response was truncated, if so automatically initiate next AI service call
-      if (toolCalls.length > 0 || result.finish_reason === "length") {
-        // Check maxTurns limit before recursing
-        if (this.maxTurns && recursionDepth + 1 >= this.maxTurns) {
-          logger?.debug(
-            `Max turns (${this.maxTurns}) reached, stopping recursion.`,
-          );
-        } else {
-          // Record committed snapshots to message history
-          if (this.reversionManager) {
-            const snapshots =
-              this.reversionManager.getAndClearCommittedSnapshots();
-            if (snapshots.length > 0) {
-              this.messageManager.addFileHistoryBlock(snapshots);
+          // Set usage on the assistant message if available
+          if (usage) {
+            const messages = this.messageManager.getMessages();
+            const lastMessage = messages[messages.length - 1];
+            if (lastMessage && lastMessage.role === "assistant") {
+              lastMessage.usage = usage;
+              this.messageManager.setMessages(messages);
+            }
+
+            // Notify Agent to add to usage tracking
+            if (this.callbacks?.onUsageAdded) {
+              this.callbacks.onUsageAdded(usage);
             }
           }
 
-          // Check interruption status
-          const isCurrentlyAborted =
-            abortController.signal.aborted ||
-            toolAbortController.signal.aborted;
+          // Collect tool calls for processing
+          const toolCalls: ChatCompletionMessageFunctionToolCall[] = [];
+          if (result.tool_calls) {
+            for (const toolCall of result.tool_calls) {
+              if (toolCall.type === "function") {
+                toolCalls.push(toolCall);
+              }
+            }
+          }
 
-          // Check if all tools were manually backgrounded
-          const lastMessage =
-            this.messageManager.getMessages()[
-              this.messageManager.getMessages().length - 1
-            ];
-          const toolBlocks =
-            lastMessage?.blocks.filter(
-              (block): block is import("../types/messaging.js").ToolBlock =>
-                block.type === "tool",
-            ) || [];
-          const hasBackgrounded =
-            toolBlocks.length > 0 &&
-            toolBlocks.some((block) => block.isManuallyBackgrounded);
-
-          if (hasBackgrounded) {
-            logger?.info(
-              "Some tools were manually backgrounded, stopping recursion.",
-            );
-          } else if (!isCurrentlyAborted) {
-            // If response was truncated, add a hidden continuation message
-            if (result.finish_reason === "length") {
-              this.messageManager.addUserMessage({
-                content:
-                  "Output token limit hit. Resume directly — no apology, no recap of what you were doing. Pick up mid-thought if that is where the cut happened. Break remaining work into smaller pieces.",
-                isMeta: true,
-              });
+          if (toolCalls.length > 0) {
+            // Partition tool calls into batches: consecutive concurrency-safe
+            // tools run in parallel, non-safe tools (Edit, Write, MCP) run one
+            // at a time to prevent read-modify-write races on the same file.
+            const batches: {
+              calls: ChatCompletionMessageFunctionToolCall[];
+              safe: boolean;
+            }[] = [];
+            for (const call of toolCalls) {
+              const toolName = call.function?.name || "";
+              const safe = this.toolManager.isConcurrencySafe(toolName);
+              const lastBatch = batches[batches.length - 1];
+              if (lastBatch && lastBatch.safe && safe) {
+                lastBatch.calls.push(call);
+              } else {
+                batches.push({ calls: [call], safe });
+              }
             }
 
-            // Duplicate Tool Call Detection
-            if (toolCalls.length > 0) {
-              const messages = this.messageManager.getMessages();
-              // Find the most recent assistant message BEFORE the current one that has tool blocks
-              // The current assistant message is messages[messages.length - 1]
-              let previousAssistantWithTools: Message | undefined;
-              for (let i = messages.length - 2; i >= 0; i--) {
-                const msg = messages[i];
-                if (
-                  msg.role === "assistant" &&
-                  msg.blocks.some((b) => b.type === "tool")
-                ) {
-                  previousAssistantWithTools = msg;
-                  break;
+            // Execute batches sequentially; within a safe batch, tools run in parallel
+            for (const batch of batches) {
+              if (
+                abortController.signal.aborted ||
+                toolAbortController.signal.aborted
+              ) {
+                break;
+              }
+              if (batch.calls.length === 1) {
+                await this.executeToolCall(
+                  batch.calls[0],
+                  abortController,
+                  toolAbortController,
+                  result.finish_reason,
+                );
+              } else {
+                await Promise.all(
+                  batch.calls.map((call) =>
+                    this.executeToolCall(
+                      call,
+                      abortController,
+                      toolAbortController,
+                      result.finish_reason,
+                    ),
+                  ),
+                );
+              }
+            }
+          }
+
+          // Handle token statistics and message compaction
+          await this.handleTokenUsageAndCompaction(
+            result.usage,
+            abortController,
+          );
+
+          // Finalize text/reasoning blocks for the final response (no tools)
+          this.messageManager.finalizeStreamingBlocks();
+
+          // Check if there are tool operations or response was truncated, if so automatically initiate next AI service call
+          if (toolCalls.length > 0 || result.finish_reason === "length") {
+            // Check maxTurns limit before continuing
+            if (this.maxTurns && turnDepth + 1 >= this.maxTurns) {
+              logger?.debug(`Max turns (${this.maxTurns}) reached, stopping.`);
+            } else {
+              // Record committed snapshots to message history
+              if (this.reversionManager) {
+                const snapshots =
+                  this.reversionManager.getAndClearCommittedSnapshots();
+                if (snapshots.length > 0) {
+                  this.messageManager.addFileHistoryBlock(snapshots);
                 }
               }
 
-              if (previousAssistantWithTools) {
-                const previousToolBlocks =
-                  previousAssistantWithTools.blocks.filter(
-                    (b): b is import("../types/messaging.js").ToolBlock =>
-                      b.type === "tool",
-                  );
-
-                for (const currentToolCall of toolCalls) {
-                  const currentName = currentToolCall.function?.name;
-                  const currentArgs = currentToolCall.function?.arguments;
-
-                  const isDuplicate = previousToolBlocks.some(
-                    (prevBlock) =>
-                      prevBlock.name === currentName &&
-                      prevBlock.parameters === currentArgs,
-                  );
-
-                  if (isDuplicate && currentName) {
-                    const toolId = currentToolCall.id;
-                    const lastMessage = messages[messages.length - 1];
-                    const toolBlock = lastMessage.blocks.find(
-                      (b): b is import("../types/messaging.js").ToolBlock =>
-                        b.type === "tool" && b.id === toolId,
-                    );
-                    if (toolBlock) {
-                      const warning = `\n\nNote: You just called this tool with the same arguments in the previous turn. Please ensure you are not in a loop and consider if you need to change your approach.`;
-                      this.messageManager.updateToolBlock({
-                        id: toolId,
-                        result: (toolBlock.result || "") + warning,
-                        stage: "end",
-                      });
+              // Check interruption status
+              const isCurrentlyAborted =
+                abortController.signal.aborted ||
+                toolAbortController.signal.aborted;
+
+              // Check if all tools were manually backgrounded
+              const lastMessage =
+                this.messageManager.getMessages()[
+                  this.messageManager.getMessages().length - 1
+                ];
+              const toolBlocks =
+                lastMessage?.blocks.filter(
+                  (block): block is import("../types/messaging.js").ToolBlock =>
+                    block.type === "tool",
+                ) || [];
+              const hasBackgrounded =
+                toolBlocks.length > 0 &&
+                toolBlocks.some((block) => block.isManuallyBackgrounded);
+
+              if (hasBackgrounded) {
+                logger?.info(
+                  "Some tools were manually backgrounded, stopping.",
+                );
+              } else if (!isCurrentlyAborted) {
+                // If response was truncated, add a hidden continuation message
+                if (result.finish_reason === "length") {
+                  this.messageManager.addUserMessage({
+                    content:
+                      "Output token limit hit. Resume directly — no apology, no recap of what you were doing. Pick up mid-thought if that is where the cut happened. Break remaining work into smaller pieces.",
+                    isMeta: true,
+                  });
+                }
+
+                // Duplicate Tool Call Detection
+                if (toolCalls.length > 0) {
+                  const messages = this.messageManager.getMessages();
+                  // Find the most recent assistant message BEFORE the current one that has tool blocks
+                  // The current assistant message is messages[messages.length - 1]
+                  let previousAssistantWithTools: Message | undefined;
+                  for (let i = messages.length - 2; i >= 0; i--) {
+                    const msg = messages[i];
+                    if (
+                      msg.role === "assistant" &&
+                      msg.blocks.some((b) => b.type === "tool")
+                    ) {
+                      previousAssistantWithTools = msg;
+                      break;
+                    }
+                  }
+
+                  if (previousAssistantWithTools) {
+                    const previousToolBlocks =
+                      previousAssistantWithTools.blocks.filter(
+                        (b): b is import("../types/messaging.js").ToolBlock =>
+                          b.type === "tool",
+                      );
+
+                    for (const currentToolCall of toolCalls) {
+                      const currentName = currentToolCall.function?.name;
+                      const currentArgs = currentToolCall.function?.arguments;
+
+                      const isDuplicate = previousToolBlocks.some(
+                        (prevBlock) =>
+                          prevBlock.name === currentName &&
+                          prevBlock.parameters === currentArgs,
+                      );
+
+                      if (isDuplicate && currentName) {
+                        const toolId = currentToolCall.id;
+                        const lastMessage = messages[messages.length - 1];
+                        const toolBlock = lastMessage.blocks.find(
+                          (b): b is import("../types/messaging.js").ToolBlock =>
+                            b.type === "tool" && b.id === toolId,
+                        );
+                        if (toolBlock) {
+                          const warning = `\n\nNote: You just called this tool with the same arguments in the previous turn. Please ensure you are not in a loop and consider if you need to change your approach.`;
+                          this.messageManager.updateToolBlock({
+                            id: toolId,
+                            result: (toolBlock.result || "") + warning,
+                            stage: "end",
+                          });
+                        }
+                      }
                     }
                   }
                 }
+
+                // Yield to the event loop so macrotasks (abort timers,
+                // signals) can be processed between turns. Without this,
+                // mocked async operations (microtasks) would starve the
+                // event loop and abort timers would never fire.
+                await new Promise((resolve) => setImmediate(resolve));
+
+                // Re-check abort status after yielding — the signal may
+                // have fired during the setImmediate gap.
+                if (
+                  abortController.signal.aborted ||
+                  toolAbortController.signal.aborted
+                ) {
+                  break inner;
+                }
+
+                turnDepth++;
+                continue inner;
               }
             }
-
-            // Recursively call AI service, increment recursion depth, and pass same configuration
-            await this.sendAIMessage({
-              recursionDepth: recursionDepth + 1,
-              model,
-              allowedRules,
-              maxTokens,
-            });
           }
+
+          // No tool calls (or stop conditions) → inner loop done
+          break inner;
+        } catch (error) {
+          // End LLM span with error
+          endLLMRequestSpan({
+            model: model || this.getModelConfig().model || "",
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+          });
+
+          // Log error event
+          logOTelEvent("error", {
+            error_type:
+              error instanceof Error ? error.constructor.name : "Unknown",
+            message: error instanceof Error ? error.message : String(error),
+          }).catch(() => {}); // Non-blocking
+
+          this.messageManager.addErrorBlock(
+            error instanceof Error ? error.message : "Unknown error occurred",
+          );
+
+          // Exit inner loop on error
+          break inner;
         }
       }
-    } catch (error) {
-      // End LLM span with error
-      endLLMRequestSpan({
-        model: model || this.getModelConfig().model || "",
-        success: false,
-        error: error instanceof Error ? error.message : String(error),
-      });
-
-      // Log error event
-      logOTelEvent("error", {
-        error_type: error instanceof Error ? error.constructor.name : "Unknown",
-        message: error instanceof Error ? error.message : String(error),
-      }).catch(() => {}); // Non-blocking
 
-      this.messageManager.addErrorBlock(
-        error instanceof Error ? error.message : "Unknown error occurred",
-      );
-    } finally {
+      // Finally-equivalent (runs once per outer iteration):
       // Only execute cleanup and hooks for the initial call
-      if (recursionDepth === 0) {
+      if (turnOffset === 0) {
         // OpenTelemetry: end interaction span
         endInteractionSpan();
 
-        // Save session in each recursion to ensure message persistence
+        // Save session in each iteration to ensure message persistence
         await this.messageManager.saveSession();
         // Set loading to false first
         this.setIsLoading(false);
@@ -1240,13 +1289,9 @@ export class AIManager {
               });
             }
           }
-          // Recursively process the notifications
-          await this.sendAIMessage({
-            recursionDepth: 0,
-            model,
-            allowedRules,
-            maxTokens,
-          });
+          // Restart outer loop to process the notifications
+          shouldRestart = true;
+          turnOffset = 0;
         } else {
           // Clear temporary rules
           this.permissionManager?.clearTemporaryRules();
@@ -1317,12 +1362,9 @@ export class AIManager {
                   // Keep loading state active to prevent UI flicker
                   this.setIsLoading(true);
                   goalContinuing = true;
-                  await this.sendAIMessage({
-                    recursionDepth: 0,
-                    model,
-                    allowedRules,
-                    maxTokens,
-                  });
+                  // Restart outer loop to continue goal pursuit
+                  shouldRestart = true;
+                  turnOffset = 0;
                 }
               }
             }
@@ -1341,18 +1383,15 @@ export class AIManager {
                 );
 
                 // Restart the conversation to let AI fix the issues
-                // Use recursionDepth = 0 to set loading false again for continuation
-                await this.sendAIMessage({
-                  recursionDepth: 0,
-                  model,
-                  allowedRules,
-                  maxTokens,
-                });
+                shouldRestart = true;
+                turnOffset = 0;
               }
             }
           }
         }
       }
+
+      if (!shouldRestart) break outer;
     }
   }