Is there an existing issue for this?

• I have searched the existing issues.

Which plugins are affected?

firebase_ai

Which platforms are affected?

Android, iOS, Web

Description

FinishReason.parseValue() in api.dart throws FormatException when Gemini returns UNEXPECTED_TOOL_CALL as a finish reason. This is a new finish reason from the Gemini API that isn't in the SDK's enum.

static FinishReason parseValue(Object jsonObject) {
  return switch (jsonObject) {
    'STOP' => FinishReason.stop,
    'MAX_TOKENS' => FinishReason.maxTokens,
    // ... other cases
    'MALFORMED_FUNCTION_CALL' => FinishReason.malformedFunctionCall,
    _ => throw FormatException('Unhandled FinishReason format', jsonObject), // <-- crashes here
  };
}

This is the same pattern as #17812 (MALFORMED_FUNCTION_CALL was missing and was added). UNEXPECTED_TOOL_CALL now needs the same treatment.

Impact

• The FormatException is thrown during stream parsing, so the entire response is lost — including any valid text or tool call data the model returned
• This is a widespread Gemini model behavior affecting multiple SDKs (Python, Java, JS, Go — see references below)
• gemini-3-flash-preview and gemini-2.5-flash are commonly affected
• The Java SDK (googleapis/java-genai) has already fixed this: Exception in Chat.sendMessage when model replies with UNEXPECTED_TOOL_CALL googleapis/java-genai#466

Suggested Fix

Add UNEXPECTED_TOOL_CALL to the FinishReason enum and parseValue switch:

enum FinishReason {
  // ... existing values
  malformedFunctionCall('MALFORMED_FUNCTION_CALL'),
  unexpectedToolCall('UNEXPECTED_TOOL_CALL'),  // <-- add this
  other('OTHER');

Or better: map unknown finish reasons to FinishReason.other instead of throwing, to be forward-compatible with future Gemini API additions:

_ => FinishReason.other,  // instead of throw FormatException

References

• Exception in Chat.sendMessage when model replies with UNEXPECTED_TOOL_CALL googleapis/java-genai#466 (fixed)
• automatic_function_calling config persists across requests, causing UNEXPECTED_TOOL_CALL when tools=None googleapis/python-genai#1818
• Gemini 2.5-flash-lite stops with UNEXPECTED_TOOL_CALL, even if no tools were actually passed langchain-ai/langchainjs#8589
• Gemini 3 with UNEXPECTED_TOOL_CALL causing missing thought_signature vercel/ai#10721
• [Bug]: APIConnectionError has unexpected kwarg 'response' on Gemini UNEXPECTED_TOOL_CALL BerriAI/litellm#18918

Reproducing the issue

1. Use gemini-3-flash-preview with function calling declarations
2. Send a multi-turn conversation with 40+ prompt parts
3. The model occasionally returns UNEXPECTED_TOOL_CALL finish reason
4. SDK throws FormatException: Unhandled FinishReason format and the response is lost

Firebase AI SDK version

3.7.0 (also confirmed missing in 3.9.0 and 3.10.0)