fix: parallel tool calls by deferring citation instructions (#397)

* Fix parallel tool calls by deferring citation instructions

For parallel tool calls (e.g., multiple web searches), all providers
(OpenAI, Anthropic, Gemini) require tool results to be consecutive
after the assistant message with tool_calls.

Previously, citation instructions were added immediately after each
tool result, which broke the consecutive sequence:
- tool result 1
- system message (citation)  <-- breaks sequence
- tool result 2

Now, citation instructions are collected during tool execution and
added AFTER all tool results:
- tool result 1
- tool result 2
- system message (citation)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* combine all instructions into one system prompt message

* add draining/system prompt updates for mulitple types of tool call with multi-turn

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: henrypark133

crates/services/src/responses/service.rs

@@ -1210,26 +1210,47 @@ impl ResponseServiceImpl {
 
             tracing::debug!("Executing {} tool calls", stream_result.tool_calls.len());
 
-            // Execute each tool call
+            // Execute each tool call, collecting any deferred instructions
+            let mut deferred_instructions: Vec<String> = Vec::new();
             for tool_call in stream_result.tool_calls {
                 match Self::execute_and_emit_tool_call(
                     ctx,
                     emitter,
                     &tool_call,
                     messages,
                     process_context,
+                    &mut deferred_instructions,
                 )
                 .await?
                 {
                     tools::ToolExecutionResult::Success => {
                         // Continue processing tool calls
                     }
                     tools::ToolExecutionResult::ApprovalRequired => {
-                        // MCP tool requires approval - pause the agent loop
+                        // MCP tool requires approval - flush any deferred instructions before pausing
+                        if !deferred_instructions.is_empty() {
+                            messages.push(CompletionMessage {
+                                role: "system".to_string(),
+                                content: std::mem::take(&mut deferred_instructions).join("\n\n"),
+                                tool_call_id: None,
+                                tool_calls: None,
+                            });
+                        }
                         return Ok(AgentLoopResult::ApprovalRequired);
                     }
                 }
             }
+
+            // Add deferred instructions AFTER all tool results (combined into one system message)
+            // This ensures tool results are consecutive (required by OpenAI/Anthropic/Gemini)
+            if !deferred_instructions.is_empty() {
+                messages.push(CompletionMessage {
+                    role: "system".to_string(),
+                    content: deferred_instructions.join("\n\n"),
+                    tool_call_id: None,
+                    tool_calls: None,
+                });
+            }
         }
 
         Ok(AgentLoopResult::Completed)
@@ -1239,12 +1260,17 @@ impl ResponseServiceImpl {
     ///
     /// Returns `Ok(ToolExecutionResult::Success)` if the tool executed normally,
     /// or `Ok(ToolExecutionResult::ApprovalRequired)` if the tool requires user approval.
+    ///
+    /// Any instructions (e.g., citation instructions from web search) are collected into
+    /// `deferred_instructions` to be added after all tool results. This ensures tool results
+    /// are consecutive (required by OpenAI/Anthropic/Gemini for parallel tool calls).
     async fn execute_and_emit_tool_call(
         ctx: &mut crate::responses::service_helpers::ResponseStreamContext,
         emitter: &mut crate::responses::service_helpers::EventEmitter,
         tool_call: &crate::responses::service_helpers::ToolCallInfo,
         messages: &mut Vec<crate::completions::ports::CompletionMessage>,
         process_context: &mut ProcessStreamContext,
+        deferred_instructions: &mut Vec<String>,
     ) -> Result<tools::ToolExecutionResult, errors::ResponseError> {
         use crate::completions::ports::CompletionMessage;
 
@@ -1388,14 +1414,10 @@ impl ResponseServiceImpl {
             tool_calls: None,
         });
 
-        // Add citation instruction if provided (first web search)
+        // Defer citation instruction to be added after all tool results
+        // This ensures tool results are consecutive (required by OpenAI/Anthropic/Gemini)
         if let Some(instruction) = instruction {
-            messages.push(CompletionMessage {
-                role: "system".to_string(),
-                content: instruction,
-                tool_call_id: None,
-                tool_calls: None,
-            });
+            deferred_instructions.push(instruction);
         }
 
         Ok(tools::ToolExecutionResult::Success)