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 gateway model identity in Anthropic responses (#1270)

Ali Khokhar8696e132e5a2
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index e2768d33..236c4f1c 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -498,6 +498,13 @@ exact client token budget without guessing provider behavior. `ResolvedModel`
owns the selected route and preference; `RoutedMessagesRequest` owns the final
request-scoped policy passed to execution.
+Routing keeps model identity split at the application boundary. The routed
+request carries the provider model sent upstream, while
+`ResolvedModel.original_model` remains the stable gateway model exposed in
+Anthropic responses and traces. `ProviderExecutor` passes both identities
+explicitly; providers, local optimizations, and local server tools must never
+publish the private upstream model as the response model.
+
`GET /v1/models` advertises:
- configured provider model refs;
diff --git a/pyproject.toml b/pyproject.toml
index a8325eb8..e16033a3 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "4.12.9"
+version = "4.12.10"
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/api/handlers/messages.py b/src/free_claude_code/api/handlers/messages.py
index 840cb574..36efaf74 100644
--- a/src/free_claude_code/api/handlers/messages.py
+++ b/src/free_claude_code/api/handlers/messages.py
@@ -277,7 +277,7 @@ class MessagesHandler:
stage="routing",
event="free_claude_code.api.optimization.safety_classifier_no_thinking",
source="api",
- model=routed.request.model,
+ model=routed.resolved.original_model,
changed=changed,
)
if not changed:
@@ -308,7 +308,7 @@ class MessagesHandler:
stage="routing",
event="free_claude_code.api.optimization.web_server_tool",
source="api",
- model=routed.request.model,
+ model=routed.resolved.original_model,
)
egress = WebFetchEgressPolicy(
allow_private_network_targets=self._settings.web_fetch_allow_private_networks,
@@ -321,6 +321,7 @@ class MessagesHandler:
routed.request,
input_tokens=input_tokens,
web_fetch_egress=egress,
+ response_model=routed.resolved.original_model,
verbose_client_errors=self._settings.log_api_error_tracebacks,
),
)
@@ -328,14 +329,18 @@ class MessagesHandler:
def _intercept_local_optimization(
self, routed: RoutedMessagesRequest
) -> _MessagesResult | None:
- optimized = try_optimizations(routed.request, self._settings)
+ optimized = try_optimizations(
+ routed.request,
+ self._settings,
+ response_model=routed.resolved.original_model,
+ )
if optimized is None:
return None
trace_event(
stage="routing",
event="free_claude_code.api.optimization.short_circuit",
source="api",
- model=routed.request.model,
+ model=routed.resolved.original_model,
)
return _MessagesCompleteResult(optimized)
diff --git a/src/free_claude_code/api/handlers/token_count.py b/src/free_claude_code/api/handlers/token_count.py
index 3ee838d5..3e5e05df 100644
--- a/src/free_claude_code/api/handlers/token_count.py
+++ b/src/free_claude_code/api/handlers/token_count.py
@@ -58,8 +58,10 @@ class TokenCountHandler:
provider_id=routed.resolved.provider_id,
provider_model=routed.resolved.provider_model,
provider_model_ref=routed.resolved.provider_model_ref,
- gateway_model=routed.request.model,
+ gateway_model=routed.resolved.original_model,
)
+ request_snapshot = anthropic_request_snapshot(routed.request)
+ request_snapshot["model"] = routed.resolved.original_model
trace_event(
stage="ingress",
event="free_claude_code.api.count_tokens.completed",
@@ -67,7 +69,7 @@ class TokenCountHandler:
request_id=request_id,
message_count=len(routed.request.messages),
input_tokens=tokens,
- snapshot=anthropic_request_snapshot(routed.request),
+ snapshot=request_snapshot,
)
return TokenCountResponse(input_tokens=tokens)
except ApplicationError:
diff --git a/src/free_claude_code/api/optimization_handlers.py b/src/free_claude_code/api/optimization_handlers.py
index 452dadcb..94e514d8 100644
--- a/src/free_claude_code/api/optimization_handlers.py
+++ b/src/free_claude_code/api/optimization_handlers.py
@@ -147,11 +147,16 @@ OPTIMIZATION_HANDLERS = [
def try_optimizations(
- request_data: MessagesRequest, settings: Settings
+ request_data: MessagesRequest,
+ settings: Settings,
+ *,
+ response_model: str | None = None,
) -> MessagesResponse | None:
"""Run optimization handlers in order. Returns first match or None."""
for handler in OPTIMIZATION_HANDLERS:
result = handler(request_data, settings)
if result is not None:
- return result
+ if response_model is None:
+ return result
+ return result.model_copy(update={"model": response_model})
return None
diff --git a/src/free_claude_code/api/web_tools/streaming.py b/src/free_claude_code/api/web_tools/streaming.py
index 3885e624..ddd3392b 100644
--- a/src/free_claude_code/api/web_tools/streaming.py
+++ b/src/free_claude_code/api/web_tools/streaming.py
@@ -40,6 +40,7 @@ async def stream_web_server_tool_response(
input_tokens: int,
*,
web_fetch_egress: WebFetchEgressPolicy,
+ response_model: str | None = None,
verbose_client_errors: bool = False,
) -> AsyncIterator[str]:
"""Stream a minimal Anthropic-shaped turn for forced `web_search` / `web_fetch` (local fallback).
@@ -71,6 +72,7 @@ async def stream_web_server_tool_response(
"web_fetch": WEB_FETCH_TOOL_ERROR,
}
+ wire_model = request.model if response_model is None else response_model
yield format_sse_event(
"message_start",
{
@@ -80,7 +82,7 @@ async def stream_web_server_tool_response(
"type": "message",
"role": "assistant",
"content": [],
- "model": request.model,
+ "model": wire_model,
"stop_reason": None,
"stop_sequence": None,
"usage": {"input_tokens": input_tokens, "output_tokens": 1},
diff --git a/src/free_claude_code/application/execution.py b/src/free_claude_code/application/execution.py
index c7ac07b5..aaf8c07f 100644
--- a/src/free_claude_code/application/execution.py
+++ b/src/free_claude_code/application/execution.py
@@ -61,6 +61,7 @@ class ProviderExecutor:
reasoning=routed.reasoning,
)
+ gateway_model = routed.resolved.original_model
route_trace: dict[str, object] = {
"stage": "routing",
"event": "free_claude_code.api.route.resolved",
@@ -69,7 +70,7 @@ class ProviderExecutor:
"provider_id": routed.resolved.provider_id,
"provider_model": routed.resolved.provider_model,
"provider_model_ref": routed.resolved.provider_model_ref,
- "gateway_model": routed.request.model,
+ "gateway_model": gateway_model,
"reasoning_control": routed.reasoning.control.value,
"reasoning_effort": (
routed.reasoning.effort.value
@@ -84,6 +85,8 @@ class ProviderExecutor:
route_trace["generation_id"] = self._generation_id
trace_event(**route_trace)
+ request_snapshot = anthropic_request_snapshot(routed.request)
+ request_snapshot["model"] = gateway_model
trace_event(
stage="ingress",
event=(
@@ -93,7 +96,7 @@ class ProviderExecutor:
),
source="api",
message_count=len(routed.request.messages),
- snapshot=anthropic_request_snapshot(routed.request),
+ snapshot=request_snapshot,
request_id=request_id,
)
@@ -113,6 +116,7 @@ class ProviderExecutor:
routed.request,
input_tokens=input_tokens,
request_id=request_id,
+ response_model=gateway_model,
reasoning=routed.reasoning,
)
async for chunk in provider_stream:
@@ -129,7 +133,7 @@ class ProviderExecutor:
stream_trace: dict[str, object] = {
"request_id": request_id,
"provider_id": routed.resolved.provider_id,
- "gateway_model": routed.request.model,
+ "gateway_model": gateway_model,
}
if self._generation_id is not None:
stream_trace["generation_id"] = self._generation_id
diff --git a/src/free_claude_code/application/ports.py b/src/free_claude_code/application/ports.py
index 0b6063f1..5d810b32 100644
--- a/src/free_claude_code/application/ports.py
+++ b/src/free_claude_code/application/ports.py
@@ -27,6 +27,7 @@ class ProviderPort(Protocol):
*,
input_tokens: int,
request_id: str,
+ response_model: str,
reasoning: ReasoningPolicy,
) -> AsyncIterator[str]: ...
diff --git a/src/free_claude_code/providers/base.py b/src/free_claude_code/providers/base.py
index 246c1be2..0abd9825 100644
--- a/src/free_claude_code/providers/base.py
+++ b/src/free_claude_code/providers/base.py
@@ -111,6 +111,7 @@ class BaseProvider(ABC):
input_tokens: int = 0,
*,
request_id: str | None = None,
+ response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
) -> AsyncIterator[str]:
"""Stream response in Anthropic SSE format."""
diff --git a/src/free_claude_code/providers/openai_chat/provider.py b/src/free_claude_code/providers/openai_chat/provider.py
index 606a2d3e..3f994f4f 100644
--- a/src/free_claude_code/providers/openai_chat/provider.py
+++ b/src/free_claude_code/providers/openai_chat/provider.py
@@ -317,6 +317,7 @@ class OpenAIChatProvider(BaseProvider):
input_tokens: int = 0,
*,
request_id: str | None = None,
+ response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
) -> AsyncIterator[str]:
"""Stream response in Anthropic SSE format."""
@@ -325,6 +326,7 @@ class OpenAIChatProvider(BaseProvider):
request=request,
input_tokens=input_tokens,
request_id=request_id,
+ response_model=response_model,
reasoning=reasoning,
)
return runner.run()
@@ -340,12 +342,16 @@ class _OpenAIChatStreamRunner:
request: MessagesRequest,
input_tokens: int,
request_id: str | None,
+ response_model: str | None,
reasoning: ReasoningPolicy,
) -> None:
self._provider = provider
self._request = request
self._input_tokens = input_tokens
self._request_id = request_id
+ self._response_model = (
+ request.model if response_model is None else response_model
+ )
self._reasoning = reasoning
self._message_id = f"msg_{uuid.uuid4()}"
self._tool_calls = OpenAIToolCallAssembler(
@@ -381,7 +387,7 @@ class _OpenAIChatStreamRunner:
source="provider",
provider=tag,
request_id=self._request_id,
- gateway_model=self._request.model,
+ gateway_model=self._response_model,
downstream_model=body.get("model"),
message_count=len(body.get("messages", [])),
tool_count=len(body.get("tools", [])),
@@ -995,7 +1001,7 @@ class _OpenAIChatStreamRunner:
def _new_ledger(self) -> AnthropicStreamLedger:
return AnthropicStreamLedger(
self._message_id,
- self._request.model,
+ self._response_model,
self._input_tokens,
log_raw_events=self._provider._config.log_raw_sse_events,
)
diff --git a/tests/api/test_api_handlers.py b/tests/api/test_api_handlers.py
index 8cdb80ff..ee299efc 100644
--- a/tests/api/test_api_handlers.py
+++ b/tests/api/test_api_handlers.py
@@ -60,6 +60,7 @@ class FakeProvider:
input_tokens: int = 0,
*,
request_id: str | None = None,
+ response_model: str | None = None,
reasoning: ReasoningPolicy,
) -> AsyncIterator[str]:
self.requests.append(request)
@@ -67,6 +68,7 @@ class FakeProvider:
{
"input_tokens": input_tokens,
"request_id": request_id,
+ "response_model": response_model,
"reasoning": reasoning,
}
)
@@ -117,6 +119,7 @@ async def test_messages_handler_passes_routed_request_and_stream_metadata() -> N
assert provider.requests[0].model == "test-model"
assert provider.stream_kwargs[0]["input_tokens"] > 0
assert provider.stream_kwargs[0]["request_id"].startswith("req_")
+ assert provider.stream_kwargs[0]["response_model"] == "nvidia_nim/test-model"
assert provider.stream_kwargs[0]["reasoning"] == ReasoningPolicy.provider_default()
assert len(provider.preflight_calls) == 1
@@ -330,6 +333,7 @@ async def test_messages_handler_stream_false_provider_exception_keeps_status() -
input_tokens: int = 0,
*,
request_id: str | None = None,
+ response_model: str | None = None,
reasoning: ReasoningPolicy,
) -> AsyncIterator[str]:
self.requests.append(request)
@@ -337,6 +341,7 @@ async def test_messages_handler_stream_false_provider_exception_keeps_status() -
{
"input_tokens": input_tokens,
"request_id": request_id,
+ "response_model": response_model,
"reasoning": reasoning,
}
)
@@ -397,7 +402,7 @@ async def test_messages_handler_forces_no_thinking_for_safety_classifier() -> No
"stage": "routing",
"event": "free_claude_code.api.optimization.safety_classifier_no_thinking",
"source": "api",
- "model": "test-model",
+ "model": "nvidia_nim/test-model",
"changed": True,
}
]
@@ -465,7 +470,7 @@ async def test_messages_handler_keeps_existing_no_thinking_for_classifier() -> N
"stage": "routing",
"event": "free_claude_code.api.optimization.safety_classifier_no_thinking",
"source": "api",
- "model": "test-model",
+ "model": "claude-3-freecc-no-thinking/nvidia_nim/test-model",
"changed": False,
}
]
diff --git a/tests/api/test_optimization_handlers.py b/tests/api/test_optimization_handlers.py
index b4d78285..d4405ce8 100644
--- a/tests/api/test_optimization_handlers.py
+++ b/tests/api/test_optimization_handlers.py
@@ -233,3 +233,23 @@ class TestTryOptimizations:
settings.enable_filepath_extraction_mock = False
req = _make_request("random user message")
assert try_optimizations(req, settings) is None
+
+ def test_response_uses_gateway_model_without_changing_routed_request(self):
+ settings = Settings()
+ settings.enable_network_probe_mock = True
+ req = _make_request("quota", max_tokens=1)
+ req.model = "upstream-model"
+
+ with patch(
+ "free_claude_code.api.optimization_handlers.is_quota_check_request",
+ return_value=True,
+ ):
+ result = try_optimizations(
+ req,
+ settings,
+ response_model="anthropic/provider/upstream-model",
+ )
+
+ assert result is not None
+ assert result.model == "anthropic/provider/upstream-model"
+ assert req.model == "upstream-model"
diff --git a/tests/api/test_web_server_tools.py b/tests/api/test_web_server_tools.py
index 9a561341..a1bd907d 100644
--- a/tests/api/test_web_server_tools.py
+++ b/tests/api/test_web_server_tools.py
@@ -56,18 +56,26 @@ def test_web_tool_user_agent_reports_installed_package_version() -> None:
class FixedProviderModelRouter(ModelRouter):
"""Test double that pins provider identity."""
- def __init__(self, settings: Settings, provider_id: str) -> None:
+ def __init__(
+ self,
+ settings: Settings,
+ provider_id: str,
+ *,
+ provider_model: str | None = None,
+ ) -> None:
super().__init__(settings)
self._fixed_provider_id = provider_id
+ self._fixed_provider_model = provider_model
def resolve_messages_request(
self, request: MessagesRequest
) -> RoutedMessagesRequest:
+ provider_model = self._fixed_provider_model or request.model
resolved = ResolvedModel(
original_model=request.model,
provider_id=self._fixed_provider_id,
- provider_model=request.model,
- provider_model_ref=f"{self._fixed_provider_id}/{request.model}",
+ provider_model=provider_model,
+ provider_model_ref=f"{self._fixed_provider_id}/{provider_model}",
reasoning_preference=ReasoningPreference.OFF,
)
routed = request.model_copy(deep=True)
@@ -425,7 +433,11 @@ async def test_service_streams_forced_web_search_by_default(monkeypatch):
service = MessagesHandler(
settings,
provider_resolver=provider_resolver,
- model_router=FixedProviderModelRouter(settings, _PROVIDER_IDS[0]),
+ model_router=FixedProviderModelRouter(
+ settings,
+ _PROVIDER_IDS[0],
+ provider_model="upstream-model",
+ ),
)
request = MessagesRequest(
model="claude-haiku-4-5-20251001",
@@ -443,6 +455,12 @@ async def test_service_streams_forced_web_search_by_default(monkeypatch):
raw = await _streaming_body_text(response)
assert "event: message_start" in raw
assert "DeepSeek V4 Released" in raw
+ message_start = next(
+ event.data["message"]
+ for event in parse_sse_text(raw)
+ if event.event == "message_start"
+ )
+ assert message_start["model"] == request.model
provider_resolver.assert_not_called()
diff --git a/tests/application/test_execution.py b/tests/application/test_execution.py
index 1ada6e12..d0491ffa 100644
--- a/tests/application/test_execution.py
+++ b/tests/application/test_execution.py
@@ -33,6 +33,7 @@ class FakeProvider:
input_tokens: int = 0,
*,
request_id: str | None = None,
+ response_model: str | None = None,
reasoning: ReasoningPolicy,
) -> AsyncIterator[str]:
self.stream_calls.append(
@@ -40,6 +41,7 @@ class FakeProvider:
"request": request,
"input_tokens": input_tokens,
"request_id": request_id,
+ "response_model": response_model,
"reasoning": reasoning,
}
)
@@ -66,6 +68,7 @@ class FailingStreamConstructionProvider(FakeProvider):
input_tokens: int = 0,
*,
request_id: str | None = None,
+ response_model: str | None = None,
reasoning: ReasoningPolicy,
) -> AsyncIterator[str]:
raise RuntimeError("stream construction failed")
@@ -114,6 +117,7 @@ async def test_executor_uses_structural_provider_port_and_preflights_eagerly() -
"request": request,
"input_tokens": 17,
"request_id": "req_application",
+ "response_model": "gateway-model",
"reasoning": ReasoningPolicy.on(),
}
]
diff --git a/tests/providers/test_model_discovery.py b/tests/providers/test_model_discovery.py
index 21268515..11a5fe63 100644
--- a/tests/providers/test_model_discovery.py
+++ b/tests/providers/test_model_discovery.py
@@ -368,6 +368,7 @@ class FakeProvider(BaseProvider):
input_tokens: int = 0,
*,
request_id: str | None = None,
+ response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
) -> AsyncIterator[str]:
if False:
diff --git a/tests/providers/test_openai_chat_usage.py b/tests/providers/test_openai_chat_usage.py
index 2c23fa93..1b5a9f14 100644
--- a/tests/providers/test_openai_chat_usage.py
+++ b/tests/providers/test_openai_chat_usage.py
@@ -200,6 +200,38 @@ async def test_openai_chat_stream_requests_usage_and_uses_provider_prompt_tokens
assert final_usage == {"input_tokens": 22, "output_tokens": 4}
+async def test_openai_chat_stream_keeps_response_model_separate_from_upstream_model():
+ provider = _UsageTestProvider()
+ request = make_messages_request(model="upstream/model")
+ create = AsyncMock(
+ return_value=_stream(
+ [
+ _chunk(content="hello"),
+ _chunk(finish_reason="stop"),
+ ]
+ )
+ )
+
+ with patch.object(provider._client.chat.completions, "create", create):
+ events = [
+ event
+ async for event in provider.stream_response(
+ request,
+ response_model="anthropic/test/upstream/model",
+ )
+ ]
+
+ assert create.await_args is not None
+ assert create.await_args.kwargs["model"] == "upstream/model"
+ message_start = next(
+ event.data["message"]
+ for event in parse_sse_text("".join(events))
+ if event.event == "message_start"
+ )
+ assert message_start["model"] == "anthropic/test/upstream/model"
+
+
@pytest.mark.asyncio
async def test_openai_chat_stream_retries_without_usage_when_option_is_rejected():
provider = _UsageTestProvider()
diff --git a/tests/providers/test_preflight_contract.py b/tests/providers/test_preflight_contract.py
index cb97d08b..dd1e2601 100644
--- a/tests/providers/test_preflight_contract.py
+++ b/tests/providers/test_preflight_contract.py
@@ -38,6 +38,7 @@ class ProviderWithoutPreflight(BaseProvider):
input_tokens: int = 0,
*,
request_id: str | None = None,
+ response_model: str | None = None,
reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
) -> AsyncIterator[str]:
if False:
diff --git a/tests/providers/test_streaming_errors.py b/tests/providers/test_streaming_errors.py
index 68443fed..0434bd7b 100644
--- a/tests/providers/test_streaming_errors.py
+++ b/tests/providers/test_streaming_errors.py
@@ -120,6 +120,7 @@ def _make_stream_runner(
request=request or _make_request(),
input_tokens=0,
request_id=request_id,
+ response_model=None,
reasoning=DEFAULT_REASONING_POLICY,
)
diff --git a/uv.lock b/uv.lock
index ba0bc797..b9c3de71 100644
--- a/uv.lock
+++ b/uv.lock
@@ -620,7 +620,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "4.12.9"
+version = "4.12.10"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },