fix: preserve Gemini thought_signature in LiteLLM multi-turn tool calls

[giulio-leone]

Issue

Closes #1764

Description

When using Gemini thinking models (e.g., gemini-2.5-flash, gemini-3-flash) through the LiteLLM model provider, multi-turn conversations with tool calls fail with:

function call 'current_time' in the 2. content block is missing a thought_signature

Root Cause

Gemini thinking models require a thought_signature on each function call in multi-turn conversations. LiteLLM encodes this signature into the tool call ID using a __thought__ separator (e.g., call_abc__thought__base64sig). However, Strands' OpenAIModel.format_chunk() passes the encoded ID through without extracting the signature into the reasoningSignature field that the streaming layer already supports.

While the encoded ID survives the round-trip in simple cases, the signature must also be explicitly stored in reasoningSignature so that:

1. The streaming infrastructure can properly track it through content block lifecycle
2. The signature can be re-encoded into the tool call ID even when the ID is cleaned or regenerated
3. provider_specific_fields.thought_signature (an alternative LiteLLM transport) is also captured

Changes

src/strands/models/litellm.py:

• Override format_chunk to detect __thought__ in tool call IDs and/or provider_specific_fields.thought_signature, extracting the signature into reasoningSignature on the contentBlockStart event
• Override format_request_message_tool_call to re-encode reasoningSignature back into the tool call ID when not already present, ensuring LiteLLM can reconstruct the Gemini-native format

tests/strands/models/test_litellm.py:

• 7 new unit tests covering: extraction from encoded ID, extraction from provider_specific_fields, no-signature passthrough, signature encoding, double-encode prevention, and full round-trip preservation

Checklist

• I've read CONTRIBUTING.md
• I've updated or added tests to cover changes
• I've verified all existing tests pass (48/48)
• This change is backward compatible (no breaking changes)

⚠️ This reopens #1888 which was accidentally closed due to fork deletion.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[opieter-aws]

/strands review

[github-actions]

Assessment: Comment

This is a well-understood bugfix that correctly addresses the missing thought_signature preservation for Gemini thinking models via LiteLLM. The approach aligns well with the existing pattern used by the native Gemini provider (gemini.py), and the round-trip test demonstrates the fix works end-to-end.

Review Details

• Unrelated changes: The PR includes a pyproject.toml dependency bound change (litellm <=1.82.6 → <2.0.0) and a tests_integ/conftest.py change (adding COHERE_API_KEY) that are unrelated to the thought_signature fix and should be split into separate PRs.
• Code organization: The thought signature extraction block in format_chunk is ~30 lines and could benefit from extraction into a private helper method for readability and testability.
• Test coverage gap: The function-level provider_specific_fields extraction path (line 295) lacks a dedicated test — all three signature sources should have coverage.
• Documentation: No public API changes — no docs PR needed.

The core fix logic is sound and the test suite covers the key scenarios well.

[opieter-aws]

@giulio-leone thanks for the PR! The review agent left some comments which would be good to address. Can you please check them and lint and rebase to pass the failing CI?

[github-actions]

Assessment: Approve

All three issues from the previous review have been addressed cleanly. The _extract_thought_signature helper is well-structured with clear priority ordering and early returns, and the function-level PSF test fills the coverage gap. Only one minor inconsistency remains (decorator ordering).

Review Details

• Previous feedback: All 3 prior comments addressed — extraction refactored to @staticmethod helper, function-level PSF test added, fallback comment reworded.
• New finding: Minor decorator order inconsistency (@classmethod @override vs file convention @override @classmethod) — non-blocking.
• Rebase note: Branch is behind main. When rebasing, ensure the litellm<=1.82.6 security pin from fix: CRITICAL: Hard pin litellm<=1.82.6 to mitigate supply chain attack #1961 is preserved (do not revert to <2.0.0).

Clean fix with solid test coverage. Nice work addressing the review feedback.

[github-actions]

Assessment: Approve

All feedback from the previous two review rounds has been addressed. No new issues found.

Review Details

• Prior feedback (4 items): All resolved — extraction helper refactored to @staticmethod, function-level PSF test added, fallback comment reworded, decorator order fixed.
• Code quality: Clean implementation with defensive typing, clear priority ordering in _extract_thought_signature, and proper delegation to the parent OpenAIModel.
• Data flow: Verified the full round-trip: format_chunk extracts signature → streaming layer preserves reasoningSignature → format_request_message_tool_call re-encodes it → tool result IDs match via preserved toolUseId.
• Testing: 8 tests covering all extraction paths, encoding/decoding, double-encode prevention, and end-to-end round-trip. Codecov confirms full coverage.
• Documentation: Bugfix with no public API changes — no docs PR needed.