Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

Preserve DeepSeek cache prefixes across tool turns (#1126)

Ali Khokhar8d7f5605890c
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 109cc5f5..d9642f73 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -569,7 +569,12 @@ Ollama's standard `reasoning` delta and history field are profile data rather
than a specialized adapter. DeepSeek intentionally uses its
OpenAI-compatible Chat Completions endpoint because that is the endpoint that
reports prompt-cache hit/miss counters; the provider maps those counters back
-into Anthropic usage fields for Claude-compatible clients. Cloudflare uses its
+into Anthropic usage fields for Claude-compatible clients. DeepSeek reasoning
+history is serialized per assistant turn: non-tool reasoning is omitted from
+its first replay, while tool-call reasoning is retained independently of the
+next generation's thinking mode. Append-only conversations therefore keep an
+identical message prefix without violating DeepSeek's tool-call replay contract.
+Cloudflare uses its
account-scoped Workers AI OpenAI-compatible Chat Completions endpoint for
`@cf/...` model IDs, while account ID composition, model search, and
Cloudflare-specific reasoning deltas stay in the Cloudflare provider client.
diff --git a/pyproject.toml b/pyproject.toml
index 07b2bd85..ff1da3ca 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "4.6.3"
+version = "4.6.4"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/src/free_claude_code/providers/deepseek/compat.py b/src/free_claude_code/providers/deepseek/compat.py
index a6248a8c..b0b28c08 100644
--- a/src/free_claude_code/providers/deepseek/compat.py
+++ b/src/free_claude_code/providers/deepseek/compat.py
@@ -55,7 +55,7 @@ def build_deepseek_request_body(
_downgrade_forced_tool_choice(data)
has_tool_history = _has_tool_history(data)
- has_replayable_tool_thinking = _has_replayable_tool_thinking(data)
+ has_replayable_tool_thinking = _all_tool_calls_have_replayable_thinking(data)
unsafe_tool_followup = has_tool_history and not has_replayable_tool_thinking
effective_thinking_enabled = thinking_enabled and not unsafe_tool_followup
if thinking_enabled:
@@ -87,16 +87,14 @@ def build_deepseek_request_body(
if "messages" in data:
data["messages"] = _normalize_tool_result_content(
- sanitize_deepseek_messages_for_openai(
- data["messages"],
- thinking_enabled=effective_thinking_enabled,
- )
+ sanitize_deepseek_messages_for_openai(data["messages"])
)
sanitized_request = MessagesRequest.model_validate(data)
body = build_openai_chat_request_body(
sanitized_request,
thinking_enabled=effective_thinking_enabled,
+ reasoning_history_enabled=True,
policy=_REQUEST_POLICY,
postprocessors=(_apply_deepseek_chat_extras,),
)
@@ -112,10 +110,8 @@ def build_deepseek_request_body(
return body
-def sanitize_deepseek_messages_for_openai(
- messages: Any, *, thinking_enabled: bool
-) -> Any:
- """Filter assistant content before converting to DeepSeek Chat Completions."""
+def sanitize_deepseek_messages_for_openai(messages: Any) -> Any:
+ """Keep only DeepSeek-required reasoning history on assistant tool calls."""
if not isinstance(messages, list):
return messages
@@ -127,29 +123,26 @@ def sanitize_deepseek_messages_for_openai(
if message.get("role") != "assistant":
sanitized.append(message)
continue
+ replay_tool_reasoning = _assistant_has_tool_use(message)
+ new_msg = dict(message)
+ if not replay_tool_reasoning:
+ new_msg.pop("reasoning_content", None)
content = message.get("content")
if not isinstance(content, list):
- sanitized.append(message)
+ sanitized.append(new_msg)
continue
- if not thinking_enabled:
- filtered = [
- block
- for block in content
- if not (
- isinstance(block, dict)
- and block.get("type") in ("thinking", "redacted_thinking")
- )
- ]
- else:
- filtered = [
- block
- for block in content
- if not (
- isinstance(block, dict) and block.get("type") == "redacted_thinking"
+ filtered = [
+ block
+ for block in content
+ if not (
+ isinstance(block, dict)
+ and (
+ block.get("type") == "redacted_thinking"
+ or (block.get("type") == "thinking" and not replay_tool_reasoning)
)
- ]
- new_msg = dict(message)
+ )
+ ]
new_msg["content"] = filtered or ""
sanitized.append(new_msg)
return sanitized
@@ -314,6 +307,15 @@ def _has_replayable_thinking_before_tool_use(message: Mapping[str, Any]) -> bool
return False
+def _assistant_has_tool_use(message: Mapping[str, Any]) -> bool:
+ if message.get("role") != "assistant":
+ return False
+ content = message.get("content")
+ return isinstance(content, list) and any(
+ isinstance(block, dict) and block.get("type") == "tool_use" for block in content
+ )
+
+
def _has_tool_history(data: dict[str, Any]) -> bool:
for message in data.get("messages") or ():
if isinstance(message, Mapping) and _has_tool_history_blocks(message):
@@ -321,13 +323,15 @@ def _has_tool_history(data: dict[str, Any]) -> bool:
return False
-def _has_replayable_tool_thinking(data: dict[str, Any]) -> bool:
+def _all_tool_calls_have_replayable_thinking(data: dict[str, Any]) -> bool:
+ found_tool_call = False
for message in data.get("messages") or ():
- if isinstance(message, Mapping) and _has_replayable_thinking_before_tool_use(
- message
- ):
- return True
- return False
+ if not isinstance(message, Mapping) or not _assistant_has_tool_use(message):
+ continue
+ found_tool_call = True
+ if not _has_replayable_thinking_before_tool_use(message):
+ return False
+ return found_tool_call
def _remove_deepseek_thinking_hints(data: dict[str, Any]) -> None:
diff --git a/src/free_claude_code/providers/openai_chat/request_policy.py b/src/free_claude_code/providers/openai_chat/request_policy.py
index 87521391..1d67fc3d 100644
--- a/src/free_claude_code/providers/openai_chat/request_policy.py
+++ b/src/free_claude_code/providers/openai_chat/request_policy.py
@@ -37,6 +37,7 @@ def build_openai_chat_request_body(
request_data: MessagesRequest,
*,
thinking_enabled: bool,
+ reasoning_history_enabled: bool | None = None,
policy: OpenAIChatRequestPolicy,
postprocessors: Iterable[OpenAIChatPostprocessor] = (),
) -> dict[str, Any]:
@@ -48,7 +49,9 @@ def build_openai_chat_request_body(
len(request_data.messages),
)
try:
- if not thinking_enabled:
+ if reasoning_history_enabled is None:
+ reasoning_history_enabled = thinking_enabled
+ if not reasoning_history_enabled:
reasoning_replay = ReasoningReplayMode.DISABLED
else:
reasoning_replay = (
diff --git a/tests/providers/test_deepseek.py b/tests/providers/test_deepseek.py
index d074857b..2cfe68b7 100644
--- a/tests/providers/test_deepseek.py
+++ b/tests/providers/test_deepseek.py
@@ -1,10 +1,13 @@
"""Tests for DeepSeek OpenAI-compatible Chat Completions provider."""
+import json
import logging
from types import SimpleNamespace
from unittest.mock import AsyncMock, patch
+import httpx
import pytest
+from openai import AsyncOpenAI
from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
@@ -37,6 +40,36 @@ def deepseek_provider(deepseek_config):
return DeepSeekProvider(deepseek_config, rate_limiter=passthrough_rate_limiter())
+async def _capture_openai_wire_body(body: dict) -> dict:
+ captured: list[dict] = []
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ payload = json.loads(request.content)
+ assert isinstance(payload, dict)
+ captured.append(payload)
+ return httpx.Response(
+ 200,
+ headers={"content-type": "text/event-stream"},
+ text="data: [DONE]\n\n",
+ )
+
+ http_client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
+ client = AsyncOpenAI(
+ api_key="test",
+ base_url="https://deepseek.invalid",
+ http_client=http_client,
+ max_retries=0,
+ )
+ try:
+ stream = await client.chat.completions.create(**body, stream=True)
+ await stream.close()
+ finally:
+ await client.close()
+
+ assert len(captured) == 1
+ return captured[0]
+
+
def test_default_base_url_alias():
assert DEEPSEEK_DEFAULT_BASE == "https://api.deepseek.com"
@@ -177,7 +210,7 @@ def test_build_request_body_respects_global_thinking_disable():
assert "stream_options" not in body
-def test_preserve_unsigned_thinking_when_thinking_on(deepseek_provider):
+def test_non_tool_thinking_is_omitted_from_first_replay(deepseek_provider):
request = MessagesRequest.model_validate(
{
"model": "m",
@@ -197,8 +230,7 @@ def test_preserve_unsigned_thinking_when_thinking_on(deepseek_provider):
}
)
body = deepseek_provider._build_request_body(request)
- assert body["messages"][0]["content"] == "out"
- assert body["messages"][0]["reasoning_content"] == "plain"
+ assert body["messages"][0] == {"role": "assistant", "content": "out"}
def test_strip_redacted_thinking_when_thinking_on(deepseek_provider):
@@ -484,6 +516,53 @@ def test_thinking_off_strips_thinking_history():
assert "sec" not in str(body["messages"])
+def test_thinking_off_still_replays_required_tool_reasoning():
+ provider = DeepSeekProvider(
+ ProviderConfig(
+ api_key="k",
+ base_url=DEEPSEEK_DEFAULT_BASE,
+ rate_limit=1,
+ rate_window=1,
+ enable_thinking=False,
+ ),
+ rate_limiter=passthrough_rate_limiter(),
+ )
+ request = MessagesRequest.model_validate(
+ {
+ "model": "m",
+ "messages": [
+ {
+ "role": "assistant",
+ "content": [
+ {"type": "thinking", "thinking": "required"},
+ {
+ "type": "tool_use",
+ "id": "t1",
+ "name": "Read",
+ "input": {"file_path": "x"},
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "t1",
+ "content": "ok",
+ }
+ ],
+ },
+ ],
+ }
+ )
+
+ body = provider._build_request_body(request)
+
+ assert "extra_body" not in body
+ assert body["messages"][0]["reasoning_content"] == "required"
+
+
def test_passthrough_tool_use_and_result(deepseek_provider):
request = MessagesRequest.model_validate(
{
@@ -630,7 +709,7 @@ def test_preflight_rejects_server_tool_result_blocks():
provider.preflight_stream(request)
-def test_reasoning_content_replayed_to_openai_chat(deepseek_provider):
+def test_non_tool_top_level_reasoning_is_not_replayed(deepseek_provider):
request = MessagesRequest(
model="m",
messages=[
@@ -642,7 +721,131 @@ def test_reasoning_content_replayed_to_openai_chat(deepseek_provider):
],
)
body = deepseek_provider._build_request_body(request)
- assert body["messages"][0]["reasoning_content"] == "r"
+ assert body["messages"][0] == {"role": "assistant", "content": "hi"}
+
+
+def test_tool_call_top_level_reasoning_is_replayed(deepseek_provider):
+ request = MessagesRequest.model_validate(
+ {
+ "model": "m",
+ "messages": [
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "tool_use",
+ "id": "t1",
+ "name": "Read",
+ "input": {"file_path": "x"},
+ }
+ ],
+ "reasoning_content": "required",
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "t1",
+ "content": "ok",
+ }
+ ],
+ },
+ ],
+ }
+ )
+
+ body = deepseek_provider._build_request_body(request)
+
+ assert body["messages"][0]["reasoning_content"] == "required"
+
+
+async def test_wire_messages_keep_prefix_across_tool_thinking_fallback(
+ deepseek_provider,
+):
+ prefix_messages = [
+ {"role": "user", "content": "first"},
+ {
+ "role": "assistant",
+ "content": [
+ {"type": "thinking", "thinking": "ordinary reasoning"},
+ {"type": "text", "text": "answer"},
+ ],
+ },
+ {"role": "user", "content": "use the first tool"},
+ {
+ "role": "assistant",
+ "content": [
+ {"type": "thinking", "thinking": "required tool reasoning"},
+ {
+ "type": "tool_use",
+ "id": "t1",
+ "name": "Read",
+ "input": {"file_path": "one"},
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "t1",
+ "content": "one",
+ }
+ ],
+ },
+ {"role": "user", "content": "use the second tool"},
+ ]
+ continued_messages = [
+ *prefix_messages,
+ {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "tool_use",
+ "id": "t2",
+ "name": "Read",
+ "input": {"file_path": "two"},
+ }
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "t2",
+ "content": "two",
+ }
+ ],
+ },
+ ]
+
+ def build(messages: list[dict]) -> dict:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "deepseek-v4-pro",
+ "messages": messages,
+ "thinking": {"type": "enabled"},
+ }
+ )
+ return deepseek_provider._build_request_body(request)
+
+ first_wire = await _capture_openai_wire_body(build(prefix_messages))
+ continued_wire = await _capture_openai_wire_body(build(continued_messages))
+ first_messages = first_wire["messages"]
+ continued = continued_wire["messages"]
+
+ assert continued[: len(first_messages)] == first_messages
+ assistant_messages = [
+ message for message in first_messages if message["role"] == "assistant"
+ ]
+ assert "reasoning_content" not in assistant_messages[0]
+ assert assistant_messages[1]["reasoning_content"] == "required tool reasoning"
+ assert first_wire["thinking"] == {"type": "enabled"}
+ assert "thinking" not in continued_wire
@pytest.mark.asyncio
diff --git a/uv.lock b/uv.lock
index 57b3e703..628fe0fe 100644
--- a/uv.lock
+++ b/uv.lock
@@ -561,7 +561,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "4.6.3"
+version = "4.6.4"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },