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

Restore Claude Code client controls for OpenAI Responses (#1311)

Ali Khokhar80b15dfe62ec
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 08ff569c..0ea25948 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -990,6 +990,16 @@ policy. The adapter preserves `reasoning.effort` in Anthropic `output_config`;
the application reasoning boundary then interprets `none` as off and preserves
all other named efforts. It never translates OpenAI effort names into Anthropic
token budgets.
+Application-resolved source controls remain on the immutable canonical request;
+provider adapters consume the resolved `ReasoningPolicy` rather than parsing
+those controls again. A target converter validates only the unrepresented
+semantic remainder: it may omit an application-consumed control or an exact
+no-op, but must reject active or unknown behavior before upstream I/O. For the
+connected OpenAI Responses transport, `output_config.effort` is already
+represented by the policy and an empty context edit or exact
+`clear_thinking_20251015` edit with `keep: "all"` is inert. Structured-output
+configuration and any active, malformed, or extended context edit remain
+unsupported and fail preflight rather than being silently discarded.
Prior Responses `reasoning` input items replay plaintext `reasoning_text`, or
fallback `summary_text`, into assistant `reasoning_content`. Encrypted reasoning
input is ignored because the proxy cannot decrypt it.
diff --git a/pyproject.toml b/pyproject.toml
index 9f11d048..62ffe342 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "4.16.1"
+version = "4.16.2"
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/core/openai_responses/provider_input.py b/src/free_claude_code/core/openai_responses/provider_input.py
index 9375b187..bc4ecea0 100644
--- a/src/free_claude_code/core/openai_responses/provider_input.py
+++ b/src/free_claude_code/core/openai_responses/provider_input.py
@@ -100,10 +100,9 @@ def _validate_supported_request(request: MessagesRequest) -> None:
unsupported.append("stop_sequences")
if request.top_k is not None:
unsupported.append("top_k")
- if request.context_management:
+ if not _is_noop_context_management(request.context_management):
unsupported.append("context_management")
- if request.output_config:
- unsupported.append("output_config")
+ unsupported.extend(_unsupported_output_config_paths(request.output_config))
if request.mcp_servers:
unsupported.append("mcp_servers")
if request.extra_body:
@@ -115,6 +114,33 @@ def _validate_supported_request(request: MessagesRequest) -> None:
)
+def _unsupported_output_config_paths(
+ output_config: dict[str, Any] | None,
+) -> list[str]:
+ if not output_config:
+ return []
+ return [f"output_config.{key}" for key in sorted(output_config) if key != "effort"]
+
+
+def _is_noop_context_management(
+ context_management: dict[str, Any] | None,
+) -> bool:
+ if not context_management:
+ return True
+ if set(context_management) != {"edits"}:
+ return False
+ edits = context_management["edits"]
+ return isinstance(edits, list) and all(
+ isinstance(edit, dict)
+ and edit
+ == {
+ "type": "clear_thinking_20251015",
+ "keep": "all",
+ }
+ for edit in edits
+ )
+
+
def _system_text(request: MessagesRequest) -> list[str]:
if request.system is None:
return []
diff --git a/tests/api/test_openai_codex_compatibility.py b/tests/api/test_openai_codex_compatibility.py
new file mode 100644
index 00000000..e647f51f
--- /dev/null
+++ b/tests/api/test_openai_codex_compatibility.py
@@ -0,0 +1,130 @@
+import json
+
+import httpx
+import pytest
+from fastapi.testclient import TestClient
+
+from free_claude_code.core.anthropic.stream_contracts import (
+ assert_anthropic_stream_contract,
+ parse_sse_text,
+ text_content,
+)
+from free_claude_code.providers.admission import ProviderAdmissionController
+from free_claude_code.providers.base import ProviderConfig
+from free_claude_code.providers.openai_codex.auth import (
+ OpenAIAccess,
+ OpenAIAuthManager,
+)
+from free_claude_code.providers.openai_codex.provider import OpenAICodexProvider
+from tests.api.support import create_test_app
+
+
+class _FakeOpenAIAuth(OpenAIAuthManager):
+ async def access(self, *, force_refresh: bool = False) -> OpenAIAccess:
+ return OpenAIAccess("access", "account", False)
+
+ async def recover_unauthorized(self, rejected_token: str) -> OpenAIAccess:
+ raise AssertionError("The compatibility request must not require auth recovery")
+
+
+def _complete_stream(text: str) -> str:
+ events = [
+ (
+ "response.created",
+ {"type": "response.created", "response": {"id": "resp_1"}},
+ ),
+ (
+ "response.output_text.delta",
+ {"type": "response.output_text.delta", "delta": text},
+ ),
+ (
+ "response.completed",
+ {
+ "type": "response.completed",
+ "response": {
+ "id": "resp_1",
+ "usage": {"input_tokens": 3, "output_tokens": 2},
+ },
+ },
+ ),
+ ]
+ return "".join(
+ f"event: {event_type}\ndata: {json.dumps(payload)}\n\n"
+ for event_type, payload in events
+ )
+
+
+async def test_messages_accepts_current_claude_controls_for_openai_provider() -> None:
+ upstream_requests: list[httpx.Request] = []
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ upstream_requests.append(request)
+ return httpx.Response(
+ 200,
+ text=_complete_stream("hello"),
+ headers={"content-type": "text/event-stream"},
+ request=request,
+ )
+
+ upstream_client = httpx.AsyncClient(
+ base_url="https://chatgpt.com/backend-api/codex/",
+ transport=httpx.MockTransport(handler),
+ )
+ provider = OpenAICodexProvider(
+ ProviderConfig(
+ api_key="",
+ base_url="https://chatgpt.com/backend-api/codex",
+ rate_limit=100,
+ rate_window=1,
+ max_concurrency=2,
+ ),
+ auth=_FakeOpenAIAuth(),
+ admission=ProviderAdmissionController(
+ provider_name="openai",
+ rate_limit=100,
+ rate_window=1,
+ max_concurrency=2,
+ base_delay=0,
+ max_delay=0,
+ jitter=0,
+ ),
+ client=upstream_client,
+ )
+ app = create_test_app(providers={"openai": provider})
+
+ try:
+ with TestClient(app) as client:
+ response = client.post(
+ "/v1/messages",
+ json={
+ "model": "openai/gpt-test",
+ "max_tokens": 1024,
+ "messages": [{"role": "user", "content": "hello"}],
+ "thinking": {"type": "adaptive", "display": "omitted"},
+ "context_management": {
+ "edits": [
+ {
+ "type": "clear_thinking_20251015",
+ "keep": "all",
+ }
+ ]
+ },
+ "output_config": {"effort": "high"},
+ "stream": True,
+ },
+ )
+ finally:
+ await upstream_client.aclose()
+
+ assert response.status_code == 200
+ assert response.headers["content-type"].startswith("text/event-stream")
+ events = parse_sse_text(response.text)
+ assert_anthropic_stream_contract(events)
+ assert text_content(events) == "hello"
+ assert len(upstream_requests) == 1
+ payload = json.loads(upstream_requests[0].content)
+ assert payload["model"] == "gpt-test"
+ assert payload["reasoning"] == {"effort": "high", "summary": "auto"}
+ assert "context_management" not in payload
+ assert "output_config" not in payload
diff --git a/tests/core/openai_responses/test_provider_input.py b/tests/core/openai_responses/test_provider_input.py
index 29dd56fe..06a9aead 100644
--- a/tests/core/openai_responses/test_provider_input.py
+++ b/tests/core/openai_responses/test_provider_input.py
@@ -2,6 +2,7 @@ import json
import pytest
+from free_claude_code.application.reasoning import client_reasoning_policy
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.core.openai_responses import (
OpenAIResponsesAdapter,
@@ -13,6 +14,11 @@ from free_claude_code.core.openai_responses.provider_input import (
)
from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
+_KEEP_ALL_THINKING_EDIT = {
+ "type": "clear_thinking_20251015",
+ "keep": "all",
+}
+
def test_build_responses_provider_request_preserves_multiturn_protocol() -> None:
request = MessagesRequest.model_validate(
@@ -107,6 +113,182 @@ def test_build_responses_provider_request_preserves_multiturn_protocol() -> None
}
+def test_build_responses_provider_request_accepts_claude_client_controls() -> None:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "gpt-test",
+ "messages": [{"role": "user", "content": "hello"}],
+ "thinking": {"type": "adaptive", "display": "omitted"},
+ "context_management": {"edits": [_KEEP_ALL_THINKING_EDIT]},
+ "output_config": {"effort": "high"},
+ }
+ )
+ snapshot = request.model_dump()
+
+ body = build_responses_provider_request(
+ request,
+ reasoning=ReasoningPolicy.on(effort=ReasoningEffort.HIGH),
+ )
+
+ assert body["reasoning"] == {"effort": "high", "summary": "auto"}
+ assert "context_management" not in body
+ assert "output_config" not in body
+ assert request.model_dump() == snapshot
+
+
+def test_build_responses_provider_request_uses_resolved_reasoning_policy() -> None:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "gpt-test",
+ "messages": [{"role": "user", "content": "hello"}],
+ "output_config": {"effort": "low"},
+ }
+ )
+
+ body = build_responses_provider_request(
+ request,
+ reasoning=ReasoningPolicy.on(effort=ReasoningEffort.MAX),
+ )
+
+ assert body["reasoning"] == {"effort": "max", "summary": "auto"}
+
+
+ "context_management",
+ [
+ None,
+ {},
+ {"edits": []},
+ {"edits": [_KEEP_ALL_THINKING_EDIT]},
+ {"edits": [_KEEP_ALL_THINKING_EDIT, _KEEP_ALL_THINKING_EDIT]},
+ ],
+)
+def test_build_responses_provider_request_accepts_noop_context_management(
+ context_management: dict[str, object] | None,
+) -> None:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "gpt-test",
+ "messages": [{"role": "user", "content": "hello"}],
+ "context_management": context_management,
+ }
+ )
+
+ body = build_responses_provider_request(
+ request,
+ reasoning=ReasoningPolicy.provider_default(),
+ )
+
+ assert "context_management" not in body
+
+
+ "context_management",
+ [
+ {"edits": [{"type": "clear_thinking_20251015"}]},
+ {
+ "edits": [
+ {
+ "type": "clear_thinking_20251015",
+ "keep": {"type": "thinking_turns", "value": 2},
+ }
+ ]
+ },
+ {"edits": [{"type": "clear_tool_uses_20250919"}]},
+ {"edits": [{"type": "unknown_edit", "keep": "all"}]},
+ {
+ "edits": [
+ {
+ **_KEEP_ALL_THINKING_EDIT,
+ "extra": True,
+ }
+ ]
+ },
+ {"edits": [], "extra": True},
+ {"edits": None},
+ {"edits": {}},
+ {"edits": "not-a-list"},
+ ],
+)
+def test_build_responses_provider_request_rejects_active_or_malformed_context(
+ context_management: dict[str, object],
+) -> None:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "gpt-test",
+ "messages": [{"role": "user", "content": "hello"}],
+ "context_management": context_management,
+ }
+ )
+
+ with pytest.raises(ResponsesConversionError, match="context_management"):
+ build_responses_provider_request(
+ request,
+ reasoning=ReasoningPolicy.provider_default(),
+ )
+
+
+ ("effort", "reasoning", "expected"),
+ [
+ (
+ "high",
+ ReasoningPolicy.on(effort=ReasoningEffort.HIGH),
+ {"effort": "high", "summary": "auto"},
+ ),
+ ("none", ReasoningPolicy.off(), {"effort": "none"}),
+ ("future", ReasoningPolicy.provider_default(), None),
+ ],
+)
+def test_build_responses_provider_request_accepts_application_owned_effort(
+ effort: str,
+ reasoning: ReasoningPolicy,
+ expected: dict[str, str] | None,
+) -> None:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "gpt-test",
+ "messages": [{"role": "user", "content": "hello"}],
+ "output_config": {"effort": effort},
+ }
+ )
+
+ body = build_responses_provider_request(request, reasoning=reasoning)
+
+ assert body.get("reasoning") == expected
+ assert "output_config" not in body
+
+
+ ("output_config", "unsupported_path"),
+ [
+ ({"format": {"type": "json_schema"}}, "output_config.format"),
+ (
+ {"effort": "high", "format": {"type": "json_schema"}},
+ "output_config.format",
+ ),
+ ({"future_control": True}, "output_config.future_control"),
+ ],
+)
+def test_build_responses_provider_request_rejects_unconsumed_output_config(
+ output_config: dict[str, object],
+ unsupported_path: str,
+) -> None:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "gpt-test",
+ "messages": [{"role": "user", "content": "hello"}],
+ "output_config": output_config,
+ }
+ )
+
+ with pytest.raises(ResponsesConversionError, match=unsupported_path):
+ build_responses_provider_request(
+ request,
+ reasoning=ReasoningPolicy.provider_default(),
+ )
+
+
def test_responses_provider_request_uses_one_portable_tool_alias() -> None:
original = "mcp__responses_provider__" + "x" * 70
request = MessagesRequest.model_validate(
@@ -219,13 +401,31 @@ def test_responses_round_trip_preserves_encrypted_reasoning_and_tool_ids() -> No
]
+def test_responses_reasoning_round_trip_reaches_provider_request() -> None:
+ adapter = OpenAIResponsesAdapter()
+ ingress = OpenAIResponsesRequest.model_validate(
+ {
+ "model": "openai/gpt-test",
+ "input": "hello",
+ "reasoning": {"effort": "high"},
+ }
+ )
+ anthropic = MessagesRequest.model_validate(adapter.to_anthropic_payload(ingress))
+
+ body = build_responses_provider_request(
+ anthropic,
+ reasoning=client_reasoning_policy(anthropic),
+ )
+
+ assert body["reasoning"] == {"effort": "high", "summary": "auto"}
+ assert "output_config" not in body
+
+
@pytest.mark.parametrize(
("field", "value"),
[
("stop_sequences", ["stop"]),
("top_k", 4),
- ("context_management", {"edits": []}),
- ("output_config", {"effort": "high"}),
("mcp_servers", [{"name": "server"}]),
("extra_body", {"unknown": True}),
],
@@ -266,3 +466,19 @@ def test_build_responses_provider_request_rejects_provider_managed_tools() -> No
request,
reasoning=ReasoningPolicy.provider_default(),
)
+
+
+def test_build_responses_provider_request_rejects_unknown_request_fields() -> None:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "gpt-test",
+ "messages": [{"role": "user", "content": "hello"}],
+ "future_field": True,
+ }
+ )
+
+ with pytest.raises(ResponsesConversionError, match="future_field"):
+ build_responses_provider_request(
+ request,
+ reasoning=ReasoningPolicy.provider_default(),
+ )
diff --git a/tests/providers/test_openai_codex_provider.py b/tests/providers/test_openai_codex_provider.py
index 2e9bc168..c4cd6618 100644
--- a/tests/providers/test_openai_codex_provider.py
+++ b/tests/providers/test_openai_codex_provider.py
@@ -5,6 +5,7 @@ from typing import Any
import httpx
import pytest
+from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.core.anthropic.stream_contracts import (
assert_anthropic_stream_contract,
@@ -12,7 +13,7 @@ from free_claude_code.core.anthropic.stream_contracts import (
text_content,
)
from free_claude_code.core.failures import ExecutionFailure
-from free_claude_code.core.reasoning import ReasoningPolicy
+from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
from free_claude_code.providers.admission import ProviderAdmissionController
from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.openai_codex.auth import (
@@ -70,6 +71,27 @@ def _request() -> MessagesRequest:
)
+def _client_control_request() -> MessagesRequest:
+ return MessagesRequest.model_validate(
+ {
+ "model": "gpt-test",
+ "max_tokens": 1024,
+ "messages": [{"role": "user", "content": "hello"}],
+ "thinking": {"type": "adaptive", "display": "omitted"},
+ "context_management": {
+ "edits": [
+ {
+ "type": "clear_thinking_20251015",
+ "keep": "all",
+ }
+ ]
+ },
+ "output_config": {"effort": "high"},
+ "stream": True,
+ }
+ )
+
+
def _sse(*events: tuple[str, dict[str, Any]]) -> str:
return "".join(
f"event: {event_type}\ndata: {json.dumps(payload)}\n\n"
@@ -172,6 +194,107 @@ async def test_provider_uses_subscription_headers_and_visible_model_catalog() ->
await client.aclose()
+async def test_provider_accepts_claude_client_controls_before_upstream_io() -> None:
+ requests: list[httpx.Request] = []
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ requests.append(request)
+ return httpx.Response(
+ 200,
+ text=_complete_stream("hello"),
+ headers={"content-type": "text/event-stream"},
+ request=request,
+ )
+
+ client = httpx.AsyncClient(
+ base_url="https://chatgpt.com/backend-api/codex/",
+ transport=httpx.MockTransport(handler),
+ )
+ provider = OpenAICodexProvider(
+ _config(), auth=_FakeAuth(), admission=_admission(), client=client
+ )
+ request = _client_control_request()
+ reasoning = ReasoningPolicy.on(effort=ReasoningEffort.HIGH)
+
+ provider.preflight_stream(request, reasoning=reasoning)
+ assert requests == []
+
+ body = await _collect(
+ provider.stream_response(
+ request,
+ request_id="req_client_controls",
+ response_model="claude-opus-4",
+ reasoning=reasoning,
+ )
+ )
+
+ assert len(requests) == 1
+ upstream = requests[0]
+ assert upstream.url.path.endswith("/responses")
+ payload = json.loads(upstream.content)
+ assert payload["model"] == "gpt-test"
+ assert payload["reasoning"] == {"effort": "high", "summary": "auto"}
+ assert "context_management" not in payload
+ assert "output_config" not in payload
+ assert_anthropic_stream_contract(parse_sse_text(body))
+ await client.aclose()
+
+
+ ("field", "value", "error_path"),
+ [
+ (
+ "context_management",
+ {
+ "edits": [
+ {
+ "type": "clear_thinking_20251015",
+ "keep": {"type": "thinking_turns", "value": 2},
+ }
+ ]
+ },
+ "context_management",
+ ),
+ (
+ "output_config",
+ {"format": {"type": "json_schema"}},
+ "output_config.format",
+ ),
+ ],
+)
+async def test_provider_preflight_rejects_unrepresentable_client_controls(
+ field: str,
+ value: object,
+ error_path: str,
+) -> None:
+ requests: list[httpx.Request] = []
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ requests.append(request)
+ return httpx.Response(500, request=request)
+
+ client = httpx.AsyncClient(
+ base_url="https://chatgpt.com/backend-api/codex/",
+ transport=httpx.MockTransport(handler),
+ )
+ provider = OpenAICodexProvider(
+ _config(), auth=_FakeAuth(), admission=_admission(), client=client
+ )
+ payload = {
+ "model": "gpt-test",
+ "messages": [{"role": "user", "content": "hello"}],
+ field: value,
+ }
+
+ with pytest.raises(InvalidRequestError, match=error_path):
+ provider.preflight_stream(MessagesRequest.model_validate(payload))
+
+ assert requests == []
+ await client.aclose()
+
+
@pytest.mark.asyncio
async def test_provider_round_trips_portable_tool_name_alias() -> None:
original = "mcp__codex_provider__" + "x" * 70
diff --git a/uv.lock b/uv.lock
index 67348144..0ee0ae31 100644
--- a/uv.lock
+++ b/uv.lock
@@ -620,7 +620,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "4.16.1"
+version = "4.16.2"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },