massgen 0.1.0a2__py3-none-any.whl → 0.1.1__py3-none-any.whl

massgen/backend/gemini.py

@@ -19,15 +19,13 @@ TECHNICAL SOLUTION:
 - Maintains compatibility with existing MassGen workflow
 """
 
-import asyncio
-import enum
-import hashlib
 import json
 import os
-import re
 import time
-from typing import Any, AsyncGenerator, Awaitable, Callable, Dict, List, Optional
+from typing import Any, AsyncGenerator, Dict, List, Optional
 
+from ..api_params_handler._gemini_api_params_handler import GeminiAPIParamsHandler
+from ..formatter._gemini_formatter import GeminiFormatter
 from ..logger_config import (
     log_backend_activity,
     log_backend_agent_message,
@@ -35,7 +33,11 @@ from ..logger_config import (
     log_tool_call,
     logger,
 )
-from .base import FilesystemSupport, LLMBackend, StreamChunk
+from .base import FilesystemSupport, StreamChunk
+from .base_with_custom_tool_and_mcp import CustomToolAndMCPBackend
+from .gemini_mcp_manager import GeminiMCPManager
+from .gemini_trackers import MCPCallTracker, MCPResponseExtractor, MCPResponseTracker
+from .gemini_utils import CoordinationResponse
 
 try:
     from pydantic import BaseModel, Field
@@ -45,10 +47,12 @@ except ImportError:
 
 # MCP integration imports
 try:
-    from ..mcp_tools import MCPClient, MCPConnectionError, MCPError
-    from ..mcp_tools.config_validator import MCPConfigValidator
-    from ..mcp_tools.exceptions import (
+    from ..mcp_tools import (
+        MCPClient,
         MCPConfigurationError,
+        MCPConfigValidator,
+        MCPConnectionError,
+        MCPError,
         MCPServerError,
         MCPTimeoutError,
         MCPValidationError,
@@ -82,1106 +86,83 @@ except ImportError:
     MCPConfigHelper = None  # type: ignore[assignment]
 
 
-class ActionType(enum.Enum):
-    """Action types for structured output."""
-
-    VOTE = "vote"
-    NEW_ANSWER = "new_answer"
-
-
-class VoteAction(BaseModel):
-    """Structured output for voting action."""
-
-    action: ActionType = Field(default=ActionType.VOTE, description="Action type")
-    agent_id: str = Field(description="Anonymous agent ID to vote for (e.g., 'agent1', 'agent2')")
-    reason: str = Field(description="Brief reason why this agent has the best answer")
-
-
-class NewAnswerAction(BaseModel):
-    """Structured output for new answer action."""
-
-    action: ActionType = Field(default=ActionType.NEW_ANSWER, description="Action type")
-    content: str = Field(description="Your improved answer. If any builtin tools like search or code execution were used, include how they are used here.")
-
-
-class CoordinationResponse(BaseModel):
-    """Structured response for coordination actions."""
-
-    action_type: ActionType = Field(description="Type of action to take")
-    vote_data: Optional[VoteAction] = Field(default=None, description="Vote data if action is vote")
-    answer_data: Optional[NewAnswerAction] = Field(default=None, description="Answer data if action is new_answer")
-
-
-class MCPResponseTracker:
-    """
-    Tracks MCP tool responses across streaming chunks to handle deduplication.
-
-    Similar to MCPCallTracker but for tracking tool responses to avoid duplicate output.
-    """
-
-    def __init__(self):
-        """Initialize the tracker with empty storage."""
-        self.processed_responses = set()  # Store hashes of processed responses
-        self.response_history = []  # Store all unique responses with timestamps
-
-    def get_response_hash(self, tool_name: str, tool_response: Any) -> str:
-        """
-        Generate a unique hash for a tool response based on name and response content.
-
-        Args:
-            tool_name: Name of the tool that responded
-            tool_response: Response from the tool
-
-        Returns:
-            MD5 hash string identifying this specific response
-        """
-        # Create a deterministic string representation
-        content = f"{tool_name}:{str(tool_response)}"
-        return hashlib.md5(content.encode()).hexdigest()
-
-    def is_new_response(self, tool_name: str, tool_response: Any) -> bool:
-        """
-        Check if this is a new tool response we haven't seen before.
-
-        Args:
-            tool_name: Name of the tool that responded
-            tool_response: Response from the tool
-
-        Returns:
-            True if this is a new response, False if already processed
-        """
-        response_hash = self.get_response_hash(tool_name, tool_response)
-        return response_hash not in self.processed_responses
-
-    def add_response(self, tool_name: str, tool_response: Any) -> Dict[str, Any]:
-        """
-        Add a new response to the tracker.
-
-        Args:
-            tool_name: Name of the tool that responded
-            tool_response: Response from the tool
-
-        Returns:
-            Dictionary containing response details and timestamp
-        """
-        response_hash = self.get_response_hash(tool_name, tool_response)
-        self.processed_responses.add(response_hash)
-
-        record = {
-            "tool_name": tool_name,
-            "response": tool_response,
-            "hash": response_hash,
-            "timestamp": time.time(),
-        }
-        self.response_history.append(record)
-        return record
-
-
-class MCPCallTracker:
-    """
-    Tracks MCP tool calls across streaming chunks to handle deduplication.
-
-    Uses hashing to identify unique tool calls and timestamps to track when they occurred.
-    This ensures we don't double-count the same tool call appearing in multiple chunks.
+def format_tool_response_as_json(response_text: str) -> str:
     """
+    Format tool response text as pretty-printed JSON if possible.
 
-    def __init__(self):
-        """Initialize the tracker with empty storage."""
-        self.processed_calls = set()  # Store hashes of processed calls
-        self.call_history = []  # Store all unique calls with timestamps
-        self.last_chunk_calls = []  # Track calls from the last chunk for deduplication
-        self.dedup_window = 0.5  # Time window in seconds for deduplication
-
-    def get_call_hash(self, tool_name: str, tool_args: Dict[str, Any]) -> str:
-        """
-        Generate a unique hash for a tool call based on name and arguments.
-
-        Args:
-            tool_name: Name of the tool being called
-            tool_args: Arguments passed to the tool
-
-        Returns:
-            MD5 hash string identifying this specific call
-        """
-        # Create a deterministic string representation
-        content = f"{tool_name}:{json.dumps(tool_args, sort_keys=True)}"
-        return hashlib.md5(content.encode()).hexdigest()
-
-    def is_new_call(self, tool_name: str, tool_args: Dict[str, Any]) -> bool:
-        """
-        Check if this is a new tool call we haven't seen before.
-
-        Uses a time-window based approach: identical calls within the dedup_window
-        are considered duplicates (likely from streaming chunks), while those outside
-        the window are considered new calls (likely intentional repeated calls).
-
-        Args:
-            tool_name: Name of the tool being called
-            tool_args: Arguments passed to the tool
-
-        Returns:
-            True if this is a new call, False if we've seen it before
-        """
-        call_hash = self.get_call_hash(tool_name, tool_args)
-        current_time = time.time()
-
-        # Check if this call exists in recent history within the dedup window
-        for call in self.call_history[-10:]:  # Check last 10 calls for efficiency
-            if call.get("hash") == call_hash:
-                time_diff = current_time - call.get("timestamp", 0)
-                if time_diff < self.dedup_window:
-                    # This is likely a duplicate from streaming chunks
-                    return False
-                # If outside the window, treat as a new intentional call
-
-        # Mark as processed
-        self.processed_calls.add(call_hash)
-        return True
-
-    def add_call(self, tool_name: str, tool_args: Dict[str, Any]) -> Dict[str, Any]:
-        """
-        Add a new tool call to the history.
-
-        Args:
-            tool_name: Name of the tool being called
-            tool_args: Arguments passed to the tool
-
-        Returns:
-            Dictionary containing the call details with timestamp and hash
-        """
-        call_record = {
-            "name": tool_name,
-            "arguments": tool_args,
-            "timestamp": time.time(),
-            "hash": self.get_call_hash(tool_name, tool_args),
-            "sequence": len(self.call_history),  # Add sequence number for ordering
-        }
-        self.call_history.append(call_record)
-
-        # Clean up old history to prevent memory growth
-        if len(self.call_history) > 100:
-            self.call_history = self.call_history[-50:]
-
-        return call_record
-
-    def get_summary(self) -> str:
-        """
-        Get a summary of all tracked tool calls.
-
-        Returns:
-            Human-readable summary of tool usage
-        """
-        if not self.call_history:
-            return "No MCP tools called"
-
-        tool_names = [call["name"] for call in self.call_history]
-        unique_tools = list(dict.fromkeys(tool_names))  # Preserve order
-        return f"Used {len(self.call_history)} MCP tool calls: {', '.join(unique_tools)}"
-
+    Args:
+        response_text: The raw response text from a tool
 
-class MCPResponseExtractor:
+    Returns:
+        Pretty-printed JSON string if response is valid JSON, otherwise original text
     """
-    Extracts MCP tool calls and responses from Gemini SDK stream chunks.
-
-    This class parses the internal SDK chunks to capture:
-    - function_call parts (tool invocations)
-    - function_response parts (tool results)
-    - Paired call-response data for tracking complete tool executions
-    """
-
-    def __init__(self):
-        """Initialize the extractor with empty storage."""
-        self.mcp_calls = []  # All tool calls
-        self.mcp_responses = []  # All tool responses
-        self.call_response_pairs = []  # Matched call-response pairs
-        self._pending_call = None  # Track current call awaiting response
-
-    def extract_function_call(self, function_call) -> Optional[Dict[str, Any]]:
-        """
-        Extract tool call information from SDK function_call object.
-
-        Tries multiple methods to extract data from different SDK versions:
-        1. Direct attributes (name, args)
-        2. Dictionary-like interface (get method)
-        3. __dict__ attributes
-        4. Protobuf _pb attributes
-        """
-        tool_name = None
-        tool_args = None
-
-        # Method 1: Direct attributes
-        tool_name = getattr(function_call, "name", None)
-        tool_args = getattr(function_call, "args", None)
-
-        # Method 2: Dictionary-like object
-        if tool_name is None:
-            try:
-                if hasattr(function_call, "get"):
-                    tool_name = function_call.get("name", None)
-                    tool_args = function_call.get("args", None)
-            except Exception:
-                pass
-
-        # Method 3: __dict__ inspection
-        if tool_name is None:
-            try:
-                if hasattr(function_call, "__dict__"):
-                    fc_dict = function_call.__dict__
-                    tool_name = fc_dict.get("name", None)
-                    tool_args = fc_dict.get("args", None)
-            except Exception:
-                pass
-
-        # Method 4: Protobuf _pb attribute
-        if tool_name is None:
-            try:
-                if hasattr(function_call, "_pb"):
-                    pb = function_call._pb
-                    if hasattr(pb, "name"):
-                        tool_name = pb.name
-                    if hasattr(pb, "args"):
-                        tool_args = pb.args
-            except Exception:
-                pass
-
-        if tool_name:
-            call_data = {
-                "name": tool_name,
-                "arguments": tool_args or {},
-                "timestamp": time.time(),
-                "raw": str(function_call)[:200],  # Truncate for logging
-            }
-            self.mcp_calls.append(call_data)
-            self._pending_call = call_data
-            return call_data
-
-        return None
-
-    def extract_function_response(self, function_response) -> Optional[Dict[str, Any]]:
-        """
-        Extract tool response information from SDK function_response object.
-
-        Uses same extraction methods as function_call for consistency.
-        """
-        tool_name = None
-        tool_response = None
+    try:
+        # Try to parse as JSON
+        parsed = json.loads(response_text)
+        # Return pretty-printed JSON with 2-space indentation
+        return json.dumps(parsed, indent=2, ensure_ascii=False)
+    except (json.JSONDecodeError, TypeError):
+        # If not valid JSON, return original text
+        return response_text
 
-        # Method 1: Direct attributes
-        tool_name = getattr(function_response, "name", None)
-        tool_response = getattr(function_response, "response", None)
 
-        # Method 2: Dictionary-like object
-        if tool_name is None:
-            try:
-                if hasattr(function_response, "get"):
-                    tool_name = function_response.get("name", None)
-                    tool_response = function_response.get("response", None)
-            except Exception:
-                pass
-
-        # Method 3: __dict__ inspection
-        if tool_name is None:
-            try:
-                if hasattr(function_response, "__dict__"):
-                    fr_dict = function_response.__dict__
-                    tool_name = fr_dict.get("name", None)
-                    tool_response = fr_dict.get("response", None)
-            except Exception:
-                pass
-
-        # Method 4: Protobuf _pb attribute
-        if tool_name is None:
-            try:
-                if hasattr(function_response, "_pb"):
-                    pb = function_response._pb
-                    if hasattr(pb, "name"):
-                        tool_name = pb.name
-                    if hasattr(pb, "response"):
-                        tool_response = pb.response
-            except Exception:
-                pass
-
-        if tool_name:
-            response_data = {
-                "name": tool_name,
-                "response": tool_response or {},
-                "timestamp": time.time(),
-                "raw": str(function_response)[:500],  # Truncate for logging
-            }
-            self.mcp_responses.append(response_data)
-
-            # Pair with pending call if names match
-            if self._pending_call and self._pending_call["name"] == tool_name:
-                self.call_response_pairs.append(
-                    {
-                        "call": self._pending_call,
-                        "response": response_data,
-                        "duration": response_data["timestamp"] - self._pending_call["timestamp"],
-                        "paired_at": time.time(),
-                    },
-                )
-                self._pending_call = None
-
-            return response_data
-
-        return None
-
-    def get_summary(self) -> Dict[str, Any]:
-        """
-        Get a summary of all extracted MCP tool interactions.
-        """
-        return {
-            "total_calls": len(self.mcp_calls),
-            "total_responses": len(self.mcp_responses),
-            "paired_interactions": len(self.call_response_pairs),
-            "pending_call": self._pending_call is not None,
-            "tool_names": list(set(call["name"] for call in self.mcp_calls)),
-            "average_duration": (sum(pair["duration"] for pair in self.call_response_pairs) / len(self.call_response_pairs) if self.call_response_pairs else 0),
-        }
+class GeminiBackend(CustomToolAndMCPBackend):
+    """Google Gemini backend using structured output for coordination and MCP tool integration."""
 
-    def clear(self):
-        """Clear all stored data."""
-        self.mcp_calls.clear()
-        self.mcp_responses.clear()
-        self.call_response_pairs.clear()
-        self._pending_call = None
+    def __init__(self, api_key: Optional[str] = None, **kwargs):
+        # Store Gemini-specific API key before calling parent init
+        gemini_api_key = api_key or os.getenv("GOOGLE_API_KEY") or os.getenv("GEMINI_API_KEY")
 
+        # Call parent class __init__ - this initializes custom_tool_manager and MCP-related attributes
+        super().__init__(gemini_api_key, **kwargs)
 
-class GeminiBackend(LLMBackend):
-    """Google Gemini backend using structured output for coordination and MCP tool integration."""
+        # Override API key with Gemini-specific value
+        self.api_key = gemini_api_key
 
-    def __init__(self, api_key: Optional[str] = None, **kwargs):
-        super().__init__(api_key, **kwargs)
-        self.api_key = api_key or os.getenv("GOOGLE_API_KEY") or os.getenv("GEMINI_API_KEY")
+        # Gemini-specific counters for builtin tools
         self.search_count = 0
         self.code_execution_count = 0
 
-        # MCP integration (filesystem MCP server may have been injected by base class)
-        self.mcp_servers = self.config.get("mcp_servers", [])
-        self.allowed_tools = kwargs.pop("allowed_tools", None)
-        self.exclude_tools = kwargs.pop("exclude_tools", None)
-        self._mcp_client: Optional[MCPClient] = None
-        self._mcp_initialized = False
+        # New components for separation of concerns
+        self.formatter = GeminiFormatter()
+        self.api_params_handler = GeminiAPIParamsHandler(self)
 
-        # MCP tool execution monitoring
-        self._mcp_tool_calls_count = 0
-        self._mcp_tool_failures = 0
+        # Gemini-specific MCP monitoring (additional to parent class)
         self._mcp_tool_successes = 0
-
-        # MCP Response Extractor for capturing tool interactions
-        self.mcp_extractor = MCPResponseExtractor()
-
-        # Limit for message history growth within MCP execution loop
-        self._max_mcp_message_history = kwargs.pop("max_mcp_message_history", 200)
         self._mcp_connection_retries = 0
 
-        # Circuit breaker configuration
-        self._circuit_breakers_enabled = kwargs.pop("circuit_breaker_enabled", True)
-        self._mcp_tools_circuit_breaker = None
-
-        # Initialize agent_id for use throughout the class
-        self.agent_id = kwargs.get("agent_id", None)
-
-        # Initialize circuit breaker if enabled
-        if self._circuit_breakers_enabled:
-            # Fail fast if required utilities are missing
-            if MCPCircuitBreakerManager is None:
-                raise RuntimeError("Circuit breakers enabled but MCPCircuitBreakerManager is not available")
-
-            try:
-                from ..mcp_tools.circuit_breaker import MCPCircuitBreaker
+        # MCP Response Extractor for capturing tool interactions (Gemini-specific)
+        self.mcp_extractor = MCPResponseExtractor()
 
-                # Use shared utility to build circuit breaker configuration
-                if MCPConfigHelper is not None:
-                    mcp_tools_config = MCPConfigHelper.build_circuit_breaker_config("mcp_tools", backend_name="gemini")
-                else:
-                    mcp_tools_config = None
-                if mcp_tools_config:
-                    self._mcp_tools_circuit_breaker = MCPCircuitBreaker(mcp_tools_config, backend_name="gemini", agent_id=self.agent_id)
-                    log_backend_activity(
-                        "gemini",
-                        "Circuit breaker initialized for MCP tools",
-                        {"enabled": True},
-                        agent_id=self.agent_id,
-                    )
-                else:
-                    log_backend_activity(
-                        "gemini",
-                        "Circuit breaker config unavailable",
-                        {"fallback": "disabled"},
-                        agent_id=self.agent_id,
-                    )
-                    self._circuit_breakers_enabled = False
-            except ImportError:
-                log_backend_activity(
-                    "gemini",
-                    "Circuit breaker import failed",
-                    {"fallback": "disabled"},
-                    agent_id=self.agent_id,
-                )
-                self._circuit_breakers_enabled = False
+        # Initialize Gemini MCP manager after all attributes are ready
+        self.mcp_manager = GeminiMCPManager(self)
 
     def _setup_permission_hooks(self):
         """Override base class - Gemini uses session-based permissions, not function hooks."""
         logger.debug("[Gemini] Using session-based permissions, skipping function hook setup")
 
-    async def _setup_mcp_with_status_stream(self, agent_id: Optional[str] = None) -> AsyncGenerator[StreamChunk, None]:
-        """Initialize MCP client with status streaming."""
-        status_queue: asyncio.Queue[StreamChunk] = asyncio.Queue()
-
-        async def status_callback(status: str, details: Dict[str, Any]) -> None:
-            """Callback to queue status updates as StreamChunks."""
-            chunk = StreamChunk(
-                type="mcp_status",
-                status=status,
-                content=details.get("message", ""),
-                source="mcp_tools",
-            )
-            await status_queue.put(chunk)
-
-        # Start the actual setup in background
-        setup_task = asyncio.create_task(self._setup_mcp_tools_internal(agent_id, status_callback))
-
-        # Yield status updates while setup is running
-        while not setup_task.done():
-            try:
-                chunk = await asyncio.wait_for(status_queue.get(), timeout=0.1)
-                yield chunk
-            except asyncio.TimeoutError:
-                continue
-
-        # Wait for setup to complete and handle any final errors
-        try:
-            await setup_task
-        except Exception as e:
-            yield StreamChunk(
-                type="mcp_status",
-                status="error",
-                content=f"MCP setup failed: {e}",
-                source="mcp_tools",
-            )
-
-    async def _setup_mcp_tools(self, agent_id: Optional[str] = None) -> None:
-        """Initialize MCP client (sessions only) - backward compatibility."""
-        if not self.mcp_servers or self._mcp_initialized:
-            return
-        # Consume status updates without yielding them
-        async for _ in self._setup_mcp_with_status_stream(agent_id):
-            pass
-
-    async def _setup_mcp_tools_internal(
-        self,
-        agent_id: Optional[str] = None,
-        status_callback: Optional[Callable[[str, Dict[str, Any]], Awaitable[None]]] = None,
-    ) -> None:
-        """Internal MCP setup logic."""
-        if not self.mcp_servers or self._mcp_initialized:
-            return
-
-        if MCPClient is None:
-            reason = "MCP import failed - MCPClient not available"
-            log_backend_activity(
-                "gemini",
-                "MCP import failed",
-                {"reason": reason, "fallback": "workflow_tools"},
-                agent_id=agent_id,
-            )
-            if status_callback:
-                await status_callback(
-                    "error",
-                    {"message": "MCP import failed - falling back to workflow tools"},
-                )
-            # Clear MCP servers to prevent further attempts
-            self.mcp_servers = []
-            return
-
-        try:
-            # Validate MCP configuration before initialization
-            validated_config = {
-                "mcp_servers": self.mcp_servers,
-                "allowed_tools": self.allowed_tools,
-                "exclude_tools": self.exclude_tools,
-            }
-
-            if MCPConfigValidator is not None:
-                try:
-                    backend_config = {
-                        "mcp_servers": self.mcp_servers,
-                        "allowed_tools": self.allowed_tools,
-                        "exclude_tools": self.exclude_tools,
-                    }
-                    # Use the comprehensive validator class for enhanced validation
-                    validator = MCPConfigValidator()
-                    validated_config = validator.validate_backend_mcp_config(backend_config)
-                    self.mcp_servers = validated_config.get("mcp_servers", self.mcp_servers)
-                    log_backend_activity(
-                        "gemini",
-                        "MCP configuration validated",
-                        {"server_count": len(self.mcp_servers)},
-                        agent_id=agent_id,
-                    )
-                    if status_callback:
-                        await status_callback(
-                            "info",
-                            {"message": f"MCP configuration validated: {len(self.mcp_servers)} servers"},
-                        )
-
-                    # Log validated server names for debugging
-                    if True:
-                        server_names = [server.get("name", "unnamed") for server in self.mcp_servers]
-                        log_backend_activity(
-                            "gemini",
-                            "MCP servers validated",
-                            {"servers": server_names},
-                            agent_id=agent_id,
-                        )
-                except MCPConfigurationError as e:
-                    log_backend_activity(
-                        "gemini",
-                        "MCP configuration validation failed",
-                        {"error": e.original_message},
-                        agent_id=agent_id,
-                    )
-                    if status_callback:
-                        await status_callback(
-                            "error",
-                            {"message": f"Invalid MCP configuration: {e.original_message}"},
-                        )
-                    self._mcp_client = None  # Clear client state for consistency
-                    raise RuntimeError(f"Invalid MCP configuration: {e.original_message}") from e
-                except MCPValidationError as e:
-                    log_backend_activity(
-                        "gemini",
-                        "MCP validation failed",
-                        {"error": e.original_message},
-                        agent_id=agent_id,
-                    )
-                    if status_callback:
-                        await status_callback(
-                            "error",
-                            {"message": f"MCP validation error: {e.original_message}"},
-                        )
-                    self._mcp_client = None  # Clear client state for consistency
-                    raise RuntimeError(f"MCP validation error: {e.original_message}") from e
-                except Exception as e:
-                    if isinstance(e, (ImportError, AttributeError)):
-                        log_backend_activity(
-                            "gemini",
-                            "MCP validation unavailable",
-                            {"reason": str(e)},
-                            agent_id=agent_id,
-                        )
-                        # Don't clear client for import errors - validation just unavailable
-                    else:
-                        log_backend_activity(
-                            "gemini",
-                            "MCP validation error",
-                            {"error": str(e)},
-                            agent_id=agent_id,
-                        )
-                        self._mcp_client = None  # Clear client state for consistency
-                        raise RuntimeError(f"MCP configuration validation failed: {e}") from e
-            else:
-                log_backend_activity(
-                    "gemini",
-                    "MCP validation skipped",
-                    {"reason": "validator_unavailable"},
-                    agent_id=agent_id,
-                )
-
-            # Instead of the current fallback logic
-            normalized_servers = MCPSetupManager.normalize_mcp_servers(self.mcp_servers)
-            log_backend_activity(
-                "gemini",
-                "Setting up MCP sessions",
-                {"server_count": len(normalized_servers)},
-                agent_id=agent_id,
-            )
-            if status_callback:
-                await status_callback(
-                    "info",
-                    {"message": f"Setting up MCP sessions for {len(normalized_servers)} servers"},
-                )
-
-            # Apply circuit breaker filtering before connection attempts
-            if self._circuit_breakers_enabled and self._mcp_tools_circuit_breaker:
-                filtered_servers = MCPCircuitBreakerManager.apply_circuit_breaker_filtering(
-                    normalized_servers,
-                    self._mcp_tools_circuit_breaker,
-                    backend_name="gemini",
-                    agent_id=agent_id,
-                )
-            else:
-                filtered_servers = normalized_servers
-            if not filtered_servers:
-                log_backend_activity(
-                    "gemini",
-                    "All MCP servers blocked by circuit breaker",
-                    {},
-                    agent_id=agent_id,
-                )
-                if status_callback:
-                    await status_callback(
-                        "warning",
-                        {"message": "All MCP servers blocked by circuit breaker"},
-                    )
-                return
-
-            if len(filtered_servers) < len(normalized_servers):
-                log_backend_activity(
-                    "gemini",
-                    "Circuit breaker filtered servers",
-                    {"filtered_count": len(normalized_servers) - len(filtered_servers)},
-                    agent_id=agent_id,
-                )
-                if status_callback:
-                    await status_callback(
-                        "warning",
-                        {"message": f"Circuit breaker filtered {len(normalized_servers) - len(filtered_servers)} servers"},
-                    )
-
-            # Extract tool filtering parameters from validated config
-            allowed_tools = validated_config.get("allowed_tools")
-            exclude_tools = validated_config.get("exclude_tools")
-
-            # Log tool filtering if configured
-            if allowed_tools:
-                log_backend_activity(
-                    "gemini",
-                    "MCP tool filtering configured",
-                    {"allowed_tools": allowed_tools},
-                    agent_id=agent_id,
-                )
-            if exclude_tools:
-                log_backend_activity(
-                    "gemini",
-                    "MCP tool filtering configured",
-                    {"exclude_tools": exclude_tools},
-                    agent_id=agent_id,
-                )
-
-            # Create client with status callback and hooks
-            self._mcp_client = MCPClient(
-                filtered_servers,
-                timeout_seconds=30,
-                allowed_tools=allowed_tools,
-                exclude_tools=exclude_tools,
-                status_callback=status_callback,
-                hooks=self.filesystem_manager.get_pre_tool_hooks() if self.filesystem_manager else {},
-            )
-
-            # Connect the client
-            await self._mcp_client.connect()
-
-            # Determine which servers actually connected
-            try:
-                connected_server_names = self._mcp_client.get_server_names()
-            except Exception:
-                connected_server_names = []
-
-            if not connected_server_names:
-                # Treat as connection failure: no active servers
-                if self._circuit_breakers_enabled and self._mcp_tools_circuit_breaker:
-                    await MCPCircuitBreakerManager.record_event(
-                        filtered_servers,
-                        self._mcp_tools_circuit_breaker,
-                        "failure",
-                        error_message="No servers connected",
-                        backend_name="gemini",
-                        agent_id=agent_id,
-                    )
-
-                log_backend_activity(
-                    "gemini",
-                    "MCP connection failed: no servers connected",
-                    {},
-                    agent_id=agent_id,
-                )
-                if status_callback:
-                    await status_callback(
-                        "error",
-                        {"message": "MCP connection failed: no servers connected"},
-                    )
-                self._mcp_client = None
-                return
-
-            # Record success ONLY for servers that actually connected
-            connected_server_configs = [server for server in filtered_servers if server.get("name") in connected_server_names]
-            if connected_server_configs:
-                if self._circuit_breakers_enabled and self._mcp_tools_circuit_breaker:
-                    await MCPCircuitBreakerManager.record_event(
-                        connected_server_configs,
-                        self._mcp_tools_circuit_breaker,
-                        "success",
-                        backend_name="gemini",
-                        agent_id=agent_id,
-                    )
-
-            self._mcp_initialized = True
-            log_backend_activity("gemini", "MCP sessions initialized successfully", {}, agent_id=agent_id)
-            if status_callback:
-                await status_callback(
-                    "success",
-                    {"message": f"MCP sessions initialized successfully with {len(connected_server_names)} servers"},
-                )
-
-        except Exception as e:
-            # Record failure for circuit breaker
-            if self._circuit_breakers_enabled and self._mcp_tools_circuit_breaker:
-                servers = MCPSetupManager.normalize_mcp_servers(self.mcp_servers)
-                await MCPCircuitBreakerManager.record_event(
-                    servers,
-                    self._mcp_tools_circuit_breaker,
-                    "failure",
-                    error_message=str(e),
-                    backend_name="gemini",
-                    agent_id=agent_id,
-                )
-
-            # Enhanced error handling for different MCP error types
-            if isinstance(e, RuntimeError) and "MCP configuration" in str(e):
-                raise
-            elif isinstance(e, MCPConnectionError):
-                log_backend_activity(
-                    "gemini",
-                    "MCP connection failed during setup",
-                    {"error": str(e)},
-                    agent_id=agent_id,
-                )
-                if status_callback:
-                    await status_callback(
-                        "error",
-                        {"message": f"Failed to establish MCP connections: {e}"},
-                    )
-                self._mcp_client = None
-                raise RuntimeError(f"Failed to establish MCP connections: {e}") from e
-            elif isinstance(e, MCPTimeoutError):
-                log_backend_activity(
-                    "gemini",
-                    "MCP connection timeout during setup",
-                    {"error": str(e)},
-                    agent_id=agent_id,
-                )
-                if status_callback:
-                    await status_callback("error", {"message": f"MCP connection timeout: {e}"})
-                self._mcp_client = None
-                raise RuntimeError(f"MCP connection timeout: {e}") from e
-            elif isinstance(e, MCPServerError):
-                log_backend_activity(
-                    "gemini",
-                    "MCP server error during setup",
-                    {"error": str(e)},
-                    agent_id=agent_id,
-                )
-                if status_callback:
-                    await status_callback("error", {"message": f"MCP server error: {e}"})
-                self._mcp_client = None
-                raise RuntimeError(f"MCP server error: {e}") from e
-            elif isinstance(e, MCPError):
-                log_backend_activity(
-                    "gemini",
-                    "MCP error during setup",
-                    {"error": str(e)},
-                    agent_id=agent_id,
-                )
-                if status_callback:
-                    await status_callback("error", {"message": f"MCP error during setup: {e}"})
-                self._mcp_client = None
-                return
-
-            else:
-                log_backend_activity(
-                    "gemini",
-                    "MCP session setup failed",
-                    {"error": str(e)},
-                    agent_id=agent_id,
-                )
-                if status_callback:
-                    await status_callback("error", {"message": f"MCP session setup failed: {e}"})
-                self._mcp_client = None
-
-    def detect_coordination_tools(self, tools: List[Dict[str, Any]]) -> bool:
-        """Detect if tools contain vote/new_answer coordination tools."""
-        if not tools:
-            return False
-
-        tool_names = set()
-        for tool in tools:
-            if tool.get("type") == "function":
-                if "function" in tool:
-                    tool_names.add(tool["function"].get("name", ""))
-                elif "name" in tool:
-                    tool_names.add(tool.get("name", ""))
-
-        return "vote" in tool_names and "new_answer" in tool_names
-
-    def build_structured_output_prompt(self, base_content: str, valid_agent_ids: Optional[List[str]] = None) -> str:
-        """Build prompt that encourages structured output for coordination."""
-        agent_list = ""
-        if valid_agent_ids:
-            agent_list = f"Valid agents: {', '.join(valid_agent_ids)}"
-
-        return f"""{base_content}
-
-IMPORTANT: You must respond with a structured JSON decision at the end of your response.
-
-If you want to VOTE for an existing agent's answer:
-{{
-  "action_type": "vote",
-  "vote_data": {{
-    "action": "vote",
-    "agent_id": "agent1",  // Choose from: {agent_list or "agent1, agent2, agent3, etc."}
-    "reason": "Brief reason for your vote"
-  }}
-}}
-
-If you want to provide a NEW ANSWER:
-{{
-  "action_type": "new_answer",
-  "answer_data": {{
-    "action": "new_answer",
-    "content": "Your complete improved answer here"
-  }}
-}}
-
-Make your decision and include the JSON at the very end of your response."""
-
-    def extract_structured_response(self, response_text: str) -> Optional[Dict[str, Any]]:
-        """Extract structured JSON response from model output."""
-        try:
-            # Strategy 0: Look for JSON inside markdown code blocks first
-            markdown_json_pattern = r"```json\s*(\{.*?\})\s*```"
-            markdown_matches = re.findall(markdown_json_pattern, response_text, re.DOTALL)
-
-            for match in reversed(markdown_matches):
-                try:
-                    parsed = json.loads(match.strip())
-                    if isinstance(parsed, dict) and "action_type" in parsed:
-                        return parsed
-                except json.JSONDecodeError:
-                    continue
-
-            # Strategy 1: Look for complete JSON blocks with proper braces
-            json_pattern = r"\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\}"
-            json_matches = re.findall(json_pattern, response_text, re.DOTALL)
-
-            # Try parsing each match (in reverse order - last one first)
-            for match in reversed(json_matches):
-                try:
-                    cleaned_match = match.strip()
-                    parsed = json.loads(cleaned_match)
-                    if isinstance(parsed, dict) and "action_type" in parsed:
-                        return parsed
-                except json.JSONDecodeError:
-                    continue
-
-            # Strategy 2: Look for JSON blocks with nested braces (more complex)
-            brace_count = 0
-            json_start = -1
-
-            for i, char in enumerate(response_text):
-                if char == "{":
-                    if brace_count == 0:
-                        json_start = i
-                    brace_count += 1
-                elif char == "}":
-                    brace_count -= 1
-                    if brace_count == 0 and json_start >= 0:
-                        # Found a complete JSON block
-                        json_block = response_text[json_start : i + 1]
-                        try:
-                            parsed = json.loads(json_block)
-                            if isinstance(parsed, dict) and "action_type" in parsed:
-                                return parsed
-                        except json.JSONDecodeError:
-                            pass
-                        json_start = -1
-
-            # Strategy 3: Line-by-line approach (fallback)
-            lines = response_text.strip().split("\n")
-            json_candidates = []
-
-            for i, line in enumerate(lines):
-                stripped = line.strip()
-                if stripped.startswith("{") and stripped.endswith("}"):
-                    json_candidates.append(stripped)
-                elif stripped.startswith("{"):
-                    # Multi-line JSON - collect until closing brace
-                    json_text = stripped
-                    for j in range(i + 1, len(lines)):
-                        json_text += "\n" + lines[j].strip()
-                        if lines[j].strip().endswith("}"):
-                            json_candidates.append(json_text)
-                            break
-
-            # Try to parse each candidate
-            for candidate in reversed(json_candidates):
-                try:
-                    parsed = json.loads(candidate)
-                    if isinstance(parsed, dict) and "action_type" in parsed:
-                        return parsed
-                except json.JSONDecodeError:
-                    continue
-
-            return None
-
-        except Exception:
-            return None
-
-    def convert_structured_to_tool_calls(self, structured_response: Dict[str, Any]) -> List[Dict[str, Any]]:
-        """Convert structured response to tool call format."""
-        action_type = structured_response.get("action_type")
-
-        if action_type == "vote":
-            vote_data = structured_response.get("vote_data", {})
-            return [
-                {
-                    "id": f"vote_{abs(hash(str(vote_data))) % 10000 + 1}",
-                    "type": "function",
-                    "function": {
-                        "name": "vote",
-                        "arguments": {
-                            "agent_id": vote_data.get("agent_id", ""),
-                            "reason": vote_data.get("reason", ""),
-                        },
-                    },
-                },
-            ]
-
-        elif action_type == "new_answer":
-            answer_data = structured_response.get("answer_data", {})
-            return [
-                {
-                    "id": f"new_answer_{abs(hash(str(answer_data))) % 10000 + 1}",
-                    "type": "function",
-                    "function": {
-                        "name": "new_answer",
-                        "arguments": {"content": answer_data.get("content", "")},
-                    },
-                },
-            ]
-
-        return []
-
-    async def _handle_mcp_retry_error(self, error: Exception, retry_count: int, max_retries: int) -> tuple[bool, AsyncGenerator[StreamChunk, None]]:
-        """Handle MCP retry errors with specific messaging and fallback logic.
-
-        Returns:
-            tuple: (should_continue_retrying, error_chunks_generator)
+    async def _process_stream(self, stream, all_params, agent_id: Optional[str] = None) -> AsyncGenerator[StreamChunk, None]:
         """
-        log_type, user_message, _ = MCPErrorHandler.get_error_details(error, None, log=False)
-
-        # Log the retry attempt
-        log_backend_activity(
-            "gemini",
-            f"MCP {log_type} on retry",
-            {"attempt": retry_count, "error": str(error)},
-            agent_id=self.agent_id,
-        )
-
-        # Check if we've exhausted retries
-        if retry_count >= max_retries:
-
-            async def error_chunks():
-                yield StreamChunk(
-                    type="content",
-                    content=f"\n⚠️  {user_message} after {max_retries} attempts; falling back to workflow tools\n",
-                )
-
-            return False, error_chunks()
-
-        # Continue retrying
-        async def empty_chunks():
-            # Empty generator - just return without yielding anything
-            if False:  # Make this a generator without actually yielding
-                yield
-
-        return True, empty_chunks()
-
-    async def _handle_mcp_error_and_fallback(
-        self,
-        error: Exception,
-    ) -> AsyncGenerator[StreamChunk, None]:
-        """Handle MCP errors with specific messaging"""
-        self._mcp_tool_failures += 1
-
-        log_type, user_message, _ = MCPErrorHandler.get_error_details(error, None, log=False)
-
-        # Log with specific error type
-        log_backend_activity(
-            "gemini",
-            "MCP tool call failed",
-            {
-                "call_number": self._mcp_tool_calls_count,
-                "error_type": log_type,
-                "error": str(error),
-            },
-            agent_id=self.agent_id,
-        )
-
-        # Yield user-friendly error message
-        yield StreamChunk(
-            type="content",
-            content=f"\n⚠️  {user_message} ({error}); continuing without MCP tools\n",
-        )
-
-    async def _execute_mcp_function_with_retry(self, function_name: str, args: Dict[str, Any], agent_id: Optional[str] = None) -> Any:
-        """Execute MCP function with exponential backoff retry logic."""
-        if MCPExecutionManager is None:
-            raise RuntimeError("MCPExecutionManager is not available - MCP backend utilities are missing")
-
-        # Stats callback for tracking
-        async def stats_callback(action: str) -> int:
-            if action == "increment_calls":
-                self._mcp_tool_calls_count += 1
-                return self._mcp_tool_calls_count
-            elif action == "increment_failures":
-                self._mcp_tool_failures += 1
-                return self._mcp_tool_failures
-            return 0
-
-        # Circuit breaker callback
-        async def circuit_breaker_callback(event: str, error_msg: str) -> None:
-            if event == "failure":
-                if self._circuit_breakers_enabled and self._mcp_tools_circuit_breaker:
-                    servers = MCPSetupManager.normalize_mcp_servers(self.mcp_servers)
-                    await MCPCircuitBreakerManager.record_event(
-                        servers,
-                        self._mcp_tools_circuit_breaker,
-                        "failure",
-                        error_message=error_msg,
-                        backend_name="gemini",
-                        agent_id=agent_id,
-                    )
-            else:
-                # Record success only for currently connected servers
-                connected_names: List[str] = []
-                try:
-                    if self._mcp_client:
-                        connected_names = self._mcp_client.get_server_names()
-                except Exception:
-                    connected_names = []
-
-                if connected_names:
-                    servers_to_record = [{"name": name} for name in connected_names]
-                    if self._circuit_breakers_enabled and self._mcp_tools_circuit_breaker:
-                        await MCPCircuitBreakerManager.record_event(
-                            servers_to_record,
-                            self._mcp_tools_circuit_breaker,
-                            "success",
-                            backend_name="gemini",
-                            agent_id=agent_id,
-                        )
+        Required by CustomToolAndMCPBackend abstract method.
+        Not used by Gemini - Gemini SDK handles streaming directly in stream_with_tools().
+        """
+        if False:
+            yield  # Make this an async generator
+        raise NotImplementedError("Gemini uses custom streaming logic in stream_with_tools()")
 
-        return await MCPExecutionManager.execute_function_with_retry(
-            function_name=function_name,
-            args=args,
-            functions=self.functions,
-            max_retries=3,
-            stats_callback=stats_callback,
-            circuit_breaker_callback=circuit_breaker_callback,
-            logger_instance=logger,
-        )
+    async def _setup_mcp_tools(self) -> None:
+        """
+        Override parent class - Gemini uses GeminiMCPManager for MCP setup.
+        This method is called by the parent class's __aenter__() context manager.
+        """
+        await self.mcp_manager.setup_mcp_tools(agent_id=self.agent_id)
+
+    def supports_upload_files(self) -> bool:
+        """
+        Override parent class - Gemini does not support upload_files preprocessing.
+        Returns False to skip upload_files processing in parent class methods.
+        """
+        return False
 
     async def stream_with_tools(self, messages: List[Dict[str, Any]], tools: List[Dict[str, Any]], **kwargs) -> AsyncGenerator[StreamChunk, None]:
         """Stream response using Gemini API with structured output for coordination and MCP tool support."""
@@ -1216,26 +197,29 @@ Make your decision and include the JSON at the very end of your response."""
         try:
             from google import genai
 
-            # Setup MCP with status streaming if not already initialized
+            # Setup MCP with status streaming via manager if not already initialized
             if not self._mcp_initialized and self.mcp_servers:
-                async for chunk in self._setup_mcp_with_status_stream(agent_id):
+                async for chunk in self.mcp_manager.setup_mcp_with_status_stream(agent_id):
                     yield chunk
             elif not self._mcp_initialized:
                 # Setup MCP without streaming for backward compatibility
-                await self._setup_mcp_tools(agent_id)
+                await self.mcp_manager.setup_mcp_tools(agent_id)
 
             # Merge constructor config with stream kwargs (stream kwargs take priority)
             all_params = {**self.config, **kwargs}
 
             # Extract framework-specific parameters
-            enable_web_search = all_params.get("enable_web_search", False)
+            all_params.get("enable_web_search", False)
             enable_code_execution = all_params.get("enable_code_execution", False)
 
             # Always use SDK MCP sessions when mcp_servers are configured
             using_sdk_mcp = bool(self.mcp_servers)
 
+            # Custom tool handling - add custom tools if any
+            using_custom_tools = bool(self.custom_tool_manager and len(self._custom_tool_names) > 0)
+
             # Analyze tool types
-            is_coordination = self.detect_coordination_tools(tools)
+            is_coordination = self.formatter.has_coordination_tools(tools)
 
             valid_agent_ids = None
 
@@ -1250,84 +234,21 @@ Make your decision and include the JSON at the very end of your response."""
                                 valid_agent_ids = agent_id_param["enum"]
                             break
 
-            # Build content string from messages (include tool results for multi-turn tool calling)
-            conversation_content = ""
-            system_message = ""
-
-            for msg in messages:
-                role = msg.get("role")
-                if role == "system":
-                    system_message = msg.get("content", "")
-                elif role == "user":
-                    conversation_content += f"User: {msg.get('content', '')}\n"
-                elif role == "assistant":
-                    conversation_content += f"Assistant: {msg.get('content', '')}\n"
-                elif role == "tool":
-                    # Ensure tool outputs are visible to the model on the next turn
-                    tool_output = msg.get("content", "")
-                    conversation_content += f"Tool Result: {tool_output}\n"
-
+            # Build content string from messages using formatter
+            full_content = self.formatter.format_messages(messages)
             # For coordination requests, modify the prompt to use structured output
             if is_coordination:
-                conversation_content = self.build_structured_output_prompt(conversation_content, valid_agent_ids)
-
-            # Combine system message and conversation
-            full_content = ""
-            if system_message:
-                full_content += f"{system_message}\n\n"
-            full_content += conversation_content
+                full_content = self.formatter.build_structured_output_prompt(full_content, valid_agent_ids)
 
             # Use google-genai package
             client = genai.Client(api_key=self.api_key)
 
-            # Setup builtin tools (only when not using SDK MCP sessions)
-            builtin_tools = []
-            if enable_web_search:
-                try:
-                    from google.genai import types
-
-                    grounding_tool = types.Tool(google_search=types.GoogleSearch())
-                    builtin_tools.append(grounding_tool)
-                except ImportError:
-                    yield StreamChunk(
-                        type="content",
-                        content="\n⚠️  Web search requires google.genai.types\n",
-                    )
-
-            if enable_code_execution:
-                try:
-                    from google.genai import types
-
-                    code_tool = types.Tool(code_execution=types.ToolCodeExecution())
-                    builtin_tools.append(code_tool)
-                except ImportError:
-                    yield StreamChunk(
-                        type="content",
-                        content="\n⚠️  Code execution requires google.genai.types\n",
-                    )
-
-            # Build config with direct parameter passthrough
-            config = {}
-
-            # Direct passthrough of all parameters except those handled separately
-            excluded_params = self.get_base_excluded_config_params() | {
-                # Gemini specific exclusions
-                "enable_web_search",
-                "enable_code_execution",
-                "use_multi_mcp",
-                "mcp_sdk_auto",
-                "allowed_tools",
-                "exclude_tools",
-            }
-            for key, value in all_params.items():
-                if key not in excluded_params and value is not None:
-                    # Handle Gemini-specific parameter mappings
-                    if key == "max_tokens":
-                        config["max_output_tokens"] = value
-                    elif key == "model":
-                        model_name = value
-                    else:
-                        config[key] = value
+            # Setup builtin tools via API params handler (SDK Tool objects)
+            builtin_tools = self.api_params_handler.get_provider_tools(all_params)
+            # Build config via API params handler (maps params, excludes backend-managed ones)
+            config = await self.api_params_handler.build_api_params(messages, tools, all_params)
+            # Extract model name (not included in config)
+            model_name = all_params.get("model")
 
             # Setup tools configuration (builtins only when not using sessions)
             all_tools = []
@@ -1335,143 +256,14 @@ Make your decision and include the JSON at the very end of your response."""
             # Branch 1: SDK auto-calling via MCP sessions (reuse existing MCPClient sessions)
             if using_sdk_mcp and self.mcp_servers:
                 if not self._mcp_client or not getattr(self._mcp_client, "is_connected", lambda: False)():
-                    # Retry MCP connection up to 5 times before falling back
-                    max_mcp_retries = 5
-                    mcp_connected = False
-
-                    for retry_count in range(1, max_mcp_retries + 1):
-                        try:
-                            # Track retry attempts
-                            self._mcp_connection_retries = retry_count
-
-                            if retry_count > 1:
-                                log_backend_activity(
-                                    "gemini",
-                                    "MCP connection retry",
-                                    {
-                                        "attempt": retry_count,
-                                        "max_retries": max_mcp_retries,
-                                    },
-                                    agent_id=agent_id,
-                                )
-                                # Yield retry status
-                                yield StreamChunk(
-                                    type="mcp_status",
-                                    status="mcp_retry",
-                                    content=f"Retrying MCP connection (attempt {retry_count}/{max_mcp_retries})",
-                                    source="mcp_tools",
-                                )
-                                # Brief delay between retries
-                                await asyncio.sleep(0.5 * retry_count)  # Progressive backoff
-
-                            # Apply circuit breaker filtering before retry attempts
-                            if self._circuit_breakers_enabled and self._mcp_tools_circuit_breaker:
-                                filtered_retry_servers = MCPCircuitBreakerManager.apply_circuit_breaker_filtering(
-                                    self.mcp_servers,
-                                    self._mcp_tools_circuit_breaker,
-                                    backend_name="gemini",
-                                    agent_id=agent_id,
-                                )
-                            else:
-                                filtered_retry_servers = self.mcp_servers
-                            if not filtered_retry_servers:
-                                log_backend_activity(
-                                    "gemini",
-                                    "All MCP servers blocked during retry",
-                                    {},
-                                    agent_id=agent_id,
-                                )
-                                # Yield blocked status
-                                yield StreamChunk(
-                                    type="mcp_status",
-                                    status="mcp_blocked",
-                                    content="All MCP servers blocked by circuit breaker",
-                                    source="mcp_tools",
-                                )
-                                using_sdk_mcp = False
-                                break
-
-                            # Get validated config for tool filtering parameters
-                            backend_config = {"mcp_servers": self.mcp_servers}
-                            if MCPConfigValidator is not None:
-                                try:
-                                    validator = MCPConfigValidator()
-                                    validated_config_retry = validator.validate_backend_mcp_config(backend_config)
-                                    allowed_tools_retry = validated_config_retry.get("allowed_tools")
-                                    exclude_tools_retry = validated_config_retry.get("exclude_tools")
-                                except Exception:
-                                    allowed_tools_retry = None
-                                    exclude_tools_retry = None
-                            else:
-                                allowed_tools_retry = None
-                                exclude_tools_retry = None
-
-                            self._mcp_client = await MCPClient.create_and_connect(
-                                filtered_retry_servers,
-                                timeout_seconds=30,
-                                allowed_tools=allowed_tools_retry,
-                                exclude_tools=exclude_tools_retry,
-                            )
-
-                            # Record success for circuit breaker
-                            if self._circuit_breakers_enabled and self._mcp_tools_circuit_breaker:
-                                await MCPCircuitBreakerManager.record_event(
-                                    filtered_retry_servers,
-                                    self._mcp_tools_circuit_breaker,
-                                    "success",
-                                    backend_name="gemini",
-                                    agent_id=agent_id,
-                                )
-                            mcp_connected = True
-                            log_backend_activity(
-                                "gemini",
-                                "MCP connection successful on retry",
-                                {"attempt": retry_count},
-                                agent_id=agent_id,
-                            )
-                            # Yield success status
-                            yield StreamChunk(
-                                type="mcp_status",
-                                status="mcp_connected",
-                                content=f"MCP connection successful on attempt {retry_count}",
-                                source="mcp_tools",
-                            )
-                            break
-
-                        except (
-                            MCPConnectionError,
-                            MCPTimeoutError,
-                            MCPServerError,
-                            MCPError,
-                            Exception,
-                        ) as e:
-                            # Record failure for circuit breaker
-                            if self._circuit_breakers_enabled and self._mcp_tools_circuit_breaker:
-                                servers = MCPSetupManager.normalize_mcp_servers(self.mcp_servers)
-                                await MCPCircuitBreakerManager.record_event(
-                                    servers,
-                                    self._mcp_tools_circuit_breaker,
-                                    "failure",
-                                    error_message=str(e),
-                                    backend_name="gemini",
-                                    agent_id=agent_id,
-                                )
-
-                            (
-                                should_continue,
-                                error_chunks,
-                            ) = await self._handle_mcp_retry_error(e, retry_count, max_mcp_retries)
-                            if not should_continue:
-                                async for chunk in error_chunks:
-                                    yield chunk
-                                using_sdk_mcp = False
-
-                    # If all retries failed, ensure we fall back gracefully
+                    mcp_connected, status_chunks = await self.mcp_manager.setup_mcp_sessions_with_retry(agent_id, max_retries=5)
+                    async for chunk in status_chunks:
+                        yield chunk
                     if not mcp_connected:
                         using_sdk_mcp = False
                         self._mcp_client = None
 
-            if not using_sdk_mcp:
+            if not using_sdk_mcp and not using_custom_tools:
                 all_tools.extend(builtin_tools)
                 if all_tools:
                     config["tools"] = all_tools
@@ -1479,7 +271,7 @@ Make your decision and include the JSON at the very end of your response."""
             # For coordination requests, use JSON response format (may conflict with tools/sessions)
             if is_coordination:
                 # Only request JSON schema when no tools are present
-                if (not using_sdk_mcp) and (not all_tools):
+                if (not using_sdk_mcp) and (not using_custom_tools) and (not all_tools):
                     config["response_mime_type"] = "application/json"
                     config["response_schema"] = CoordinationResponse.model_json_schema()
                 else:
