[ENHANCEMENT] Support Gemini 3 Built-in and Custom Tool Combinations (Tool Context Circulation)

[KuroZantetsuken]

Problem (one or two sentences)

Users using Gemini 3 models in Roo Code cannot combine Gemini's powerful server-side built-in tools (like Google Search, URL Context, and Code Execution) with Roo Code's client-side custom tools (like reading/writing local files or terminal commands) in a single generation.

Context (who is affected and when)

This affects users who configure Roo Code to use Gemini 3 models. It happens when attempting complex, agentic workflows that require both real-time external data grounding (e.g., searching the web for the latest API docs) and local codebase operations (e.g., implementing that API in the project).

Desired behavior (conceptual, not technical)

Roo Code should enable "tool context circulation" when using Gemini 3 models. This means allowing the Gemini model to perform built-in server-side actions (like running a Google Search) and then seamlessly passing that context into Roo Code's local custom tools so the model can complete the user's task in one continuous workflow.

Constraints / preferences (optional)

• This must only be enabled for Gemini 3 models, as it is a preview feature specific to that generation.
• Must correctly preserve and return the API's required hidden context data (thought_signatures, id, tool_type) in the chat history to prevent the model from erroring out.
• Keep token limits in mind, as intermediate tool context will count towards the prompt token count (excluding Google Search queries).

Request checklist

• I've searched existing Issues and Discussions for duplicates
• This describes a specific problem with clear context and impact

Roo Code Task Links (optional)

No response

Acceptance criteria (optional)

Given a user has configured Roo Code to use a Gemini 3 model
When the user asks a prompt requiring both a built-in Gemini tool (e.g., web search) and a Roo Code custom tool (e.g., editing a file)
Then Roo Code sets include_server_side_tool_invocations to true in the API configuration
And the extension successfully circulates the toolCall and toolResponse parts alongside Roo Code's functionCall and functionResponse parts
And all parts containing thoughtSignature, id, and toolType are accurately preserved and passed back to the model in subsequent conversational turns
But this change should not break or interfere with the tool-calling logic of other providers (like OpenAI, Claude, or older Gemini models).

Proposed approach (optional)

1. Update the Gemini API provider configuration in Roo Code to include toolConfig: { includeServerSideToolInvocations: true } when a Gemini 3 model is selected.
2. Update the Gemini message builder/history mapper in Roo Code to capture toolCall, toolResponse, executableCode, and codeExecutionResult parts.
3. Ensure that when Roo Code constructs the message history for subsequent turns, it passes back the exact thoughtSignature and id fields embedded in the API's previous responses, which are critical for the Gemini 3 context circulation to function.

Trade-offs / risks (optional)

• Token Consumption: Adding toolCall and toolResponse history to the prompt increases prompt_token_count on subsequent turns, potentially driving up costs or hitting context limits faster.
• Provider Complexity: Roo Code's message history parsing will need specialized handling just for Gemini 3's unique thoughtSignature and combined tool architecture, adding slight complexity to the tool-calling abstraction layer.

[roomote-v0]

I've analyzed this issue and here's my proposed implementation plan:

Analysis

The current Gemini handler (src/api/providers/gemini.ts) explicitly notes at line 132 that "Google built-in tools (Grounding, URL Context) are mutually exclusive with function declarations in the Gemini API." Gemini 3 introduces a new capability via includeServerSideToolInvocations that lifts this restriction, allowing the model to use both server-side built-in tools (Google Search, URL Context, Code Execution) and client-side function declarations in a single generation.

There is already a gemini-3.1-pro-preview-customtools model variant in packages/types/src/providers/gemini.ts, which appears to be the Gemini API model name that supports this combined tool mode. The streaming handler currently only processes functionCall, thought, and text parts, and does not handle the server-side tool parts (toolCall, toolResponse, executableCode, codeExecutionResult) that the API returns when built-in tools are invoked server-side.

Proposed Changes

1. Enable includeServerSideToolInvocations in tool config for Gemini 3+ models (src/api/providers/gemini.ts)

• Add a helper to detect Gemini 3+ models (model IDs containing gemini-3 or the -customtools suffix).
• When a Gemini 3+ model is detected, add includeServerSideToolInvocations: true to the toolConfig in GenerateContentConfig.
• This allows the model to invoke its built-in tools alongside Roo Code's function declarations.

2. Handle server-side tool parts in the streaming response (src/api/providers/gemini.ts)

• Extend the streaming loop (lines 233-287) to recognize and handle new part types from the Gemini API response:
  • toolCall (server-side tool invocation, e.g., Google Search)
  • toolResponse (server-side tool result)
  • executableCode (server-side code execution input)
  • codeExecutionResult (server-side code execution output)
• These server-side tool interactions happen transparently on Google's servers. Roo Code does not need to execute them. Instead, we should:
  • Yield text/grounding results from toolResponse parts to the user as informational context.
  • Accumulate these parts so they can be preserved in the conversation history for round-tripping.

3. Preserve server-side tool context in conversation history (src/api/transform/gemini-format.ts and src/core/task/Task.ts)

• When storing assistant messages in addToApiConversationHistory, include server-side tool parts (with their thoughtSignature, id, and toolType metadata) as additional content blocks.
• In gemini-format.ts, update convertAnthropicContentToGemini to recognize and pass through these server-side tool content blocks when converting history back to Gemini format, preserving the required metadata fields.
• This ensures the model receives the full context of previous server-side tool invocations on subsequent turns.

4. Scope the change to Gemini 3 models only

• The includeServerSideToolInvocations flag and new part handling will be gated behind a Gemini 3+ model check.
• Older Gemini models (2.5, 2.0, 1.5) and all other providers remain completely unaffected.
• The existing gemini-3.1-pro-preview-customtools model variant should naturally benefit from this since it's a Gemini 3 model.

5. Tests

• Add unit tests in src/api/providers/__tests__/gemini.spec.ts to verify includeServerSideToolInvocations is set for Gemini 3 models and not for older models.
• Add tests in src/api/transform/__tests__/gemini-format.spec.ts for round-tripping server-side tool parts through the message converter.
• Add integration-style tests for the streaming handler to verify server-side tool parts are processed correctly.

Open Questions

1. SDK support: The @google/genai SDK is at v1.29.1. I need to verify that includeServerSideToolInvocations is available in the ToolConfig type. If not, we may need to bump the SDK version or cast the config.
2. Surface server-side tool output: Should the output from server-side tools (e.g., Google Search results, code execution output) be surfaced to the user in the chat UI as distinct message types, or just included as inline text context? The simplest approach is to yield them as text chunks, but a richer approach could use a new stream event type.
3. The -customtools model variant: Is gemini-3.1-pro-preview-customtools specifically the model that enables this feature, or should all Gemini 3 models support it? The current approach gates on all Gemini 3+ model IDs.

This approach addresses the core issue while keeping changes isolated to the Gemini provider path, with no impact on other providers.

Please mention @roomote in a comment saying that you approve this plan, and I'll proceed with the implementation.

[KuroZantetsuken]

gemini-3.1-pro-preview-customtools is only for prioritizing custom tool calls over basic bash commands, right? This new combo feature is on any Gemini 3 model I'm pretty sure.