@@ -1499,107 +291,327 @@ Make your decision and include the JSON at the very end of your response."""
             # Use streaming for real-time response
             full_content_text = ""
             final_response = None
-            if using_sdk_mcp and self.mcp_servers:
-                # Reuse active sessions from MCPClient
+            # Buffer the last response chunk that contains candidate metadata so we can
+            # inspect builtin tool usage (grounding/code execution) after streaming
+            last_response_with_candidates = None
+            if (using_sdk_mcp and self.mcp_servers) or using_custom_tools:
+                # Process MCP and/or custom tools
                 try:
-                    if not self._mcp_client:
-                        raise RuntimeError("MCP client not initialized")
-                    mcp_sessions = self._mcp_client.get_active_sessions()
-                    if not mcp_sessions:
-                        raise RuntimeError("No active MCP sessions available")
-
-                    # Convert sessions to permission sessions if filesystem manager is available
-                    if self.filesystem_manager:
-                        logger.info(f"[Gemini] Converting {len(mcp_sessions)} MCP sessions to permission sessions")
+                    # ====================================================================
+                    # Preparation phase: Initialize MCP and custom tools
+                    # ====================================================================
+                    mcp_sessions = []
+                    mcp_error = None
+                    custom_tools_functions = []
+                    custom_tools_error = None
+
+                    # Try to initialize MCP sessions
+                    if using_sdk_mcp and self.mcp_servers:
                         try:
-                            from ..mcp_tools.hooks import (
-                                convert_sessions_to_permission_sessions,
+                            if not self._mcp_client:
+                                raise RuntimeError("MCP client not initialized")
+                            mcp_sessions = self.mcp_manager.get_active_mcp_sessions(
+                                convert_to_permission_sessions=bool(self.filesystem_manager),
                             )
+                            if not mcp_sessions:
+                                # If no MCP sessions, record error but don't interrupt (may still have custom tools)
+                                mcp_error = RuntimeError("No active MCP sessions available")
+                                logger.warning(f"[Gemini] MCP sessions unavailable: {mcp_error}")
+                        except Exception as e:
+                            mcp_error = e
+                            logger.warning(f"[Gemini] Failed to initialize MCP sessions: {e}")
+
+                    # Try to initialize custom tools
+                    if using_custom_tools:
+                        try:
+                            # Get custom tools schemas (in OpenAI format)
+                            custom_tools_schemas = self._get_custom_tools_schemas()
+                            if custom_tools_schemas:
+                                # Convert to Gemini SDK format using formatter
+                                # formatter handles: OpenAI format -> Gemini dict -> FunctionDeclaration objects
+                                custom_tools_functions = self.formatter.format_custom_tools(
+                                    custom_tools_schemas,
+                                    return_sdk_objects=True,
+                                )
 
-                            mcp_sessions = convert_sessions_to_permission_sessions(mcp_sessions, self.filesystem_manager.path_permission_manager)
+                                if custom_tools_functions:
+                                    logger.debug(
+                                        f"[Gemini] Loaded {len(custom_tools_functions)} custom tools " f"as FunctionDeclarations",
+                                    )
+                                else:
+                                    custom_tools_error = RuntimeError("Custom tools conversion failed")
+                                    logger.warning(f"[Gemini] Custom tools unavailable: {custom_tools_error}")
+                            else:
+                                custom_tools_error = RuntimeError("No custom tools available")
+                                logger.warning(f"[Gemini] Custom tools unavailable: {custom_tools_error}")
                         except Exception as e:
-                            logger.error(f"[Gemini] Failed to convert sessions to permission sessions: {e}")
-                            # Continue with regular sessions on error
-                    else:
-                        logger.debug("[Gemini] No filesystem manager found, using standard sessions")
+                            custom_tools_error = e
+                            logger.warning(f"[Gemini] Failed to initialize custom tools: {e}")
 
-                    # Apply sessions as tools, do not mix with builtin or function_declarations
+                    # Check if at least one tool system is available
+                    has_mcp = bool(mcp_sessions and not mcp_error)
+                    has_custom_tools = bool(custom_tools_functions and not custom_tools_error)
+
+                    if not has_mcp and not has_custom_tools:
+                        # Both failed, raise error to enter fallback
+                        raise RuntimeError(
+                            f"Both MCP and custom tools unavailable. " f"MCP error: {mcp_error}. Custom tools error: {custom_tools_error}",
+                        )
+
+                    # ====================================================================
+                    # Configuration phase: Build session_config
+                    # ====================================================================
                     session_config = dict(config)
 
-                    # Get available tools from MCP client for logging
-                    available_tools = []
-                    if self._mcp_client:
-                        available_tools = list(self._mcp_client.tools.keys())
+                    # Collect all available tool information
+                    available_mcp_tools = []
+                    if has_mcp and self._mcp_client:
+                        available_mcp_tools = list(self._mcp_client.tools.keys())
+
+                    available_custom_tool_names = list(self._custom_tool_names) if has_custom_tools else []
+
+                    # Apply tools to config
+                    tools_to_apply = []
+                    sessions_applied = False
+                    custom_tools_applied = False
+
+                    # Add MCP sessions (if available and not blocked by planning mode)
+                    if has_mcp:
+                        if not self.mcp_manager.should_block_mcp_tools_in_planning_mode(
+                            self.is_planning_mode_enabled(),
+                            available_mcp_tools,
+                        ):
+                            logger.debug(
+                                f"[Gemini] Passing {len(mcp_sessions)} MCP sessions to SDK: " f"{[type(s).__name__ for s in mcp_sessions]}",
+                            )
+                            tools_to_apply.extend(mcp_sessions)
+                            sessions_applied = True
+
+                    # Add custom tools (if available)
+                    if has_custom_tools:
+                        # Wrap FunctionDeclarations in a Tool object for Gemini SDK
+                        try:
+                            from google.genai import types
+
+                            # Create a Tool object containing all custom function declarations
+                            custom_tool = types.Tool(function_declarations=custom_tools_functions)
+
+                            logger.debug(
+                                f"[Gemini] Wrapped {len(custom_tools_functions)} custom tools " f"in Tool object for SDK",
+                            )
+                            tools_to_apply.append(custom_tool)
+                            custom_tools_applied = True
+                        except Exception as e:
+                            logger.error(f"[Gemini] Failed to wrap custom tools in Tool object: {e}")
+                            custom_tools_error = e
+
+                    # Apply tool configuration
+                    if tools_to_apply:
+                        session_config["tools"] = tools_to_apply
+
+                        # Disable automatic function calling for custom tools
+                        # MassGen uses declarative mode: SDK should return function call requests
+                        # instead of automatically executing them
+                        if has_custom_tools:
+                            from google.genai import types
+
+                            session_config["automatic_function_calling"] = types.AutomaticFunctionCallingConfig(
+                                disable=True,
+                            )
+                            logger.debug("[Gemini] Disabled automatic function calling for custom tools")
+
+                    # ====================================================================
+                    # Logging and status output
+                    # ====================================================================
+                    if sessions_applied:
+                        # Track MCP tool usage attempt
+                        self._mcp_tool_calls_count += 1
 
-                    # Check planning mode - block MCP tools during coordination phase
-                    if self.is_planning_mode_enabled():
-                        logger.info("[Gemini] Planning mode enabled - blocking MCP tools during coordination")
-                        # Don't set tools, which prevents automatic function calling
                         log_backend_activity(
                             "gemini",
-                            "MCP tools blocked in planning mode",
+                            "MCP tool call initiated",
                             {
-                                "blocked_tools": len(available_tools),
+                                "call_number": self._mcp_tool_calls_count,
                                 "session_count": len(mcp_sessions),
+                                "available_tools": available_mcp_tools[:],
+                                "total_tools": len(available_mcp_tools),
                             },
                             agent_id=agent_id,
                         )
-                    else:
-                        # Log session types for debugging if needed
-                        logger.debug(f"[Gemini] Passing {len(mcp_sessions)} sessions to SDK: {[type(s).__name__ for s in mcp_sessions]}")
-
-                        session_config["tools"] = mcp_sessions
-
-                    # Track MCP tool usage attempt
-                    self._mcp_tool_calls_count += 1
-
-                    log_backend_activity(
-                        "gemini",
-                        "MCP tool call initiated",
-                        {
-                            "call_number": self._mcp_tool_calls_count,
-                            "session_count": len(mcp_sessions),
-                            "available_tools": available_tools[:],  # Log first 10 tools for brevity
-                            "total_tools": len(available_tools),
-                        },
-                        agent_id=agent_id,
-                    )
 
-                    # Log MCP tool usage (SDK handles actual tool calling automatically)
-                    log_tool_call(
-                        agent_id,
-                        "mcp_session_tools",
-                        {
-                            "session_count": len(mcp_sessions),
-                            "call_number": self._mcp_tool_calls_count,
-                            "available_tools": available_tools,
-                        },
-                        backend_name="gemini",
-                    )
+                        log_tool_call(
+                            agent_id,
+                            "mcp_session_tools",
+                            {
+                                "session_count": len(mcp_sessions),
+                                "call_number": self._mcp_tool_calls_count,
+                                "available_tools": available_mcp_tools,
+                            },
+                            backend_name="gemini",
+                        )
 
-                    # Yield detailed MCP status as StreamChunk
-                    tools_info = f" ({len(available_tools)} tools available)" if available_tools else ""
-                    yield StreamChunk(
-                        type="mcp_status",
-                        status="mcp_tools_initiated",
-                        content=f"MCP tool call initiated (call #{self._mcp_tool_calls_count}){tools_info}: {', '.join(available_tools[:5])}{'...' if len(available_tools) > 5 else ''}",
-                        source="mcp_tools",
-                    )
+                        tools_info = f" ({len(available_mcp_tools)} tools available)" if available_mcp_tools else ""
+                        yield StreamChunk(
+                            type="mcp_status",
+                            status="mcp_tools_initiated",
+                            content=f"MCP tool call initiated (call #{self._mcp_tool_calls_count}){tools_info}: {', '.join(available_mcp_tools[:5])}{'...' if len(available_mcp_tools) > 5 else ''}",
+                            source="mcp_tools",
+                        )
+
+                    if custom_tools_applied:
+                        # Track custom tool usage attempt
+                        log_backend_activity(
+                            "gemini",
+                            "Custom tools initiated",
+                            {
+                                "tool_count": len(custom_tools_functions),
+                                "available_tools": available_custom_tool_names,
+                            },
+                            agent_id=agent_id,
+                        )
 
-                    # Use async streaming call with sessions (SDK supports auto-calling MCP here)
-                    # The SDK's session feature will still handle tool calling automatically
-                    stream = await client.aio.models.generate_content_stream(model=model_name, contents=full_content, config=session_config)
+                        tools_preview = ", ".join(available_custom_tool_names[:5])
+                        tools_suffix = "..." if len(available_custom_tool_names) > 5 else ""
+                        yield StreamChunk(
+                            type="custom_tool_status",
+                            status="custom_tools_initiated",
+                            content=f"Custom tools initiated ({len(custom_tools_functions)} tools available): {tools_preview}{tools_suffix}",
+                            source="custom_tools",
+                        )
+
+                    # ====================================================================
+                    # Streaming phase
+                    # ====================================================================
+                    # Use async streaming call with sessions/tools
+                    stream = await client.aio.models.generate_content_stream(
+                        model=model_name,
+                        contents=full_content,
+                        config=session_config,
+                    )
 
-                    # Initialize MCPCallTracker and MCPResponseTracker for deduplication across chunks
+                    # Initialize trackers for both MCP and custom tools
                     mcp_tracker = MCPCallTracker()
                     mcp_response_tracker = MCPResponseTracker()
+                    custom_tracker = MCPCallTracker()  # Reuse MCPCallTracker for custom tools
+                    custom_response_tracker = MCPResponseTracker()  # Reuse for custom tools
+
                     mcp_tools_used = []  # Keep for backward compatibility
+                    custom_tools_used = []  # Track custom tool usage
 
                     # Iterate over the asynchronous stream to get chunks as they arrive
                     async for chunk in stream:
                         # ============================================
-                        # 1. Process MCP function calls/responses
+                        # 1. Process function calls/responses
                         # ============================================
+
+                        # First check for function calls in the current chunk's candidates
+                        # (this is where custom tool calls appear, not in automatic_function_calling_history)
+                        if hasattr(chunk, "candidates") and chunk.candidates:
+                            for candidate in chunk.candidates:
+                                if hasattr(candidate, "content") and candidate.content:
+                                    if hasattr(candidate.content, "parts") and candidate.content.parts:
+                                        for part in candidate.content.parts:
+                                            # Check for function_call part
+                                            if hasattr(part, "function_call") and part.function_call:
+                                                # Extract call data
+                                                call_data = self.mcp_extractor.extract_function_call(part.function_call)
+
+                                                if call_data:
+                                                    tool_name = call_data["name"]
+                                                    tool_args = call_data["arguments"]
+
+                                                    # DEBUG: Log tool matching
+                                                    logger.info(f"🔍 [DEBUG] Function call detected: tool_name='{tool_name}'")
+                                                    logger.info(f"🔍 [DEBUG] Available MCP tools: {available_mcp_tools}")
+                                                    logger.info(f"🔍 [DEBUG] Available custom tools: {list(self._custom_tool_names) if has_custom_tools else []}")
+
+                                                    # Determine if it's MCP tool or custom tool
+                                                    # MCP tools may come from SDK without prefix, so we need to check both:
+                                                    # 1. Direct match (tool_name in list)
+                                                    # 2. Prefixed match (mcp__server__tool_name in list)
+                                                    is_mcp_tool = False
+                                                    if has_mcp:
+                                                        # Direct match
+                                                        if tool_name in available_mcp_tools:
+                                                            is_mcp_tool = True
+                                                        else:
+                                                            # Try matching with MCP prefix format: mcp__<server>__<tool>
+                                                            # Check if any available MCP tool ends with the current tool_name
+                                                            for mcp_tool in available_mcp_tools:
+                                                                # Format: mcp__server__toolname
+                                                                if mcp_tool.startswith("mcp__") and mcp_tool.endswith(f"__{tool_name}"):
+                                                                    is_mcp_tool = True
+                                                                    logger.info(f"🔍 [DEBUG] Matched MCP tool: {tool_name} -> {mcp_tool}")
+                                                                    break
+
+                                                    is_custom_tool = has_custom_tools and tool_name in self._custom_tool_names
+
+                                                    logger.info(f"🔍 [DEBUG] Tool matching result: is_mcp_tool={is_mcp_tool}, is_custom_tool={is_custom_tool}")
+
+                                                    if is_custom_tool:
+                                                        # Process custom tool call
+                                                        if custom_tracker.is_new_call(tool_name, tool_args):
+                                                            call_record = custom_tracker.add_call(tool_name, tool_args)
+
+                                                            custom_tools_used.append(
+                                                                {
+                                                                    "name": tool_name,
+                                                                    "arguments": tool_args,
+                                                                    "timestamp": call_record["timestamp"],
+                                                                },
+                                                            )
+
+                                                            timestamp_str = time.strftime(
+                                                                "%H:%M:%S",
+                                                                time.localtime(call_record["timestamp"]),
+                                                            )
+
+                                                            yield StreamChunk(
+                                                                type="custom_tool_status",
+                                                                status="custom_tool_called",
+                                                                content=f"🔧 Custom Tool Called: {tool_name} at {timestamp_str} with args: {json.dumps(tool_args, indent=2)}",
+                                                                source="custom_tools",
+                                                            )
+
+                                                            log_tool_call(
+                                                                agent_id,
+                                                                tool_name,
+                                                                tool_args,
+                                                                backend_name="gemini",
+                                                            )
+                                                    elif is_mcp_tool:
+                                                        # Process MCP tool call
+                                                        if mcp_tracker.is_new_call(tool_name, tool_args):
+                                                            call_record = mcp_tracker.add_call(tool_name, tool_args)
+
+                                                            mcp_tools_used.append(
+                                                                {
+                                                                    "name": tool_name,
+                                                                    "arguments": tool_args,
+                                                                    "timestamp": call_record["timestamp"],
+                                                                },
+                                                            )
+
+                                                            timestamp_str = time.strftime(
+                                                                "%H:%M:%S",
+                                                                time.localtime(call_record["timestamp"]),
+                                                            )
+
+                                                            yield StreamChunk(
+                                                                type="mcp_status",
+                                                                status="mcp_tool_called",
+                                                                content=f"🔧 MCP Tool Called: {tool_name} at {timestamp_str} with args: {json.dumps(tool_args, indent=2)}",
+                                                                source="mcp_tools",
+                                                            )
+
+                                                            log_tool_call(
+                                                                agent_id,
+                                                                tool_name,
+                                                                tool_args,
+                                                                backend_name="gemini",
+                                                            )
+
+                        # Then check automatic_function_calling_history (for MCP tools that were auto-executed)
                         if hasattr(chunk, "automatic_function_calling_history") and chunk.automatic_function_calling_history:
                             for history_item in chunk.automatic_function_calling_history:
                                 if hasattr(history_item, "parts") and history_item.parts is not None:
@@ -1613,127 +625,190 @@ Make your decision and include the JSON at the very end of your response."""
                                                 tool_name = call_data["name"]
                                                 tool_args = call_data["arguments"]
 
-                                                # Check if this is a new call using the tracker
-                                                if mcp_tracker.is_new_call(tool_name, tool_args):
-                                                    # Add to tracker history
-                                                    call_record = mcp_tracker.add_call(tool_name, tool_args)
-
-                                                    # Add to legacy list for compatibility
-                                                    mcp_tools_used.append(
-                                                        {
-                                                            "name": tool_name,
-                                                            "arguments": tool_args,
-                                                            "timestamp": call_record["timestamp"],
-                                                        },
-                                                    )
-
-                                                    # Format timestamp for display
-                                                    timestamp_str = time.strftime(
-                                                        "%H:%M:%S",
-                                                        time.localtime(call_record["timestamp"]),
-                                                    )
-
-                                                    # Yield detailed MCP tool call information
-                                                    yield StreamChunk(
-                                                        type="mcp_status",
-                                                        status="mcp_tool_called",
-                                                        content=f"🔧 MCP Tool Called: {tool_name} at {timestamp_str} with args: {json.dumps(tool_args, indent=2)}",
-                                                        source="mcp_tools",
-                                                    )
-
-                                                    # Log the specific tool call
-                                                    log_tool_call(
-                                                        agent_id,
-                                                        tool_name,
-                                                        tool_args,
-                                                        backend_name="gemini",
-                                                    )
+                                                # DEBUG: Log tool matching (from automatic_function_calling_history)
+                                                logger.info(f"🔍 [DEBUG-AUTO] Function call in history: tool_name='{tool_name}'")
+                                                logger.info(f"🔍 [DEBUG-AUTO] Available MCP tools: {available_mcp_tools}")
+                                                logger.info(f"🔍 [DEBUG-AUTO] Available custom tools: {list(self._custom_tool_names) if has_custom_tools else []}")
+
+                                                # Determine if it's MCP tool or custom tool
+                                                # MCP tools may come from SDK without prefix, so we need to check both
+                                                is_mcp_tool = False
+                                                if has_mcp:
+                                                    if tool_name in available_mcp_tools:
+                                                        is_mcp_tool = True
+                                                    else:
+                                                        # Try matching with MCP prefix format
+                                                        for mcp_tool in available_mcp_tools:
+                                                            if mcp_tool.startswith("mcp__") and mcp_tool.endswith(f"__{tool_name}"):
+                                                                is_mcp_tool = True
+                                                                logger.info(f"🔍 [DEBUG-AUTO] Matched MCP tool: {tool_name} -> {mcp_tool}")
+                                                                break
+
+                                                is_custom_tool = has_custom_tools and tool_name in self._custom_tool_names
+
+                                                logger.info(f"🔍 [DEBUG-AUTO] Tool matching result: is_mcp_tool={is_mcp_tool}, is_custom_tool={is_custom_tool}")
+
+                                                if is_mcp_tool:
+                                                    # Process MCP tool call
+                                                    if mcp_tracker.is_new_call(tool_name, tool_args):
+                                                        call_record = mcp_tracker.add_call(tool_name, tool_args)
+
+                                                        mcp_tools_used.append(
+                                                            {
+                                                                "name": tool_name,
+                                                                "arguments": tool_args,
+                                                                "timestamp": call_record["timestamp"],
+                                                            },
+                                                        )
+
+                                                        timestamp_str = time.strftime(
+                                                            "%H:%M:%S",
+                                                            time.localtime(call_record["timestamp"]),
+                                                        )
+
+                                                        yield StreamChunk(
+                                                            type="mcp_status",
+                                                            status="mcp_tool_called",
+                                                            content=f"🔧 MCP Tool Called: {tool_name} at {timestamp_str} with args: {json.dumps(tool_args, indent=2)}",
+                                                            source="mcp_tools",
+                                                        )
+
+                                                        log_tool_call(
+                                                            agent_id,
+                                                            tool_name,
+                                                            tool_args,
+                                                            backend_name="gemini",
+                                                        )
+
+                                                elif is_custom_tool:
+                                                    # Process custom tool call
+                                                    if custom_tracker.is_new_call(tool_name, tool_args):
+                                                        call_record = custom_tracker.add_call(tool_name, tool_args)
+
+                                                        custom_tools_used.append(
+                                                            {
+                                                                "name": tool_name,
+                                                                "arguments": tool_args,
+                                                                "timestamp": call_record["timestamp"],
+                                                            },
+                                                        )
+
+                                                        timestamp_str = time.strftime(
+                                                            "%H:%M:%S",
+                                                            time.localtime(call_record["timestamp"]),
+                                                        )
+
+                                                        yield StreamChunk(
+                                                            type="custom_tool_status",
+                                                            status="custom_tool_called",
+                                                            content=f"🔧 Custom Tool Called: {tool_name} at {timestamp_str} with args: {json.dumps(tool_args, indent=2)}",
+                                                            source="custom_tools",
+                                                        )
+
+                                                        log_tool_call(
+                                                            agent_id,
+                                                            tool_name,
+                                                            tool_args,
+                                                            backend_name="gemini",
+                                                        )
 
                                         # Check for function_response part
                                         elif hasattr(part, "function_response") and part.function_response:
-                                            # Use MCPResponseExtractor to extract response data
                                             response_data = self.mcp_extractor.extract_function_response(part.function_response)
 
                                             if response_data:
                                                 tool_name = response_data["name"]
                                                 tool_response = response_data["response"]
 
-                                                # Check if this is a new response using the tracker
-                                                if mcp_response_tracker.is_new_response(tool_name, tool_response):
-                                                    # Add to tracker history
-                                                    response_record = mcp_response_tracker.add_response(tool_name, tool_response)
-
-                                                    # Extract text content from CallToolResult
-                                                    response_text = None
-                                                    if isinstance(tool_response, dict) and "result" in tool_response:
-                                                        result = tool_response["result"]
-                                                        # Check if result has content attribute (CallToolResult object)
-                                                        if hasattr(result, "content") and result.content:
-                                                            # Get the first content item (TextContent object)
-                                                            first_content = result.content[0]
-                                                            # Extract the text attribute
-                                                            if hasattr(first_content, "text"):
-                                                                response_text = first_content.text
-
-                                                    # Use extracted text or fallback to string representation
-                                                    if response_text is None:
+                                                # Determine if it's MCP tool or custom tool
+                                                # MCP tools may come from SDK without prefix
+                                                is_mcp_tool = False
+                                                if has_mcp:
+                                                    if tool_name in available_mcp_tools:
+                                                        is_mcp_tool = True
+                                                    else:
+                                                        # Try matching with MCP prefix format
+                                                        for mcp_tool in available_mcp_tools:
+                                                            if mcp_tool.startswith("mcp__") and mcp_tool.endswith(f"__{tool_name}"):
+                                                                is_mcp_tool = True
+                                                                break
+
+                                                is_custom_tool = has_custom_tools and tool_name in self._custom_tool_names
+
+                                                if is_mcp_tool:
+                                                    # Process MCP tool response
+                                                    if mcp_response_tracker.is_new_response(tool_name, tool_response):
+                                                        response_record = mcp_response_tracker.add_response(tool_name, tool_response)
+
+                                                        # Extract text content from CallToolResult
+                                                        response_text = None
+                                                        if isinstance(tool_response, dict) and "result" in tool_response:
+                                                            result = tool_response["result"]
+                                                            if hasattr(result, "content") and result.content:
+                                                                first_content = result.content[0]
+                                                                if hasattr(first_content, "text"):
+                                                                    response_text = first_content.text
+
+                                                        if response_text is None:
+                                                            response_text = str(tool_response)
+
+                                                        timestamp_str = time.strftime(
+                                                            "%H:%M:%S",
+                                                            time.localtime(response_record["timestamp"]),
+                                                        )
+
+                                                        # Format response as JSON if possible
+                                                        formatted_response = format_tool_response_as_json(response_text)
+
+                                                        yield StreamChunk(
+                                                            type="mcp_status",
+                                                            status="mcp_tool_response",
+                                                            content=f"✅ MCP Tool Response from {tool_name} at {timestamp_str}: {formatted_response}",
+                                                            source="mcp_tools",
+                                                        )
+
+                                                        log_backend_activity(
+                                                            "gemini",
+                                                            "MCP tool response received",
+                                                            {
+                                                                "tool_name": tool_name,
+                                                                "response_preview": str(tool_response)[:],
+                                                            },
+                                                            agent_id=agent_id,
+                                                        )
+
+                                                elif is_custom_tool:
+                                                    # Process custom tool response
+                                                    if custom_response_tracker.is_new_response(tool_name, tool_response):
+                                                        response_record = custom_response_tracker.add_response(tool_name, tool_response)
+
+                                                        # Extract text from response
                                                         response_text = str(tool_response)
 
-                                                    # Format timestamp for display
-                                                    timestamp_str = time.strftime(
-                                                        "%H:%M:%S",
-                                                        time.localtime(response_record["timestamp"]),
-                                                    )
-
-                                                    # Yield MCP tool response information
-                                                    yield StreamChunk(
-                                                        type="mcp_status",
-                                                        status="mcp_tool_response",
-                                                        content=f"✅ MCP Tool Response from {tool_name} at {timestamp_str}: {response_text}",
-                                                        source="mcp_tools",
-                                                    )
-
-                                                    # Log the tool response
-                                                    log_backend_activity(
-                                                        "gemini",
-                                                        "MCP tool response received",
-                                                        {
-                                                            "tool_name": tool_name,
-                                                            "response_preview": str(tool_response)[:],
-                                                        },
-                                                        agent_id=agent_id,
-                                                    )
-
-                            # Track successful MCP tool execution (only on first chunk with MCP history)
-                            if not hasattr(self, "_mcp_stream_started"):
-                                self._mcp_tool_successes += 1
-                                self._mcp_stream_started = True
-                                log_backend_activity(
-                                    "gemini",
-                                    "MCP tool call succeeded",
-                                    {"call_number": self._mcp_tool_calls_count},
-                                    agent_id=agent_id,
-                                )
-
-                                # Log MCP tool success as a tool call event
-                                log_tool_call(
-                                    agent_id,
-                                    "mcp_session_tools",
-                                    {
-                                        "session_count": len(mcp_sessions),
-                                        "call_number": self._mcp_tool_calls_count,
-                                    },
-                                    result="success",
-                                    backend_name="gemini",
-                                )
-
-                                # Yield MCP success status as StreamChunk
-                                yield StreamChunk(
-                                    type="mcp_status",
-                                    status="mcp_tools_success",
-                                    content=f"MCP tool call succeeded (call #{self._mcp_tool_calls_count})",
-                                    source="mcp_tools",
-                                )
+                                                        timestamp_str = time.strftime(
+                                                            "%H:%M:%S",
+                                                            time.localtime(response_record["timestamp"]),
+                                                        )
+
+                                                        # Format response as JSON if possible
+                                                        formatted_response = format_tool_response_as_json(response_text)
+
+                                                        yield StreamChunk(
+                                                            type="custom_tool_status",
+                                                            status="custom_tool_response",
+                                                            content=f"✅ Custom Tool Response from {tool_name} at {timestamp_str}: {formatted_response}",
+                                                            source="custom_tools",
+                                                        )
+
+                                                        log_backend_activity(
+                                                            "gemini",
+                                                            "Custom tool response received",
+                                                            {
+                                                                "tool_name": tool_name,
+                                                                "response_preview": str(tool_response),
+                                                            },
+                                                            agent_id=agent_id,
+                                                        )
 
                         # ============================================
                         # 2. Process text content
@@ -1750,24 +825,595 @@ Make your decision and include the JSON at the very end of your response."""
                             log_stream_chunk("backend.gemini", "content", chunk_text, agent_id)
                             yield StreamChunk(type="content", content=chunk_text)
 
+                        # ============================================
+                        # 3. Buffer last chunk with candidates
+                        # ============================================
+                        if hasattr(chunk, "candidates") and chunk.candidates:
+                            last_response_with_candidates = chunk
+
                     # Reset stream tracking
                     if hasattr(self, "_mcp_stream_started"):
                         delattr(self, "_mcp_stream_started")
 
-                    # Add MCP usage indicator with detailed summary using tracker
-                    tools_summary = mcp_tracker.get_summary()
-                    if not tools_summary or tools_summary == "No MCP tools called":
-                        tools_summary = "MCP session completed (no tools explicitly called)"
-                    else:
-                        tools_summary = f"MCP session complete - {tools_summary}"
-
-                    log_stream_chunk("backend.gemini", "mcp_indicator", tools_summary, agent_id)
-                    yield StreamChunk(
-                        type="mcp_status",
-                        status="mcp_session_complete",
-                        content=f"MCP session complete - {tools_summary}",
-                        source="mcp_tools",
-                    )
+                    # ====================================================================
+                    # Tool execution loop: Execute tools until model stops calling them
+                    # ====================================================================
+                    # Note: When automatic_function_calling is disabled, BOTH custom and MCP tools
+                    # need to be manually executed. The model may make multiple rounds of tool calls
+                    # (e.g., call custom tool first, then MCP tool after seeing the result).
+
+                    executed_tool_calls = set()  # Track which tools we've already executed
+                    max_tool_rounds = 10  # Prevent infinite loops
+                    tool_round = 0
+
+                    while tool_round < max_tool_rounds:
+                        # Find new tool calls that haven't been executed yet
+                        new_custom_tools = []
+                        new_mcp_tools = []
+
+                        for tool_call in custom_tools_used:
+                            call_signature = f"custom_{tool_call['name']}_{json.dumps(tool_call['arguments'], sort_keys=True)}"
+                            if call_signature not in executed_tool_calls:
+                                new_custom_tools.append(tool_call)
+                                executed_tool_calls.add(call_signature)
+
+                        for tool_call in mcp_tools_used:
+                            call_signature = f"mcp_{tool_call['name']}_{json.dumps(tool_call['arguments'], sort_keys=True)}"
+                            if call_signature not in executed_tool_calls:
+                                new_mcp_tools.append(tool_call)
+                                executed_tool_calls.add(call_signature)
+
+                        # If no new tools to execute, break the loop
+                        if not new_custom_tools and not new_mcp_tools:
+                            break
+
+                        tool_round += 1
+                        logger.debug(f"[Gemini] Tool execution round {tool_round}: {len(new_custom_tools)} custom, {len(new_mcp_tools)} MCP")
+
+                        # Execute tools and collect results for this round
+                        tool_responses = []
+
+                        # Execute custom tools
+                        for tool_call in new_custom_tools:
+                            tool_name = tool_call["name"]
+                            tool_args = tool_call["arguments"]
+
+                            try:
+                                # Execute the custom tool
+                                result_str = await self._execute_custom_tool(
+                                    {
+                                        "name": tool_name,
+                                        "arguments": json.dumps(tool_args) if isinstance(tool_args, dict) else tool_args,
+                                    },
+                                )
+
+                                # Format result as JSON if possible
+                                formatted_result = format_tool_response_as_json(result_str)
+
+                                # Yield execution status
+                                yield StreamChunk(
+                                    type="custom_tool_status",
+                                    status="custom_tool_executed",
+                                    content=f"✅ Custom Tool Executed: {tool_name} -> {formatted_result}",
+                                    source="custom_tools",
+                                )
+
+                                # Build function response in Gemini format
+                                tool_responses.append(
+                                    {
+                                        "name": tool_name,
+                                        "response": {"result": result_str},
+                                    },
+                                )
+
+                            except Exception as e:
+                                error_msg = f"Error executing custom tool {tool_name}: {str(e)}"
+                                logger.error(error_msg)
+                                yield StreamChunk(
+                                    type="custom_tool_status",
+                                    status="custom_tool_error",
+                                    content=f"❌ {error_msg}",
+                                    source="custom_tools",
+                                )
+                                # Add error response
+                                tool_responses.append(
+                                    {
+                                        "name": tool_name,
+                                        "response": {"error": str(e)},
+                                    },
+                                )
+
+                        # Execute MCP tools manually (since automatic_function_calling is disabled)
+                        for tool_call in new_mcp_tools:
+                            tool_name = tool_call["name"]
+                            tool_args = tool_call["arguments"]
+
+                            try:
+                                # Execute the MCP tool via MCP client
+                                if not self._mcp_client:
+                                    raise RuntimeError("MCP client not initialized")
+
+                                # Convert tool name to prefixed format if needed
+                                # MCP client expects: mcp__server__toolname
+                                # Gemini SDK returns: toolname (without prefix)
+                                prefixed_tool_name = tool_name
+                                if not tool_name.startswith("mcp__"):
+                                    # Find the matching prefixed tool name
+                                    for mcp_tool in available_mcp_tools:
+                                        if mcp_tool.startswith("mcp__") and mcp_tool.endswith(f"__{tool_name}"):
+                                            prefixed_tool_name = mcp_tool
+                                            logger.info(f"🔧 [DEBUG] Converting tool name for execution: {tool_name} -> {prefixed_tool_name}")
+                                            break
+
+                                mcp_result = await self._mcp_client.call_tool(prefixed_tool_name, tool_args)
+
+                                # Extract text from CallToolResult object
+                                result_str = None
+                                if mcp_result:
+                                    if hasattr(mcp_result, "content") and mcp_result.content:
+                                        first_content = mcp_result.content[0]
+                                        if hasattr(first_content, "text"):
+                                            result_str = first_content.text
+
+                                if result_str is None:
+                                    result_str = str(mcp_result) if mcp_result else "None"
+
+                                # Format result as JSON if possible
+                                formatted_result = format_tool_response_as_json(result_str)
+                                result_preview = formatted_result
+
+                                # Yield execution status
+                                yield StreamChunk(
+                                    type="mcp_status",
+                                    status="mcp_tool_executed",
+                                    content=f"✅ MCP Tool Executed: {tool_name} -> {result_preview}{'...' if len(formatted_result) > 200 else ''}",
+                                    source="mcp_tools",
+                                )
+
+                                # Build function response in Gemini format
+                                tool_responses.append(
+                                    {
+                                        "name": tool_name,
+                                        "response": {"result": mcp_result},
+                                    },
+                                )
+
+                            except Exception as e:
+                                error_msg = f"Error executing MCP tool {tool_name}: {str(e)}"
+                                logger.error(error_msg)
+                                yield StreamChunk(
+                                    type="mcp_status",
+                                    status="mcp_tool_error",
+                                    content=f"❌ {error_msg}",
+                                    source="mcp_tools",
+                                )
+                                # Add error response
+                                tool_responses.append(
+                                    {
+                                        "name": tool_name,
+                                        "response": {"error": str(e)},
+                                    },
+                                )
+
+                        # Make continuation call with tool results from this round
+                        if tool_responses:
+                            try:
+                                from google.genai import types
+
+                                # Build conversation history for continuation
+                                # Track all function calls from this round
+                                round_function_calls = new_custom_tools + new_mcp_tools
+
+                                # Build conversation history
+                                conversation_history = []
+
+                                # Add original user content
+                                conversation_history.append(
+                                    types.Content(
+                                        parts=[types.Part(text=full_content)],
+                                        role="user",
+                                    ),
+                                )
+
+                                # Add model's function call response (tools from THIS round)
+                                model_parts = []
+                                for tool_call in round_function_calls:
+                                    model_parts.append(
+                                        types.Part.from_function_call(
+                                            name=tool_call["name"],
+                                            args=tool_call["arguments"],
+                                        ),
+                                    )
+
+                                conversation_history.append(
+                                    types.Content(
+                                        parts=model_parts,
+                                        role="model",
+                                    ),
+                                )
+
+                                # Add function response (as user message with function_response parts)
+                                response_parts = []
+                                for resp in tool_responses:
+                                    response_parts.append(
+                                        types.Part.from_function_response(
+                                            name=resp["name"],
+                                            response=resp["response"],
+                                        ),
+                                    )
+
+                                conversation_history.append(
+                                    types.Content(
+                                        parts=response_parts,
+                                        role="user",
+                                    ),
+                                )
+
+                                # Make continuation call
+                                yield StreamChunk(
+                                    type="custom_tool_status",
+                                    status="continuation_call",
+                                    content=f"🔄 Making continuation call with {len(tool_responses)} tool results...",
+                                    source="custom_tools",
+                                )
+
+                                # Use same session_config as before
+                                continuation_stream = await client.aio.models.generate_content_stream(
+                                    model=model_name,
+                                    contents=conversation_history,
+                                    config=session_config,
+                                )
+
+                                # Process continuation stream (same processing as main stream)
+                                async for chunk in continuation_stream:
+                                    # ============================================
+                                    # Process function calls/responses in continuation
+                                    # ============================================
+                                    # Check for function calls in current chunk's candidates
+                                    if hasattr(chunk, "candidates") and chunk.candidates:
+                                        for candidate in chunk.candidates:
+                                            if hasattr(candidate, "content") and candidate.content:
+                                                if hasattr(candidate.content, "parts") and candidate.content.parts:
+                                                    for part in candidate.content.parts:
+                                                        # Check for function_call part
+                                                        if hasattr(part, "function_call") and part.function_call:
+                                                            call_data = self.mcp_extractor.extract_function_call(part.function_call)
+
+                                                            if call_data:
+                                                                tool_name = call_data["name"]
+                                                                tool_args = call_data["arguments"]
+
+                                                                # Determine if it's MCP tool or custom tool
+                                                                # MCP tools may come from SDK without prefix
+                                                                is_mcp_tool = False
+                                                                if has_mcp:
+                                                                    if tool_name in available_mcp_tools:
+                                                                        is_mcp_tool = True
+                                                                    else:
+                                                                        # Try matching with MCP prefix format
+                                                                        for mcp_tool in available_mcp_tools:
+                                                                            if mcp_tool.startswith("mcp__") and mcp_tool.endswith(f"__{tool_name}"):
+                                                                                is_mcp_tool = True
+                                                                                break
+
+                                                                is_custom_tool = has_custom_tools and tool_name in self._custom_tool_names
+
+                                                                if is_custom_tool:
+                                                                    # Process custom tool call
+                                                                    if custom_tracker.is_new_call(tool_name, tool_args):
+                                                                        call_record = custom_tracker.add_call(tool_name, tool_args)
+
+                                                                        custom_tools_used.append(
+                                                                            {
+                                                                                "name": tool_name,
+                                                                                "arguments": tool_args,
+                                                                                "timestamp": call_record["timestamp"],
+                                                                            },
+                                                                        )
+
+                                                                        timestamp_str = time.strftime(
+                                                                            "%H:%M:%S",
+                                                                            time.localtime(call_record["timestamp"]),
+                                                                        )
+
+                                                                        yield StreamChunk(
+                                                                            type="custom_tool_status",
+                                                                            status="custom_tool_called",
+                                                                            content=f"🔧 Custom Tool Called: {tool_name} at {timestamp_str} with args: {json.dumps(tool_args, indent=2)}",
+                                                                            source="custom_tools",
+                                                                        )
+
+                                                                        log_tool_call(
+                                                                            agent_id,
+                                                                            tool_name,
+                                                                            tool_args,
+                                                                            backend_name="gemini",
+                                                                        )
+                                                                elif is_mcp_tool:
+                                                                    # Process MCP tool call
+                                                                    if mcp_tracker.is_new_call(tool_name, tool_args):
+                                                                        call_record = mcp_tracker.add_call(tool_name, tool_args)
+
+                                                                        mcp_tools_used.append(
+                                                                            {
+                                                                                "name": tool_name,
+                                                                                "arguments": tool_args,
+                                                                                "timestamp": call_record["timestamp"],
+                                                                            },
+                                                                        )
+
+                                                                        timestamp_str = time.strftime(
+                                                                            "%H:%M:%S",
+                                                                            time.localtime(call_record["timestamp"]),
+                                                                        )
+
+                                                                        yield StreamChunk(
+                                                                            type="mcp_status",
+                                                                            status="mcp_tool_called",
+                                                                            content=f"🔧 MCP Tool Called: {tool_name} at {timestamp_str} with args: {json.dumps(tool_args, indent=2)}",
+                                                                            source="mcp_tools",
+                                                                        )
+
+                                                                        log_tool_call(
+                                                                            agent_id,
+                                                                            tool_name,
+                                                                            tool_args,
+                                                                            backend_name="gemini",
+                                                                        )
+
+                                    # Check automatic_function_calling_history (for auto-executed MCP tools)
+                                    if hasattr(chunk, "automatic_function_calling_history") and chunk.automatic_function_calling_history:
+                                        for history_item in chunk.automatic_function_calling_history:
+                                            if hasattr(history_item, "parts") and history_item.parts is not None:
+                                                for part in history_item.parts:
+                                                    # Check for function_call part
+                                                    if hasattr(part, "function_call") and part.function_call:
+                                                        call_data = self.mcp_extractor.extract_function_call(part.function_call)
+
+                                                        if call_data:
+                                                            tool_name = call_data["name"]
+                                                            tool_args = call_data["arguments"]
+
+                                                            # Determine if it's MCP tool or custom tool
+                                                            # MCP tools may come from SDK without prefix
+                                                            is_mcp_tool = False
+                                                            if has_mcp:
+                                                                if tool_name in available_mcp_tools:
+                                                                    is_mcp_tool = True
+                                                                else:
+                                                                    # Try matching with MCP prefix format
+                                                                    for mcp_tool in available_mcp_tools:
+                                                                        if mcp_tool.startswith("mcp__") and mcp_tool.endswith(f"__{tool_name}"):
+                                                                            is_mcp_tool = True
+                                                                            break
+
+                                                            is_custom_tool = has_custom_tools and tool_name in self._custom_tool_names
+
+                                                            if is_mcp_tool:
+                                                                # Process MCP tool call
+                                                                if mcp_tracker.is_new_call(tool_name, tool_args):
+                                                                    call_record = mcp_tracker.add_call(tool_name, tool_args)
+
+                                                                    mcp_tools_used.append(
+                                                                        {
+                                                                            "name": tool_name,
+                                                                            "arguments": tool_args,
+                                                                            "timestamp": call_record["timestamp"],
+                                                                        },
+                                                                    )
+
+                                                                    timestamp_str = time.strftime(
+                                                                        "%H:%M:%S",
+                                                                        time.localtime(call_record["timestamp"]),
+                                                                    )
+
+                                                                    yield StreamChunk(
+                                                                        type="mcp_status",
+                                                                        status="mcp_tool_called",
+                                                                        content=f"🔧 MCP Tool Called: {tool_name} at {timestamp_str} with args: {json.dumps(tool_args, indent=2)}",
+                                                                        source="mcp_tools",
+                                                                    )
+
+                                                                    log_tool_call(
+                                                                        agent_id,
+                                                                        tool_name,
+                                                                        tool_args,
+                                                                        backend_name="gemini",
+                                                                    )
+
+                                                            elif is_custom_tool:
+                                                                # Process custom tool call
+                                                                if custom_tracker.is_new_call(tool_name, tool_args):
+                                                                    call_record = custom_tracker.add_call(tool_name, tool_args)
+
+                                                                    custom_tools_used.append(
+                                                                        {
+                                                                            "name": tool_name,
+                                                                            "arguments": tool_args,
+                                                                            "timestamp": call_record["timestamp"],
+                                                                        },
+                                                                    )
+
+                                                                    timestamp_str = time.strftime(
+                                                                        "%H:%M:%S",
+                                                                        time.localtime(call_record["timestamp"]),
+                                                                    )
+
+                                                                    yield StreamChunk(
+                                                                        type="custom_tool_status",
+                                                                        status="custom_tool_called",
+                                                                        content=f"🔧 Custom Tool Called: {tool_name} at {timestamp_str} with args: {json.dumps(tool_args, indent=2)}",
+                                                                        source="custom_tools",
+                                                                    )
+
+                                                                    log_tool_call(
+                                                                        agent_id,
+                                                                        tool_name,
+                                                                        tool_args,
+                                                                        backend_name="gemini",
+                                                                    )
+
+                                                    # Check for function_response part
+                                                    elif hasattr(part, "function_response") and part.function_response:
+                                                        response_data = self.mcp_extractor.extract_function_response(part.function_response)
+
+                                                        if response_data:
+                                                            tool_name = response_data["name"]
+                                                            tool_response = response_data["response"]
+
+                                                            # Determine if it's MCP tool or custom tool
+                                                            # MCP tools may come from SDK without prefix
+                                                            is_mcp_tool = False
+                                                            if has_mcp:
+                                                                if tool_name in available_mcp_tools:
+                                                                    is_mcp_tool = True
+                                                                else:
+                                                                    # Try matching with MCP prefix format
+                                                                    for mcp_tool in available_mcp_tools:
+                                                                        if mcp_tool.startswith("mcp__") and mcp_tool.endswith(f"__{tool_name}"):
+                                                                            is_mcp_tool = True
+                                                                            break
+
+                                                            is_custom_tool = has_custom_tools and tool_name in self._custom_tool_names
+
+                                                            if is_mcp_tool:
+                                                                # Process MCP tool response
+                                                                if mcp_response_tracker.is_new_response(tool_name, tool_response):
+                                                                    response_record = mcp_response_tracker.add_response(tool_name, tool_response)
+
+                                                                    # Extract text content from CallToolResult
+                                                                    response_text = None
+                                                                    if isinstance(tool_response, dict) and "result" in tool_response:
+                                                                        result = tool_response["result"]
+                                                                        if hasattr(result, "content") and result.content:
+                                                                            first_content = result.content[0]
+                                                                            if hasattr(first_content, "text"):
+                                                                                response_text = first_content.text
+
+                                                                    if response_text is None:
+                                                                        response_text = str(tool_response)
+
+                                                                    timestamp_str = time.strftime(
+                                                                        "%H:%M:%S",
+                                                                        time.localtime(response_record["timestamp"]),
+                                                                    )
+
+                                                                    # Format response as JSON if possible
+                                                                    formatted_response = format_tool_response_as_json(response_text)
+
+                                                                    yield StreamChunk(
+                                                                        type="mcp_status",
+                                                                        status="mcp_tool_response",
+                                                                        content=f"✅ MCP Tool Response from {tool_name} at {timestamp_str}: {formatted_response}",
+                                                                        source="mcp_tools",
+                                                                    )
+
+                                                                    log_backend_activity(
+                                                                        "gemini",
+                                                                        "MCP tool response received",
+                                                                        {
+                                                                            "tool_name": tool_name,
+                                                                            "response_preview": str(tool_response)[:],
+                                                                        },
+                                                                        agent_id=agent_id,
+                                                                    )
+
+                                                            elif is_custom_tool:
+                                                                # Process custom tool response
+                                                                if custom_response_tracker.is_new_response(tool_name, tool_response):
+                                                                    response_record = custom_response_tracker.add_response(tool_name, tool_response)
+
+                                                                    # Extract text from response
+                                                                    response_text = str(tool_response)
+
+                                                                    timestamp_str = time.strftime(
+                                                                        "%H:%M:%S",
+                                                                        time.localtime(response_record["timestamp"]),
+                                                                    )
+
+                                                                    # Format response as JSON if possible
+                                                                    formatted_response = format_tool_response_as_json(response_text)
+
+                                                                    yield StreamChunk(
+                                                                        type="custom_tool_status",
+                                                                        status="custom_tool_response",
+                                                                        content=f"✅ Custom Tool Response from {tool_name} at {timestamp_str}: {formatted_response}",
+                                                                        source="custom_tools",
+                                                                    )
+
+                                                                    log_backend_activity(
+                                                                        "gemini",
+                                                                        "Custom tool response received",
+                                                                        {
+                                                                            "tool_name": tool_name,
+                                                                            "response_preview": str(tool_response),
+                                                                        },
+                                                                        agent_id=agent_id,
+                                                                    )
+
+                                    # ============================================
+                                    # Process text content
+                                    # ============================================
+                                    if hasattr(chunk, "text") and chunk.text:
+                                        chunk_text = chunk.text
+                                        full_content_text += chunk_text
+                                        log_stream_chunk("backend.gemini", "continuation_content", chunk_text, agent_id)
+                                        yield StreamChunk(type="content", content=chunk_text)
+
+                                    # ============================================
+                                    # Buffer last chunk
+                                    # ============================================
+                                    if hasattr(chunk, "candidates") and chunk.candidates:
+                                        last_response_with_candidates = chunk
+
+                            except Exception as e:
+                                error_msg = f"Error in continuation call: {str(e)}"
+                                logger.error(error_msg)
+                                yield StreamChunk(
+                                    type="custom_tool_status",
+                                    status="continuation_error",
+                                    content=f"❌ {error_msg}",
+                                    source="custom_tools",
+                                )
+
+                    # ====================================================================
+                    # Completion phase: Output summary
+                    # ====================================================================
+
+                    # Add MCP usage indicator with detailed summary
+                    if has_mcp:
+                        mcp_summary = mcp_tracker.get_summary()
+                        if not mcp_summary or mcp_summary == "No MCP tools called":
+                            mcp_summary = "MCP session completed (no tools explicitly called)"
+                        else:
+                            mcp_summary = f"MCP session complete - {mcp_summary}"
+
+                        log_stream_chunk("backend.gemini", "mcp_indicator", mcp_summary, agent_id)
+                        yield StreamChunk(
+                            type="mcp_status",
+                            status="mcp_session_complete",
+                            content=mcp_summary,
+                            source="mcp_tools",
+                        )
+
+                    # Add custom tool usage indicator with detailed summary
+                    if has_custom_tools:
+                        custom_summary = custom_tracker.get_summary()
+                        if not custom_summary or custom_summary == "No MCP tools called":
+                            custom_summary = "Custom tools session completed (no tools explicitly called)"
+                        else:
+                            # Replace "MCP tool" with "Custom tool"
+                            custom_summary = custom_summary.replace("MCP tool", "Custom tool")
+                            custom_summary = f"Custom tools session complete - {custom_summary}"
+
+                        log_stream_chunk("backend.gemini", "custom_tools_indicator", custom_summary, agent_id)
+                        yield StreamChunk(
+                            type="custom_tool_status",
+                            status="custom_tools_session_complete",
+                            content=custom_summary,
+                            source="custom_tools",
+                        )
+
                 except (
                     MCPConnectionError,
                     MCPTimeoutError,
@@ -1775,26 +1421,102 @@ Make your decision and include the JSON at the very end of your response."""
                     MCPError,
                     Exception,
                 ) as e:
-                    log_stream_chunk("backend.gemini", "mcp_error", str(e), agent_id)
+                    log_stream_chunk("backend.gemini", "tools_error", str(e), agent_id)
+
+                    # ====================================================================
+                    # Error handling: Distinguish MCP and custom tools errors
+                    # ====================================================================
+
+                    # Determine error type
+                    is_mcp_error = isinstance(e, (MCPConnectionError, MCPTimeoutError, MCPServerError, MCPError))
+                    is_custom_tool_error = not is_mcp_error and using_custom_tools
 
                     # Emit user-friendly error message
-                    async for chunk in self._handle_mcp_error_and_fallback(e):
-                        yield chunk
+                    if is_mcp_error:
+                        async for chunk in self.mcp_manager.handle_mcp_error_and_fallback(e):
+                            yield chunk
+                    elif is_custom_tool_error:
+                        yield StreamChunk(
+                            type="custom_tool_status",
+                            status="custom_tools_error",
+                            content=f"⚠️ [Custom Tools] Error: {str(e)}; falling back to non-custom-tool mode",
+                            source="custom_tools",
+                        )
+                    else:
+                        yield StreamChunk(
+                            type="mcp_status",
+                            status="tools_error",
+                            content=f"⚠️ [Tools] Error: {str(e)}; falling back",
+                            source="tools",
+                        )
 
-                    # Fallback to non-MCP streaming with manual configuration
+                    # Fallback configuration
                     manual_config = dict(config)
-                    if all_tools:
-                        manual_config["tools"] = all_tools
 
-                    # Need to create a new stream for fallback since stream is None
-                    stream = await client.aio.models.generate_content_stream(model=model_name, contents=full_content, config=manual_config)
+                    # Decide fallback configuration based on error type
+                    if is_mcp_error and using_custom_tools:
+                        # MCP error but custom tools available: exclude MCP, keep custom tools
+                        try:
+                            custom_tools_schemas = self._get_custom_tools_schemas()
+                            if custom_tools_schemas:
+                                # Convert to Gemini format using formatter
+                                custom_tools_functions = self.formatter.format_custom_tools(
+                                    custom_tools_schemas,
+                                    return_sdk_objects=True,
+                                )
+                                # Wrap FunctionDeclarations in a Tool object for Gemini SDK
+                                from google.genai import types
+
+                                custom_tool = types.Tool(function_declarations=custom_tools_functions)
+                                manual_config["tools"] = [custom_tool]
+                                logger.info("[Gemini] Fallback: using custom tools only (MCP failed)")
+                            else:
+                                # Custom tools also unavailable, use builtin tools
+                                if all_tools:
+                                    manual_config["tools"] = all_tools
+                                logger.info("[Gemini] Fallback: using builtin tools only (both MCP and custom tools failed)")
+                        except Exception:
+                            if all_tools:
+                                manual_config["tools"] = all_tools
+                            logger.info("[Gemini] Fallback: using builtin tools only (custom tools also failed)")
+
+                    elif is_custom_tool_error and using_sdk_mcp:
+                        # Custom tools error but MCP available: exclude custom tools, keep MCP
+                        try:
+                            if self._mcp_client:
+                                mcp_sessions = self.mcp_manager.get_active_mcp_sessions(
+                                    convert_to_permission_sessions=bool(self.filesystem_manager),
+                                )
+                                if mcp_sessions:
+                                    manual_config["tools"] = mcp_sessions
+                                    logger.info("[Gemini] Fallback: using MCP only (custom tools failed)")
+                                else:
+                                    if all_tools:
+                                        manual_config["tools"] = all_tools
+                                    logger.info("[Gemini] Fallback: using builtin tools only (both custom tools and MCP failed)")
+                        except Exception:
+                            if all_tools:
+                                manual_config["tools"] = all_tools
+                            logger.info("[Gemini] Fallback: using builtin tools only (MCP also failed)")
+
+                    else:
+                        # Both failed or cannot determine: use builtin tools
+                        if all_tools:
+                            manual_config["tools"] = all_tools
+                        logger.info("[Gemini] Fallback: using builtin tools only (all advanced tools failed)")
+
+                    # Create new stream for fallback
+                    stream = await client.aio.models.generate_content_stream(
+                        model=model_name,
+                        contents=full_content,
+                        config=manual_config,
+                    )
 
                     async for chunk in stream:
                         # Process text content
                         if hasattr(chunk, "text") and chunk.text:
                             chunk_text = chunk.text
                             full_content_text += chunk_text
-                            # Log fallback content chunks
                             log_stream_chunk(
                                 "backend.gemini",
                                 "fallback_content",
@@ -1802,30 +1524,46 @@ Make your decision and include the JSON at the very end of your response."""
                                 agent_id,
                             )
                             yield StreamChunk(type="content", content=chunk_text)
-
+                        # Buffer last chunk with candidates for fallback path
+                        if hasattr(chunk, "candidates") and chunk.candidates:
+                            last_response_with_candidates = chunk
             else:
-                # Non-MCP path (existing behavior)
-                # Create stream for non-MCP path
-                stream = await client.aio.models.generate_content_stream(model=model_name, contents=full_content, config=config)
-
-                async for chunk in stream:
-                    # ============================================
-                    # 1. Process text content
-                    # ============================================
-                    if hasattr(chunk, "text") and chunk.text:
-                        chunk_text = chunk.text
-                        full_content_text += chunk_text
-
-                        # Enhanced logging for non-MCP streaming chunks
-                        log_stream_chunk("backend.gemini", "content", chunk_text, agent_id)
-                        log_backend_agent_message(
-                            agent_id,
-                            "RECV",
-                            {"content": chunk_text},
-                            backend_name="gemini",
-                        )
+                # Non-MCP streaming path: execute when MCP is disabled
+                try:
+                    # Use the standard config (with builtin tools if configured)
+                    stream = await client.aio.models.generate_content_stream(
+                        model=model_name,
+                        contents=full_content,
+                        config=config,
+                    )
+
+                    # Process streaming chunks
+                    async for chunk in stream:
+                        # Process text content
+                        if hasattr(chunk, "text") and chunk.text:
+                            chunk_text = chunk.text
+                            full_content_text += chunk_text
+                            log_backend_agent_message(
+                                agent_id,
+                                "RECV",
+                                {"content": chunk_text},
+                                backend_name="gemini",
+                            )
+                            log_stream_chunk("backend.gemini", "content", chunk_text, agent_id)
+                            yield StreamChunk(type="content", content=chunk_text)
+                        # Buffer last chunk with candidates for non-MCP path
+                        if hasattr(chunk, "candidates") and chunk.candidates:
+                            last_response_with_candidates = chunk
 
-                        yield StreamChunk(type="content", content=chunk_text)
+                except Exception as e:
+                    error_msg = f"Non-MCP streaming error: {e}"
+                    log_stream_chunk(
+                        "backend.gemini",
+                        "non_mcp_stream_error",
+                        {"error_type": type(e).__name__, "error_message": str(e)},
+                        agent_id,
+                    )
+                    yield StreamChunk(type="error", error=error_msg)
 
             content = full_content_text
 
@@ -1842,11 +1580,11 @@ Make your decision and include the JSON at the very end of your response."""
                     structured_response = json.loads(content.strip())
                 except json.JSONDecodeError:
                     # Strategy 2: Extract JSON from mixed text content (handles markdown-wrapped JSON)
-                    structured_response = self.extract_structured_response(content)
+                    structured_response = self.formatter.extract_structured_response(content)
 
                 if structured_response and isinstance(structured_response, dict) and "action_type" in structured_response:
                     # Convert to tool calls
-                    tool_calls = self.convert_structured_to_tool_calls(structured_response)
+                    tool_calls = self.formatter.convert_structured_to_tool_calls(structured_response)
                     if tool_calls:
                         tool_calls_detected = tool_calls
                         # Log conversion to tool calls (summary)
@@ -1866,6 +1604,10 @@ Make your decision and include the JSON at the very end of your response."""
                             # Ensure logging does not interrupt flow
                             pass
 
+            # Assign buffered final response (if available) so builtin tool indicators can be emitted
+            if last_response_with_candidates is not None:
+                final_response = last_response_with_candidates
+
             # Process builtin tool results if any tools were used
             if builtin_tools and final_response and hasattr(final_response, "candidates") and final_response.candidates:
                 # Check for grounding or code execution results
@@ -2054,7 +1796,7 @@ Make your decision and include the JSON at the very end of your response."""
             yield StreamChunk(type="error", error=error_msg)
         finally:
             # Cleanup resources
-            await self._cleanup_resources(stream, client)
+            await self.mcp_manager.cleanup_genai_resources(stream, client)
             # Ensure context manager exit for MCP cleanup
             try:
                 await self.__aexit__(None, None, None)
@@ -2132,7 +1874,7 @@ Make your decision and include the JSON at the very end of your response."""
         super().reset_token_usage()
 
     async def cleanup_mcp(self):
-        """Cleanup MCP connections."""
+        """Cleanup MCP connections - override parent class to use Gemini-specific cleanup."""
         if self._mcp_client:
             try:
                 await self._mcp_client.disconnect()
@@ -2148,90 +1890,16 @@ Make your decision and include the JSON at the very end of your response."""
             finally:
                 self._mcp_client = None
                 self._mcp_initialized = False
-
-    async def _cleanup_resources(self, stream, client):
-        """Cleanup google-genai resources to avoid unclosed aiohttp sessions."""
-        # Close stream
-        try:
-            if stream is not None:
-                close_fn = getattr(stream, "aclose", None) or getattr(stream, "close", None)
-                if close_fn is not None:
-                    maybe = close_fn()
-                    if hasattr(maybe, "__await__"):
-                        await maybe
-        except Exception as e:
-            log_backend_activity(
-                "gemini",
-                "Stream cleanup failed",
-                {"error": str(e)},
-                agent_id=self.agent_id,
-            )
-        # Close internal aiohttp session held by google-genai BaseApiClient
-        try:
-            if client is not None:
-                base_client = getattr(client, "_api_client", None)
-                if base_client is not None:
-                    session = getattr(base_client, "_aiohttp_session", None)
-                    if session is not None and hasattr(session, "close"):
-                        if not session.closed:
-                            await session.close()
-                            log_backend_activity(
-                                "gemini",
-                                "Closed google-genai aiohttp session",
-                                {},
-                                agent_id=self.agent_id,
-                            )
-                        base_client._aiohttp_session = None
-                        # Yield control to allow connector cleanup
-                        await asyncio.sleep(0)
-        except Exception as e:
-            log_backend_activity(
-                "gemini",
-                "Failed to close google-genai aiohttp session",
-                {"error": str(e)},
-                agent_id=self.agent_id,
-            )
-        # Close internal async transport if exposed
-        try:
-            if client is not None and hasattr(client, "aio") and client.aio is not None:
-                aio_obj = client.aio
-                for method_name in ("close", "stop"):
-                    method = getattr(aio_obj, method_name, None)
-                    if method:
-                        maybe = method()
-                        if hasattr(maybe, "__await__"):
-                            await maybe
-                        break
-        except Exception as e:
-            log_backend_activity(
-                "gemini",
-                "Client AIO cleanup failed",
-                {"error": str(e)},
-                agent_id=self.agent_id,
-            )
-
-        # Close client
-        try:
-            if client is not None:
-                for method_name in ("aclose", "close"):
-                    method = getattr(client, method_name, None)
-                    if method:
-                        maybe = method()
-                        if hasattr(maybe, "__await__"):
-                            await maybe
-                        break
-        except Exception as e:
-            log_backend_activity(
-                "gemini",
-                "Client cleanup failed",
-                {"error": str(e)},
-                agent_id=self.agent_id,
-            )
+                # Also clear parent class attributes if they exist (for compatibility)
+                if hasattr(self, "_mcp_functions"):
+                    self._mcp_functions.clear()
+                if hasattr(self, "_mcp_function_names"):
+                    self._mcp_function_names.clear()
 
     async def __aenter__(self) -> "GeminiBackend":
         """Async context manager entry."""
         try:
-            await self._setup_mcp_tools(agent_id=self.agent_id)
+            await self.mcp_manager.setup_mcp_tools(agent_id=self.agent_id)
         except Exception as e:
             log_backend_activity(
                 "gemini",