Make reasoning policy provider-neutral and client-aware (#1148)

## Problem

FCC reduced reasoning to global and route booleans, mixing client
intent, configuration, provider wire capabilities, output visibility,
and history replay. That discarded named client efforts, encouraged
model-name checks, and made provider behavior inconsistent.

## Changes

| Before | After |
| --- | --- |
| Admin exposed global and route thinking toggles. | Admin exposes
**Off**, **From client**, **Low**, **Medium**, **High**, **X-High**, and
**Max**; Fable, Opus, Sonnet, and Haiku also expose **Inherit**. |
| Request intent was repeatedly reduced to a boolean across routing and
providers. | The application boundary resolves one immutable
`ReasoningPolicy` with independent control, named effort, and exact
positive token budget. |
| Provider adapters could infer reasoning behavior from upstream model
names or versions. | Provider profiles translate only documented
provider-wide wire capabilities; architecture and contributor rules
prohibit model-specific reasoning branches. |
| Gateway reasoning controls were ad hoc. |
[OpenRouter](https://openrouter.ai/docs/guides/best-practices/reasoning-tokens)
and [Vercel AI
Gateway](https://vercel.com/docs/ai-gateway/models-and-providers) use
documented reasoning objects, including exact budgets where
representable. |
| Named effort forwarding was inconsistent or absent. |
[Gemini](https://ai.google.dev/gemini-api/docs/openai),
[Ollama](https://docs.ollama.com/api/openai-compatibility), [LM
Studio](https://lmstudio.ai/changelog/lmstudio-v0.4.8),
[Fireworks](https://docs.fireworks.ai/guides/querying-text-models/reasoning),
[Cohere](https://docs.cohere.com/docs/compatibility-api),
[Wafer](https://docs.wafer.ai/serverless/api-reference),
[Groq](https://console.groq.com/docs/reasoning),
[Cerebras](https://inference-docs.cerebras.ai/capabilities/reasoning),
[SambaNova](https://docs.sambanova.ai/docs/api-reference/chat-completions/create-chat-based-completion),
and
[Mistral](https://docs.mistral.ai/studio-api/conversations/reasoning)
receive their documented named vocabularies with explicit provider-owned
downgrades. |
| Boolean thinking controls were mixed into shared conversion. |
[DeepSeek](https://api-docs.deepseek.com/guides/thinking_mode/),
[Kimi](https://platform.kimi.ai/docs/guide/use-kimi-k2-thinking-model),
[Z.ai](https://docs.z.ai/guides/capabilities/thinking-mode), [Cloudflare
Workers
AI](https://developers.cloudflare.com/changelog/post/2026-04-20-kimi-k2-6-workers-ai/),
and [NVIDIA
NIM](https://docs.nvidia.com/nim/large-language-models/1.15.0/thinking-budget-control.html)
use provider-owned thinking-object or chat-template controls. |
| Effort names and output limits could become fabricated reasoning
budgets. | Exact budgets remain exact and are forwarded only through
documented fields for OpenRouter, Fireworks, LM Studio, NIM, and
[llama.cpp](https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md);
named efforts and output limits are never converted into token budgets.
|
| New-turn reasoning and prior-turn replay shared one switch. | Every
profile independently declares native reasoning replay, `<think>` tag
replay, provider-specific replay, or no replay; **Off** suppresses new
reasoning output without corrupting required history. |
| Providers without a stable generic compute control received guessed
controls. |
[MiniMax](https://platform.minimax.io/docs/api-reference/text-openai-api)
requests split output only, while [GitHub
Models](https://docs.github.com/en/rest/models/inference), [Hugging Face
Inference
Providers](https://huggingface.co/docs/inference-providers/en/tasks/chat-completion),
Codestral, and OpenCode keep provider defaults and use only their
explicit replay profile. |
| OpenAI Responses effort became a lossy Anthropic thinking boolean. |
Responses preserves `reasoning.effort` through `output_config`, then
resolves it through the same application policy as Messages without
inventing a budget. |
| Legacy booleans remained the persisted contract. | FCC-owned dotenv
files migrate to typed `REASONING_*` values, explicit env files receive
an actionable warning, documentation describes the ownership boundary,
and the package advances to 4.8.0. |
| Reasoning behavior was covered by scattered boolean assertions. | New
policy, routing, encoder, provider, Admin, migration, Responses, and
smoke contracts pass all five local CI checks: 2,368 tests passed, 40
skipped; 92 smoke tests collect and both live config migration checks
pass. |

<!-- greptile_comment -->

<details open><summary><h3>Greptile Summary</h3></summary>

This PR makes reasoning policy client-aware and independent of provider
model names. The main changes are:

- Adds one immutable reasoning policy resolved at the application
boundary.
- Adds typed root and route reasoning settings with Admin UI support.
- Moves wire controls and history replay behavior into provider
profiles.
- Migrates owned dotenv files from legacy thinking booleans.
- Expands provider, routing, migration, API, and smoke coverage.
</details>

<h3>Confidence Score: 5/5</h3>

This looks safe to merge.

No blocking issues found in the changed code.

<details><summary><h3><a href="https://www.greptile.com/trex"><img
alt="T-Rex"
src="https://greptile-static-assets.s3.amazonaws.com/trex/trex_green.svg"
height="20" align="absmiddle"></a> T-Rex Logs</h3></summary>

**What T-Rex did**
- Ran the contract-validation test suite with the specified test
modules, and the tests reported 78 passed in 1.53s with exit code 0.
- Reviewed the complete captured output artifact
reasoning-contract-02-after.log to verify the final test outcomes and
successful contract validation.

<a
href="https://app.greptile.com/trex/runs/14792858/artifacts"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifactsDark.svg?v=4"><source
media="(prefers-color-scheme: light)"
srcset="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifacts.svg?v=4"><img
alt="View all artifacts"
src="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifacts.svg?v=4"></picture></a>

_{<a href="https://www.greptile.com/trex"><img alt="T-Rex"
src="https://greptile-static-assets.s3.amazonaws.com/trex/trex_green.svg"
height="14" align="absmiddle"></a> Ran code and verified through
T-Rex}
</details>

<details open><summary><h3>Important Files Changed</h3></summary>

| Filename | Overview |
|----------|----------|
| src/free_claude_code/config/env_migrations.py | Migrates legacy
reasoning booleans in owned dotenv files and warns for explicit
environment files. |
| src/free_claude_code/application/reasoning.py | Resolves client
controls and configured preferences into one provider-neutral reasoning
policy. |
| src/free_claude_code/application/routing.py | Carries route-level
reasoning preferences into request-scoped policy resolution. |
| src/free_claude_code/providers/openai_chat/reasoning.py | Provides
shared provider encoders for reasoning controls and replay behavior. |

</details>

_{Reviews (2): Last reviewed commit: ["chore: release reasoning
controls as
4.8..."](https://github.com/alishahryar1/free-claude-code/commit/9d4be767f7dbdca5709474012f43dcdc6f4347e3)
| [Re-trigger
Greptile](https://app.greptile.com/api/retrigger?id=44984039)}

<!-- /greptile_comment -->

.env.example

@@ -139,14 +139,15 @@ FCC_SMOKE_OPENROUTER_FREE_MODELS=
 FCC_SMOKE_OPENROUTER_FREE_EXTRA_MODELS=
 
 
-# Thinking output
-# Per-Claude-model switches for provider reasoning requests and Claude thinking blocks.
-# Blank per-model switches inherit ENABLE_MODEL_THINKING.
-ENABLE_FABLE_THINKING=
-ENABLE_OPUS_THINKING=
-ENABLE_SONNET_THINKING=
-ENABLE_HAIKU_THINKING=
-ENABLE_MODEL_THINKING=true
+# Reasoning policy
+# Root: off | client | low | medium | high | xhigh | max
+# Route overrides additionally accept inherit. "client" preserves the CLI's effort;
+# providers translate only controls documented by their API.
+REASONING_POLICY=client
+REASONING_FABLE=inherit
+REASONING_OPUS=inherit
+REASONING_SONNET=inherit
+REASONING_HAIKU=inherit
 
 
 # Provider config

AGENTS.md

@@ -35,6 +35,7 @@
 - **DRY**: Extract shared base classes to eliminate duplication. Prefer composition over copy-paste.
 - **Encapsulation**: Use accessor methods for internal state (e.g. `set_current_task()`), not direct `_attribute` assignment from outside.
 - **Provider-specific config**: Keep provider-specific fields (e.g. `nim_settings`) in provider constructors, not in the base `ProviderConfig`.
+- **Model-independent reasoning**: Resolve client reasoning intent once at the application boundary; provider adapters translate documented provider capabilities. Never branch on upstream model names or versions to choose reasoning behavior.
 - **Dead code**: Remove unused code, legacy systems, and hardcoded values. Use settings/config instead of literals (e.g. `settings.provider_type` not `"nvidia_nim"`).
 - **Performance**: Use list accumulation for strings (not `+=` in loops), cache env vars at init, prefer iterative over recursive when stack depth matters.
 - **Platform-agnostic naming**: Use generic names (e.g. `PLATFORM_EDIT`) not platform-specific ones (e.g. `TELEGRAM_EDIT`) in shared code.

ARCHITECTURE.md

@@ -312,9 +312,15 @@ Model routing configuration is tiered:
 
 - `MODEL` is the fallback provider-prefixed model ref.
 - `MODEL_FABLE`, `MODEL_OPUS`, `MODEL_SONNET`, and `MODEL_HAIKU` override Claude model tiers.
-- `ENABLE_MODEL_THINKING` is the global thinking switch.
-- `ENABLE_FABLE_THINKING`, `ENABLE_OPUS_THINKING`, `ENABLE_SONNET_THINKING`, and
-  `ENABLE_HAIKU_THINKING` optionally override thinking by tier.
+- `REASONING_POLICY` selects `off`, `client`, `low`, `medium`, `high`, `xhigh`,
+  or `max` for the fallback route.
+- `REASONING_FABLE`, `REASONING_OPUS`, `REASONING_SONNET`, and
+  `REASONING_HAIKU` accept the same values plus `inherit`.
+
+[config/reasoning.py](src/free_claude_code/config/reasoning.py) owns the typed
+configuration vocabulary. FCC-owned dotenv files receive a one-time rename and
+value migration from the retired boolean settings; explicit `FCC_ENV_FILE`
+files are never rewritten and instead receive an actionable startup warning.
 
 [config/model_refs.py](src/free_claude_code/config/model_refs.py) owns provider-prefixed model ref
 parsing and configured `MODEL*` inventory. API routing and provider validation
@@ -434,7 +440,7 @@ sequenceDiagram
     Route->>Manager: acquire current generation
     Manager-->>Route: Lease(settings, provider resolver)
     Route->>Handler: create message
-    Handler->>Router: resolve model and thinking
+    Handler->>Router: resolve model and reasoning intent
     Handler->>Handler: server tools or optimizations
     Handler->>Exec: stream routed request
     Exec->>Lease: resolve provider
@@ -465,10 +471,15 @@ If the incoming model is not direct, `ModelRouter` maps it by Claude tier. Names
 containing `fable`, `opus`, `sonnet`, or `haiku` use the matching tier override when set,
 otherwise they fall back to `MODEL`.
 
-The router also resolves thinking. Gateway model IDs can force thinking on or
-off; otherwise `ModelRouter` applies tier-specific thinking overrides or the
-global setting. `ResolvedModel` carries only the selected route and thinking
-decision; provider catalog metadata does not cross the application boundary.
+The router also selects the applicable reasoning preference. Direct provider
+refs use the root policy; Claude tier routes use a non-inherited tier override
+or the root fallback; the no-thinking gateway variant forces `off`.
+[application/reasoning.py](src/free_claude_code/application/reasoning.py) then
+combines that preference with the concrete client request exactly once. The
+resulting `ReasoningPolicy` preserves independent control, named effort, and an
+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.
 
 `GET /v1/models` advertises:
 
@@ -480,9 +491,11 @@ decision; provider catalog metadata does not cross the application boundary.
 Provider model discovery and optional thinking metadata live in the
 application-level catalog owned by `ProviderRuntimeManager`.
 `ProviderModelInfo.supports_thinking` alone owns discovered per-model thinking
-support; provider-wide capabilities do not model thinking. The catalog is not
-part of an individual provider generation, so a hot replacement does not erase
-the last useful model list. Discovery failures retain prior entries.
+support for model-list presentation; it does not select request behavior.
+Provider adapters must never branch on upstream model names or versions to
+translate reasoning. The catalog is not part of an individual provider
+generation, so a hot replacement does not erase the last useful model list.
+Discovery failures retain prior entries.
 
 Codex-specific model picker shaping stays out of this route. `fcc-codex` fetches
 the same `/v1/models` response at launch, converts FCC gateway IDs into
@@ -536,7 +549,7 @@ compatibility layer.
 [providers/base.py](src/free_claude_code/providers/base.py) defines provider-internal construction and lifecycle contracts:
 
 - `ProviderConfig`: shared provider settings such as API key, base URL, rate
-  limits, timeouts, proxy, thinking, and logging flags. It is a frozen internal
+  limits, timeouts, proxy, and logging flags. It is a frozen internal
   value whose base URL has already been resolved from the catalog.
 - `BaseProvider`: the abstract implementation base for cleanup, model listing,
   explicit preflight, and `stream_response()`.
@@ -544,7 +557,8 @@ compatibility layer.
 There is one upstream provider family:
 [providers/openai_chat/](src/free_claude_code/providers/openai_chat/) implements the concrete
 `OpenAIChatProvider` used by every OpenAI-compatible `/chat/completions`
-upstream. `OpenAIChatProfile` contains immutable request policy, its standard
+upstream. `OpenAIChatProfile` contains immutable request policy, an explicit
+reasoning encoder, an explicit history replay mode, its standard
 streamed-reasoning field, postprocessors, and base-URL normalization for
 ordinary vendors. Configuration differences therefore remain data rather than
 empty subclasses. The package also
@@ -559,7 +573,7 @@ LM Studio composes the OpenAI-chat conversion first and its context-budget probe
 second; conversion failure therefore cannot open a stream or run the probe.
 
 Providers call the OpenAI request policy for Anthropic-to-OpenAI conversion,
-thinking replay selection, `extra_body`, and chat-completion field normalization.
+reasoning replay selection, `extra_body`, and chat-completion field normalization.
 Specialized provider packages remain only for true upstream quirks such as
 Gemini thought signatures, NIM tool-schema aliases, retry downgrades, and NVCF
 deployment-failure classification, or DeepSeek attachment/tool/thinking
@@ -585,11 +599,47 @@ the GLM Coding Plan provider and uses Z.ai's Coding Plan OpenAI base.
 Mistral La Plateforme keeps its native `reasoning_effort` and thinking-chunk
 request/stream mapping inside
 [providers/mistral/reasoning.py](src/free_claude_code/providers/mistral/reasoning.py), including its
-fallback retry when a selected Mistral model rejects reasoning fields.
+fallback retry when an upstream request rejects reasoning fields.
 NIM reasoning budget control is also treated as a provider-owned best-effort
 downgrade: if an upstream NIM deployment rejects explicit budget control, FCC
 retries without the budget while preserving thinking enablement.
 
+### Reasoning Ownership
+
+[core/reasoning.py](src/free_claude_code/core/reasoning.py) owns the immutable,
+provider-neutral `ReasoningPolicy`. It represents three distinct facts:
+
+- `control`: provider default, explicitly off, or explicitly on;
+- `effort`: the client's named effort when one was supplied;
+- `budget_tokens`: an exact positive client budget, never a derived value.
+
+The application layer resolves configuration and client input into this value;
+the API layer may replace it for a product policy such as the safety classifier;
+providers receive it unchanged. Provider adapters alone translate the subset
+their documented wire API can represent. The shared OpenAI-chat implementation
+uses small encoder objects for named effort, reasoning objects, thinking
+objects, chat-template booleans, exact llama.cpp budgets, and split reasoning
+output. Specialized providers keep only translations that cannot be expressed
+by those encoders.
+
+Reasoning history replay is a separate request-conversion decision. Every
+profile explicitly chooses native `reasoning_content`, native `reasoning`,
+`<think>` tags, provider-specific chunks, or no replay. Turning off computation
+for the next generation does not silently erase prior assistant state required
+for a valid continuation.
+
+The boundary has four hard rules:
+
+1. Never inspect an upstream model name or version to select reasoning behavior.
+2. Never convert a named effort into a fabricated token budget, or use the
+   output-token limit as a reasoning budget.
+3. Forward an exact token budget only where the provider documents one; otherwise
+   translate a supported named or boolean control and leave unsupported precision
+   to the provider.
+4. Provider-default intent emits no compute-control field. Explicit off requests
+   an upstream disable where supported and always suppresses reasoning output at
+   the FCC protocol boundary.
+
 Shared provider responsibilities include upstream rate limiting, model listing,
 SDK/HTTP failure classification, safe diagnostic construction, HTTP resource
 cleanup, thinking/tool handling, retry or recovery where supported, and
@@ -755,10 +805,11 @@ tools with a single string `input` field, and restores `custom_tool_call`,
 Responses edge. Text or grammar format metadata is preserved as model guidance;
 FCC does not validate custom-tool grammars.
 
-Responses reasoning is handled as protocol conversion, not provider policy.
-`reasoning.effort = "none"` converts to a disabled Anthropic `thinking`
-request; any other explicit Responses reasoning request enables Anthropic
-thinking without translating OpenAI effort names into Anthropic token budgets.
+Responses reasoning is handled as lossless protocol conversion before provider
+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.
 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.
@@ -794,7 +845,7 @@ handling. Each optimization is controlled by settings flags.
 
 Claude Code auto-mode safety-classifier requests are a message-only routing
 policy, not a short-circuit response. After routing, the Messages handler detects the
-narrow classifier prompt shape and forces thinking off before provider execution
+narrow classifier prompt shape and forces reasoning off before provider execution
 so Claude Code receives a parser-readable `<block>yes</block>` or
 `<block>no</block>` verdict.
 
@@ -1321,7 +1372,7 @@ Update this file when a change adds or meaningfully changes:
 - startup, shutdown, or resource ownership;
 - configuration precedence or managed config behavior;
 - provider runtime, catalog, or upstream-adapter architecture;
-- model routing or thinking behavior;
+- model routing or reasoning behavior;
 - CLI adapter behavior;
 - messaging platform behavior;
 - protocol conversion or streaming contracts;

CLAUDE.md

@@ -35,6 +35,7 @@
 - **DRY**: Extract shared base classes to eliminate duplication. Prefer composition over copy-paste.
 - **Encapsulation**: Use accessor methods for internal state (e.g. `set_current_task()`), not direct `_attribute` assignment from outside.
 - **Provider-specific config**: Keep provider-specific fields (e.g. `nim_settings`) in provider constructors, not in the base `ProviderConfig`.
+- **Model-independent reasoning**: Resolve client reasoning intent once at the application boundary; provider adapters translate documented provider capabilities. Never branch on upstream model names or versions to choose reasoning behavior.
 - **Dead code**: Remove unused code, legacy systems, and hardcoded values. Use settings/config instead of literals (e.g. `settings.provider_type` not `"nvidia_nim"`).
 - **Performance**: Use list accumulation for strings (not `+=` in loops), cache env vars at init, prefer iterative over recursive when stack depth matters.
 - **Platform-agnostic naming**: Use generic names (e.g. `PLATFORM_EDIT`) not platform-specific ones (e.g. `TELEGRAM_EDIT`) in shared code.

README.md

@@ -201,6 +201,12 @@ Use the tag shown by `ollama list` with the `ollama/` prefix. `OLLAMA_BASE_URL`
 
 For example, route Opus to `nvidia_nim/moonshotai/kimi-k2.6`, Sonnet to `open_router/openrouter/free`, Haiku to `lmstudio/qwen3.5-coder`, and keep `MODEL` on `zai/glm-5.2`.
 
+### Reasoning Control
+
+Open **Admin UI → Model Config → Reasoning** to choose how FCC handles client reasoning controls. The default **From client** option preserves reasoning effort sent by Claude Code, Codex, or Pi; when the client sends no control, the provider keeps its own default.
+
+You can instead select **Off**, **Low**, **Medium**, **High**, **X-High**, or **Max**. Fable, Opus, Sonnet, and Haiku each have the same choices plus **Inherit**, which uses the root policy. FCC translates each choice only into controls documented by that provider, so unsupported precision safely remains provider-defined.
+
 <a id="connect-your-client"></a>
 
 ## Connect Your Client

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "free-claude-code"
-version = "4.7.3"
+version = "4.8.0"
 description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
 readme = "README.md"
 requires-python = ">=3.14.0"

smoke/capabilities.py

@@ -201,7 +201,7 @@ CAPABILITY_CONTRACTS: tuple[CapabilityContract, ...] = (
             "tests/providers/test_open_router.py",
         ),
         (
-            "test_per_model_thinking_config_e2e",
+            "test_route_reasoning_config_e2e",
             "test_provider_reasoning_tool_continuation_e2e",
         ),
     ),
@@ -269,10 +269,11 @@ CAPABILITY_CONTRACTS: tuple[CapabilityContract, ...] = (
         "removed_env_migration",
         "removed_env_migration",
         "free_claude_code.config.settings.Settings",
-        "NIM_ENABLE_THINKING or ENABLE_THINKING in env or dotenv",
-        "startup succeeds and stale keys do not change thinking defaults",
-        "removed key ignored",
-        ("tests/config/test_config.py",),
+        "retired ENABLE_MODEL_THINKING or tier override in an FCC-owned dotenv",
+        "owned dotenv is migrated to the typed reasoning policy",
+        "explicit dotenv receives an actionable warning",
+        ("tests/config/test_env_migrations.py", "tests/config/test_config.py"),
+        ("test_removed_env_migration_e2e",),
     ),
     CapabilityContract(
         "provider_runtime",

smoke/features.py

@@ -157,7 +157,7 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
             "test_provider_reasoning_tool_continuation_e2e",
             "test_gemini_thought_signature_tool_continuation_e2e",
             "test_claude_cli_adaptive_thinking_e2e",
-            "test_per_model_thinking_config_e2e",
+            "test_route_reasoning_config_e2e",
         ),
         ("providers", "cli", "config"),
         ("configured provider",),

smoke/product/test_config_extensibility_product_live.py

@@ -64,14 +64,14 @@ def test_removed_env_migration_e2e(smoke_config: SmokeConfig, tmp_path) -> None:
 
 
 @pytest.mark.smoke_target("config")
-def test_per_model_thinking_config_e2e(smoke_config: SmokeConfig, tmp_path) -> None:
+def test_route_reasoning_config_e2e(smoke_config: SmokeConfig, tmp_path) -> None:
     env_file = tmp_path / "thinking.env"
     env_file.write_text(
-        'ENABLE_MODEL_THINKING="false"\n'
-        'ENABLE_FABLE_THINKING="true"\n'
-        'ENABLE_OPUS_THINKING="true"\n'
-        "ENABLE_SONNET_THINKING=\n"
-        'ENABLE_HAIKU_THINKING="false"\n',
+        'REASONING_POLICY="off"\n'
+        'REASONING_FABLE="high"\n'
+        'REASONING_OPUS="client"\n'
+        'REASONING_SONNET="inherit"\n'
+        'REASONING_HAIKU="off"\n',
         encoding="utf-8",
     )
     env = os.environ.copy()
@@ -81,11 +81,11 @@ def test_per_model_thinking_config_e2e(smoke_config: SmokeConfig, tmp_path) -> N
         "from free_claude_code.config.settings import Settings; "
         "s=Settings(); "
         "r=ModelRouter(s); "
-        "print(r.resolve('claude-fable-5').thinking_enabled); "
-        "print(r.resolve('claude-opus-4-20250514').thinking_enabled); "
-        "print(r.resolve('claude-sonnet-4-20250514').thinking_enabled); "
-        "print(r.resolve('claude-haiku-4-20250514').thinking_enabled); "
-        "print(r.resolve('unknown-model').thinking_enabled)"
+        "print(r.resolve('claude-fable-5').reasoning_preference.value); "
+        "print(r.resolve('claude-opus-4-20250514').reasoning_preference.value); "
+        "print(r.resolve('claude-sonnet-4-20250514').reasoning_preference.value); "
+        "print(r.resolve('claude-haiku-4-20250514').reasoning_preference.value); "
+        "print(r.resolve('unknown-model').reasoning_preference.value)"
     )
     result = run_captured_text(
         cmd_python_c(script),
@@ -96,11 +96,11 @@ def test_per_model_thinking_config_e2e(smoke_config: SmokeConfig, tmp_path) -> N
     )
     assert result.returncode == 0, result.stderr
     assert result.stdout.splitlines() == [
-        "True",
-        "True",
-        "False",
-        "False",
-        "False",
+        "high",
+        "client",
+        "off",
+        "off",
+        "off",
     ]
 
 

smoke/product/test_nvidia_nim_cli_product_live.py

@@ -35,7 +35,7 @@ def test_nvidia_nim_cli_matrix_e2e(smoke_config: SmokeConfig, tmp_path: Path) ->
             env_overrides={
                 "MODEL": provider_model.full_model,
                 "MESSAGING_PLATFORM": "none",
-                "ENABLE_MODEL_THINKING": "true",
+                "REASONING_POLICY": "high",
                 "LOG_RAW_API_PAYLOADS": "true",
                 "LOG_RAW_SSE_EVENTS": "true",
             },

smoke/product/test_openrouter_free_cli_product_live.py

@@ -37,7 +37,7 @@ def test_openrouter_free_cli_matrix_e2e(
             env_overrides={
                 "MODEL": provider_model.full_model,
                 "MESSAGING_PLATFORM": "none",
-                "ENABLE_MODEL_THINKING": "true",
+                "REASONING_POLICY": "high",
                 "LOG_RAW_API_PAYLOADS": "true",
                 "LOG_RAW_SSE_EVENTS": "true",
             },

smoke/product/test_provider_product_live.py

@@ -4,6 +4,7 @@ import httpx
 import pytest
 
 from free_claude_code.application.routing import ModelRouter
+from free_claude_code.config.reasoning import ReasoningPreference
 from free_claude_code.core.anthropic.stream_contracts import (
     SSEEvent,
     parse_sse_lines,
@@ -101,8 +102,8 @@ def test_gemini_thought_signature_tool_continuation_e2e(
 def test_provider_reasoning_tool_continuation_e2e(
     smoke_config: SmokeConfig, provider_model: ProviderModel
 ) -> None:
-    if not _provider_smoke_thinking_enabled(smoke_config):
-        pytest.skip("the configured Claude route does not enable thinking")
+    if not _provider_smoke_reasoning_enabled(smoke_config):
+        pytest.skip("the configured Claude route disables reasoning")
     _run_provider_scenario(
         smoke_config, provider_model, _scenario_reasoning_tool_continuation
     )
@@ -267,11 +268,12 @@ def _tool_use_blocks_or_skip(
     return blocks
 
 
-def _provider_smoke_thinking_enabled(smoke_config: SmokeConfig) -> bool:
+def _provider_smoke_reasoning_enabled(smoke_config: SmokeConfig) -> bool:
     return (
         ModelRouter(smoke_config.settings)
         .resolve("claude-sonnet-4-5-20250929")
-        .thinking_enabled
+        .reasoning_preference
+        is not ReasoningPreference.OFF
     )
 
 

smoke/product/test_runtime_ownership_product_live.py

@@ -173,8 +173,21 @@ def _message_payload(*, stream: bool) -> dict[str, Any]:
 def _write_initial_managed_config(home: Path, upstream: FakeOpenAIUpstream) -> None:
     config_path = home / ".fcc" / ".env"
     config_path.parent.mkdir(parents=True, exist_ok=True)
+    template = "\n".join(
+        line
+        for line in load_env_template().splitlines()
+        if not line.startswith(
+            (
+                "REASONING_POLICY=",
+                "REASONING_FABLE=",
+                "REASONING_OPUS=",
+                "REASONING_SONNET=",
+                "REASONING_HAIKU=",
+            )
+        )
+    )
     config_path.write_text(
-        load_env_template()
+        template
         + "\n"
         + "\n".join(
             [
@@ -245,10 +258,19 @@ def test_provider_hot_swap_preserves_inflight_stream_e2e(
                     "MODEL_HAIKU",
                     "MODEL_OPUS",
                     "MODEL_SONNET",
+                    "REASONING_FABLE",
+                    "REASONING_HAIKU",
+                    "REASONING_OPUS",
+                    "REASONING_POLICY",
+                    "REASONING_SONNET",
                 },
             )
         )
 
+        managed_config = (home / ".fcc" / ".env").read_text(encoding="utf-8")
+        assert "REASONING_POLICY=off" in managed_config
+        assert "ENABLE_MODEL_THINKING" not in managed_config
+
         def consume_old_stream() -> None:
             try:
                 with httpx.stream(

src/free_claude_code/api/admin_static/admin.js

@@ -20,7 +20,7 @@ const VIEW_GROUPS = [
     id: "model_config",
     label: "Model Config",
     title: "Model Config",
-    sections: ["models", "thinking", "web_tools"],
+    sections: ["models", "reasoning", "web_tools"],
     containerId: "modelConfigSections",
   },
   {
@@ -308,21 +308,12 @@ function inputForField(field) {
     return input;
   }
 
-  if (field.type === "tri_boolean") {
-    const select = document.createElement("select");
-    [
-      ["", "Inherit"],
-      ["true", "Enabled"],
-      ["false", "Disabled"],
-    ].forEach(([value, label]) => select.appendChild(option(value, label)));
-    select.value = field.value || "";
-    return select;
-  }
-
   if (field.type === "select") {
     const select = document.createElement("select");
-    field.options.forEach((value) => select.appendChild(option(value, value)));
-    select.value = field.value || field.options[0] || "";
+    field.options.forEach((item) =>
+      select.appendChild(option(item.value, item.label)),
+    );
+    select.value = field.value || field.options[0]?.value || "";
     return select;
   }
 

src/free_claude_code/api/handlers/messages.py

@@ -47,6 +47,7 @@ from free_claude_code.core.anthropic import (
 )
 from free_claude_code.core.diagnostics import safe_exception_message
 from free_claude_code.core.failures import ExecutionFailure, find_execution_failure
+from free_claude_code.core.reasoning import ReasoningControl, ReasoningPolicy
 from free_claude_code.core.trace import trace_event
 
 
@@ -271,7 +272,7 @@ class MessagesHandler:
     ) -> RoutedMessagesRequest:
         if not is_safety_classifier_request(routed.request):
             return routed
-        changed = routed.resolved.thinking_enabled
+        changed = routed.reasoning.control is not ReasoningControl.OFF
         trace_event(
             stage="routing",
             event="free_claude_code.api.optimization.safety_classifier_no_thinking",
@@ -281,10 +282,7 @@ class MessagesHandler:
         )
         if not changed:
             return routed
-        return RoutedMessagesRequest(
-            request=routed.request,
-            resolved=replace(routed.resolved, thinking_enabled=False),
-        )
+        return replace(routed, reasoning=ReasoningPolicy.off())
 
     def _run_message_intercepts(
         self, routed: RoutedMessagesRequest

src/free_claude_code/application/execution.py

@@ -58,7 +58,7 @@ class ProviderExecutor:
         provider = self._provider_resolver(routed.resolved.provider_id)
         provider.preflight_stream(
             routed.request,
-            thinking_enabled=routed.resolved.thinking_enabled,
+            reasoning=routed.reasoning,
         )
 
         route_trace: dict[str, object] = {
@@ -70,7 +70,13 @@ class ProviderExecutor:
             "provider_model": routed.resolved.provider_model,
             "provider_model_ref": routed.resolved.provider_model_ref,
             "gateway_model": routed.request.model,
-            "thinking_enabled": routed.resolved.thinking_enabled,
+            "reasoning_control": routed.reasoning.control.value,
+            "reasoning_effort": (
+                routed.reasoning.effort.value
+                if routed.reasoning.effort is not None
+                else None
+            ),
+            "reasoning_budget_tokens": routed.reasoning.budget_tokens,
         }
         if wire_api == "responses":
             route_trace["wire_api"] = "responses"
@@ -107,7 +113,7 @@ class ProviderExecutor:
                     routed.request,
                     input_tokens=input_tokens,
                     request_id=request_id,
-                    thinking_enabled=routed.resolved.thinking_enabled,
+                    reasoning=routed.reasoning,
                 )
                 async for chunk in provider_stream:
                     yield chunk

src/free_claude_code/application/ports.py

@@ -6,6 +6,7 @@ from typing import Protocol
 
 from free_claude_code.config.settings import Settings
 from free_claude_code.core.anthropic import MessagesRequest
+from free_claude_code.core.reasoning import ReasoningPolicy
 
 from .model_metadata import ProviderModelInfo
 
@@ -17,7 +18,7 @@ class ProviderPort(Protocol):
         self,
         request: MessagesRequest,
         *,
-        thinking_enabled: bool,
+        reasoning: ReasoningPolicy,
     ) -> None: ...
 
     def stream_response(
@@ -26,7 +27,7 @@ class ProviderPort(Protocol):
         *,
         input_tokens: int,
         request_id: str,
-        thinking_enabled: bool,
+        reasoning: ReasoningPolicy,
     ) -> AsyncIterator[str]: ...
 
 

src/free_claude_code/application/reasoning.py

@@ -0,0 +1,99 @@
+"""Resolve client reasoning input and FCC configuration exactly once."""
+
+from collections.abc import Mapping
+from typing import Any
+
+from free_claude_code.config.reasoning import ReasoningPreference
+from free_claude_code.core.anthropic.models import MessagesRequest, ThinkingConfig
+from free_claude_code.core.reasoning import (
+    ReasoningControl,
+    ReasoningEffort,
+    ReasoningPolicy,
+)
+
+
+def resolve_reasoning_policy(
+    request: MessagesRequest,
+    preference: ReasoningPreference,
+) -> ReasoningPolicy:
+    """Apply one resolved configuration preference to the client request."""
+
+    if preference is ReasoningPreference.INHERIT:
+        raise ValueError("Reasoning preference must be resolved before application.")
+    if preference is ReasoningPreference.OFF:
+        return ReasoningPolicy.off()
+    if preference is not ReasoningPreference.CLIENT:
+        return ReasoningPolicy.on(effort=ReasoningEffort(preference.value))
+    return client_reasoning_policy(request)
+
+
+def client_reasoning_policy(request: MessagesRequest) -> ReasoningPolicy:
+    """Return the lossless reasoning intent expressed by one client request."""
+
+    budget_tokens = _positive_budget(request.thinking)
+    thinking_control = _thinking_control(
+        request.thinking,
+        budget_tokens=budget_tokens,
+    )
+    effort, effort_disables = _output_effort(request.output_config)
+
+    if effort_disables:
+        return ReasoningPolicy.off()
+    if thinking_control is ReasoningControl.OFF:
+        return ReasoningPolicy(
+            control=ReasoningControl.OFF,
+            effort=effort,
+        )
+    if thinking_control is ReasoningControl.ON or budget_tokens is not None:
+        return ReasoningPolicy.on(
+            effort=effort,
+            budget_tokens=budget_tokens,
+        )
+    return ReasoningPolicy(
+        control=ReasoningControl.DEFAULT,
+        effort=effort,
+    )
+
+
+def _thinking_control(
+    thinking: ThinkingConfig | None,
+    *,
+    budget_tokens: int | None,
+) -> ReasoningControl:
+    if thinking is None:
+        return ReasoningControl.DEFAULT
+    if thinking.type == "disabled" or (
+        "enabled" in thinking.model_fields_set and thinking.enabled is False
+    ):
+        return ReasoningControl.OFF
+    if (
+        thinking.type in {"adaptive", "enabled"}
+        or ("enabled" in thinking.model_fields_set and thinking.enabled is True)
+        or budget_tokens is not None
+    ):
+        return ReasoningControl.ON
+    return ReasoningControl.DEFAULT
+
+
+def _output_effort(value: Any) -> tuple[ReasoningEffort | None, bool]:
+    if not isinstance(value, Mapping):
+        return None, False
+    raw = value.get("effort")
+    if not isinstance(raw, str):
+        return None, False
+    normalized = raw.strip().lower()
+    if normalized == "none":
+        return None, True
+    try:
+        return ReasoningEffort(normalized), False
+    except ValueError:
+        return None, False
+
+
+def _positive_budget(thinking: ThinkingConfig | None) -> int | None:
+    if thinking is None:
+        return None
+    value = thinking.budget_tokens
+    if isinstance(value, int) and not isinstance(value, bool) and value > 0:
+        return value
+    return None

src/free_claude_code/application/routing.py

@@ -10,9 +10,20 @@ from free_claude_code.config.provider_catalog import (
     PROVIDER_CATALOG,
     SUPPORTED_PROVIDER_IDS,
 )
+from free_claude_code.config.reasoning import ReasoningPreference
 from free_claude_code.config.settings import Settings
 from free_claude_code.core.anthropic import MessagesRequest, TokenCountRequest
 from free_claude_code.core.gateway_model_ids import decode_gateway_model_id
+from free_claude_code.core.reasoning import ReasoningPolicy
+
+from .reasoning import resolve_reasoning_policy
+
+_ROUTE_SETTINGS = (
+    ("fable", "model_fable", "reasoning_fable"),
+    ("opus", "model_opus", "reasoning_opus"),
+    ("haiku", "model_haiku", "reasoning_haiku"),
+    ("sonnet", "model_sonnet", "reasoning_sonnet"),
+)
 
 
 @dataclass(frozen=True, slots=True)
@@ -21,13 +32,14 @@ class ResolvedModel:
     provider_id: str
     provider_model: str
     provider_model_ref: str
-    thinking_enabled: bool
+    reasoning_preference: ReasoningPreference
 
 
 @dataclass(frozen=True, slots=True)
 class RoutedMessagesRequest:
     request: MessagesRequest
     resolved: ResolvedModel
+    reasoning: ReasoningPolicy
 
 
 @dataclass(frozen=True, slots=True)
@@ -46,31 +58,31 @@ class ModelRouter:
         (
             direct_provider_id,
             direct_provider_model,
-            force_thinking_enabled,
+            force_reasoning_off,
         ) = self._direct_provider_model(claude_model_name)
         if direct_provider_id is not None and direct_provider_model is not None:
-            thinking_enabled = (
-                force_thinking_enabled
-                if force_thinking_enabled is not None
-                else self._resolve_thinking(direct_provider_model)
+            reasoning_preference = (
+                ReasoningPreference.OFF
+                if force_reasoning_off
+                else self._settings.reasoning_policy
             )
             logger.debug(
-                "MODEL DIRECT: '{}' -> provider='{}' model='{}' thinking={}",
+                "MODEL DIRECT: '{}' -> provider='{}' model='{}' reasoning={}",
                 claude_model_name,
                 direct_provider_id,
                 direct_provider_model,
-                thinking_enabled,
+                reasoning_preference.value,
             )
             return ResolvedModel(
                 original_model=claude_model_name,
                 provider_id=direct_provider_id,
                 provider_model=direct_provider_model,
                 provider_model_ref=claude_model_name,
-                thinking_enabled=thinking_enabled,
+                reasoning_preference=reasoning_preference,
             )
 
         provider_model_ref = self._resolve_model_ref(claude_model_name)
-        thinking_enabled = self._resolve_thinking(claude_model_name)
+        reasoning_preference = self._resolve_reasoning_preference(claude_model_name)
         provider_id = parse_provider_type(provider_model_ref)
         self._validate_provider_id(provider_id)
         provider_model = parse_model_name(provider_model_ref)
@@ -83,7 +95,7 @@ class ModelRouter:
             provider_id=provider_id,
             provider_model=provider_model,
             provider_model_ref=provider_model_ref,
-            thinking_enabled=thinking_enabled,
+            reasoning_preference=reasoning_preference,
         )
 
     @staticmethod
@@ -93,53 +105,55 @@ class ModelRouter:
 
     def _direct_provider_model(
         self, model_name: str
-    ) -> tuple[str | None, str | None, bool | None]:
+    ) -> tuple[str | None, str | None, bool]:
         decoded = decode_gateway_model_id(model_name)
         if decoded is not None:
             if decoded.provider_id not in SUPPORTED_PROVIDER_IDS:
-                return None, None, None
+                return None, None, False
             return (
                 decoded.provider_id,
                 decoded.provider_model,
-                decoded.force_thinking_enabled,
+                decoded.force_reasoning_off,
             )
 
         provider_id, separator, provider_model = model_name.partition("/")
         if not separator:
-            return None, None, None
+            return None, None, False
         if provider_id not in SUPPORTED_PROVIDER_IDS:
-            return None, None, None
+            return None, None, False
         if not provider_model:
-            return None, None, None
-        return provider_id, provider_model, None
+            return None, None, False
+        return provider_id, provider_model, False
 
     def _resolve_model_ref(self, claude_model_name: str) -> str:
         """Resolve a Claude model name to the configured provider/model ref."""
 
-        name_lower = claude_model_name.lower()
-        if "fable" in name_lower and self._settings.model_fable is not None:
-            return self._settings.model_fable
-        if "opus" in name_lower and self._settings.model_opus is not None:
-            return self._settings.model_opus
-        if "haiku" in name_lower and self._settings.model_haiku is not None:
-            return self._settings.model_haiku
-        if "sonnet" in name_lower and self._settings.model_sonnet is not None:
-            return self._settings.model_sonnet
+        route = self._matched_route(claude_model_name)
+        if route is not None:
+            model = getattr(self._settings, route[1])
+            if isinstance(model, str):
+                return model
         return self._settings.model
 
-    def _resolve_thinking(self, claude_model_name: str) -> bool:
-        """Resolve whether thinking is enabled for an incoming Claude model name."""
+    def _resolve_reasoning_preference(
+        self, claude_model_name: str
+    ) -> ReasoningPreference:
+        """Resolve a route override without inspecting the provider model."""
 
-        name_lower = claude_model_name.lower()
-        if "fable" in name_lower and self._settings.enable_fable_thinking is not None:
-            return self._settings.enable_fable_thinking
-        if "opus" in name_lower and self._settings.enable_opus_thinking is not None:
-            return self._settings.enable_opus_thinking
-        if "haiku" in name_lower and self._settings.enable_haiku_thinking is not None:
-            return self._settings.enable_haiku_thinking
-        if "sonnet" in name_lower and self._settings.enable_sonnet_thinking is not None:
-            return self._settings.enable_sonnet_thinking
-        return self._settings.enable_model_thinking
+        route = self._matched_route(claude_model_name)
+        if route is not None:
+            preference = getattr(self._settings, route[2])
+            if preference is not ReasoningPreference.INHERIT:
+                return preference
+        return self._settings.reasoning_policy
+
+    @staticmethod
+    def _matched_route(model_name: str) -> tuple[str, str, str] | None:
+        normalized = model_name.lower()
+        return next(
+            (route for route in _ROUTE_SETTINGS if route[0] in normalized),
+            None,
+        )
 
     def resolve_messages_request(
         self, request: MessagesRequest
@@ -148,7 +162,14 @@ class ModelRouter:
         resolved = self.resolve(request.model)
         routed = request.model_copy(deep=True)
         routed.model = resolved.provider_model
-        return RoutedMessagesRequest(request=routed, resolved=resolved)
+        return RoutedMessagesRequest(
+            request=routed,
+            resolved=resolved,
+            reasoning=resolve_reasoning_policy(
+                routed,
+                resolved.reasoning_preference,
+            ),
+        )
 
     def resolve_token_count_request(
         self, request: TokenCountRequest

src/free_claude_code/cli/commands.py

@@ -13,7 +13,7 @@ import uvicorn
 from free_claude_code.cli.launchers.common import preflight_proxy
 from free_claude_code.cli.process_registry import kill_all_best_effort
 from free_claude_code.config.env_migrations import (
-    explicit_env_file_huggingface_warning,
+    explicit_env_file_migration_warning,
     migrate_owned_env_files,
 )
 from free_claude_code.config.env_template import load_env_template
@@ -148,6 +148,6 @@ def _migrate_config_env_keys() -> tuple[Path, ...]:
     """Apply dotenv key migrations before Settings loads config."""
 
     migrated = migrate_owned_env_files()
-    if warning := explicit_env_file_huggingface_warning(os.environ):
+    if warning := explicit_env_file_migration_warning(os.environ):
         print(warning, file=sys.stderr)
     return migrated

src/free_claude_code/config/admin/manifest.py

@@ -4,6 +4,11 @@ from collections.abc import Iterable
 from dataclasses import dataclass
 from typing import Literal
 
+from free_claude_code.config.reasoning import (
+    ROOT_REASONING_PREFERENCES,
+    ROUTE_REASONING_PREFERENCES,
+    ReasoningPreference,
+)
 from free_claude_code.config.settings import Settings
 
 from .provider_manifest import provider_field_specs
@@ -13,7 +18,6 @@ FieldType = Literal[
     "secret",
     "number",
     "boolean",
-    "tri_boolean",
     "model",
     "optional_model",
     "select",
@@ -41,7 +45,7 @@ class ConfigFieldSpec:
     field_type: FieldType = "text"
     settings_attr: str | None = None
     default: str = ""
-    options: tuple[str, ...] = ()
+    options: tuple[str | ConfigOptionSpec, ...] = ()
     secret: bool = False
     advanced: bool = False
     restart_required: bool = False
@@ -49,6 +53,33 @@ class ConfigFieldSpec:
     description: str = ""
 
 
+@dataclass(frozen=True, slots=True)
+class ConfigOptionSpec:
+    """A persisted option value and its user-facing label."""
+
+    value: str
+    label: str
+
+
+def _reasoning_options(
+    preferences: tuple[ReasoningPreference, ...],
+) -> tuple[ConfigOptionSpec, ...]:
+    labels = {
+        ReasoningPreference.INHERIT: "Inherit",
+        ReasoningPreference.OFF: "Off",
+        ReasoningPreference.CLIENT: "From client",
+        ReasoningPreference.LOW: "Low",
+        ReasoningPreference.MEDIUM: "Medium",
+        ReasoningPreference.HIGH: "High",
+        ReasoningPreference.XHIGH: "X-High",
+        ReasoningPreference.MAX: "Max",
+    }
+    return tuple(
+        ConfigOptionSpec(preference.value, labels[preference])
+        for preference in preferences
+    )
+
+
 SECTIONS: tuple[ConfigSectionSpec, ...] = (
     ConfigSectionSpec(
         "providers",
@@ -61,9 +92,9 @@ SECTIONS: tuple[ConfigSectionSpec, ...] = (
         "Search discovered provider models or enter a provider/model slug.",
     ),
     ConfigSectionSpec(
-        "thinking",
-        "Thinking",
-        "Global and tier-specific thinking behavior.",
+        "reasoning",
+        "Reasoning",
+        "Client reasoning policy and route-specific overrides.",
     ),
     ConfigSectionSpec(
         "runtime",
@@ -143,44 +174,53 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
         description="Select None to use the Default Model for Haiku requests.",
     ),
     ConfigFieldSpec(
-        "ENABLE_MODEL_THINKING",
-        "Enable Thinking",
-        "thinking",
-        "boolean",
-        settings_attr="enable_model_thinking",
-        default="true",
-    ),
-    ConfigFieldSpec(
-        "ENABLE_FABLE_THINKING",
-        "Fable Thinking",
-        "thinking",
-        "tri_boolean",
-        settings_attr="enable_fable_thinking",
-        description="Blank inherits Enable Thinking.",
+        "REASONING_POLICY",
+        "Reasoning Policy",
+        "reasoning",
+        "select",
+        settings_attr="reasoning_policy",
+        default="client",
+        options=_reasoning_options(ROOT_REASONING_PREFERENCES),
+        description=(
+            "From client preserves CLI effort. Providers translate only the controls "
+            "their API supports."
+        ),
+    ),
+    ConfigFieldSpec(
+        "REASONING_FABLE",
+        "Fable Reasoning",
+        "reasoning",
+        "select",
+        settings_attr="reasoning_fable",
+        default="inherit",
+        options=_reasoning_options(ROUTE_REASONING_PREFERENCES),
     ),
     ConfigFieldSpec(
-        "ENABLE_OPUS_THINKING",
-        "Opus Thinking",
-        "thinking",
-        "tri_boolean",
-        settings_attr="enable_opus_thinking",
-        description="Blank inherits Enable Thinking.",
+        "REASONING_OPUS",
+        "Opus Reasoning",
+        "reasoning",
+        "select",
+        settings_attr="reasoning_opus",
+        default="inherit",
+        options=_reasoning_options(ROUTE_REASONING_PREFERENCES),
     ),
     ConfigFieldSpec(
-        "ENABLE_SONNET_THINKING",
-        "Sonnet Thinking",
-        "thinking",
-        "tri_boolean",
-        settings_attr="enable_sonnet_thinking",
-        description="Blank inherits Enable Thinking.",
+        "REASONING_SONNET",
+        "Sonnet Reasoning",
+        "reasoning",
+        "select",
+        settings_attr="reasoning_sonnet",
+        default="inherit",
+        options=_reasoning_options(ROUTE_REASONING_PREFERENCES),
     ),
     ConfigFieldSpec(
-        "ENABLE_HAIKU_THINKING",
-        "Haiku Thinking",
-        "thinking",
-        "tri_boolean",
-        settings_attr="enable_haiku_thinking",
-        description="Blank inherits Enable Thinking.",
+        "REASONING_HAIKU",
+        "Haiku Reasoning",
+        "reasoning",
+        "select",
+        settings_attr="reasoning_haiku",
+        default="inherit",
+        options=_reasoning_options(ROUTE_REASONING_PREFERENCES),
     ),
     ConfigFieldSpec(
         "ANTHROPIC_AUTH_TOKEN",

src/free_claude_code/config/admin/values.py

@@ -5,7 +5,13 @@ from typing import Any
 
 from free_claude_code.config.paths import managed_env_path
 
-from .manifest import FIELD_BY_KEY, FIELDS, SECTIONS, ConfigFieldSpec
+from .manifest import (
+    FIELD_BY_KEY,
+    FIELDS,
+    SECTIONS,
+    ConfigFieldSpec,
+    ConfigOptionSpec,
+)
 from .sources import (
     configured_env_files,
     dotenv_values_from_file,
@@ -88,7 +94,14 @@ def load_config_response() -> dict[str, Any]:
                 "advanced": field.advanced,
                 "restart_required": field.restart_required,
                 "session_sensitive": field.session_sensitive,
-                "options": list(field.options),
+                "options": [
+                    (
+                        {"value": option.value, "label": option.label}
+                        if isinstance(option, ConfigOptionSpec)
+                        else {"value": option, "label": option}
+                    )
+                    for option in field.options
+                ],
                 "description": field.description,
             }
         )

src/free_claude_code/config/env_migrations.py

@@ -22,6 +22,7 @@ class EnvKeyMigration:
 
     old_key: str
     new_key: str
+    value_map: tuple[tuple[str, str], ...] = ()
 
 
 HUGGINGFACE_TOKEN_MIGRATION = EnvKeyMigration(
@@ -29,32 +30,67 @@ HUGGINGFACE_TOKEN_MIGRATION = EnvKeyMigration(
     new_key=HUGGINGFACE_API_KEY_ENV,
 )
 
+_LEGACY_TRUE_VALUES = ("1", "true", "t", "on", "yes", "y")
+_LEGACY_FALSE_VALUES = ("0", "false", "f", "off", "no", "n")
+_LEGACY_REASONING_BOOLEAN_MAP = (
+    *((value, "client") for value in _LEGACY_TRUE_VALUES),
+    *((value, "off") for value in _LEGACY_FALSE_VALUES),
+)
+
+REASONING_MIGRATIONS = (
+    EnvKeyMigration(
+        "ENABLE_MODEL_THINKING",
+        "REASONING_POLICY",
+        _LEGACY_REASONING_BOOLEAN_MAP,
+    ),
+    *(
+        EnvKeyMigration(
+            f"ENABLE_{route}_THINKING",
+            f"REASONING_{route}",
+            (("", "inherit"), *_LEGACY_REASONING_BOOLEAN_MAP),
+        )
+        for route in ("FABLE", "OPUS", "SONNET", "HAIKU")
+    ),
+)
+
+ENV_MIGRATIONS = (HUGGINGFACE_TOKEN_MIGRATION, *REASONING_MIGRATIONS)
+
 
 def migrate_owned_env_files() -> tuple[Path, ...]:
     """Apply key migrations to repo and managed dotenv files."""
 
-    return tuple(
-        path.resolve()
-        for path in _unique_paths((repo_env_path(), managed_env_path()))
-        if migrate_env_key_in_file(path, HUGGINGFACE_TOKEN_MIGRATION)
-    )
+    changed_paths: list[Path] = []
+    for path in _unique_paths((repo_env_path(), managed_env_path())):
+        changed = False
+        for migration in ENV_MIGRATIONS:
+            changed = migrate_env_key_in_file(path, migration) or changed
+        if changed:
+            changed_paths.append(path.resolve())
+    return tuple(changed_paths)
 
 
-def explicit_env_file_huggingface_warning(
+def explicit_env_file_migration_warning(
     env: Mapping[str, str] | None = None,
 ) -> str | None:
-    """Return a warning when an explicit env file still uses ``HF_TOKEN``."""
+    """Return a warning when an explicit env file uses a retired setting."""
 
     path = explicit_env_path(env)
     if path is None or not path.is_file():
         return None
     text = path.read_text(encoding="utf-8")
-    if not env_text_needs_migration(text, HUGGINGFACE_TOKEN_MIGRATION):
+    pending = tuple(
+        migration
+        for migration in ENV_MIGRATIONS
+        if env_text_needs_migration(text, migration)
+    )
+    if not pending:
         return None
+    renames = ", ".join(
+        f"{migration.old_key} to {migration.new_key}" for migration in pending
+    )
     return (
-        f"{LEGACY_HUGGINGFACE_TOKEN_ENV} is set in explicit FCC_ENV_FILE {path}. "
-        f"Rename it to {HUGGINGFACE_API_KEY_ENV}; explicit env files are not "
-        "rewritten automatically."
+        f"Explicit FCC_ENV_FILE {path} uses retired settings. Rename {renames}; "
+        "explicit env files are not rewritten automatically."
     )
 
 
@@ -86,9 +122,12 @@ def migrate_env_key_in_text(
         match = _DOTENV_ASSIGNMENT_RE.match(line)
         if match is None or match.group("key") != migration.old_key:
             continue
+        remainder = line[match.end() :]
+        if migration.value_map:
+            remainder = _mapped_value(remainder, migration.value_map)
         lines[index] = (
             f"{match.group('prefix')}{migration.new_key}{match.group('suffix')}"
-            f"{line[match.end() :]}"
+            f"{remainder}"
         )
         changed = True
     if not changed:
@@ -114,6 +153,20 @@ def _defines_key(text: str, key: str) -> bool:
     return False
 
 
+def _mapped_value(value: str, mapping: tuple[tuple[str, str], ...]) -> str:
+    """Map a simple dotenv value while preserving comments and line endings."""
+
+    line = value.rstrip("\r\n")
+    newline = value[len(line) :]
+    raw_value, separator, comment = line.partition("#")
+    normalized = raw_value.strip().strip("'\"").lower()
+    replacement = dict(mapping).get(normalized)
+    if replacement is None:
+        return value
+    suffix = f" #{comment}" if separator else ""
+    return f"{replacement}{suffix}{newline}"
+
+
 def _unique_paths(paths: tuple[Path, ...]) -> tuple[Path, ...]:
     seen: set[Path] = set()
     unique: list[Path] = []

src/free_claude_code/config/reasoning.py

@@ -0,0 +1,24 @@
+"""User-configurable reasoning policy values."""
+
+from enum import StrEnum
+
+
+class ReasoningPreference(StrEnum):
+    """Configuration choice applied before provider translation."""
+
+    INHERIT = "inherit"
+    OFF = "off"
+    CLIENT = "client"
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    XHIGH = "xhigh"
+    MAX = "max"
+
+
+ROOT_REASONING_PREFERENCES = tuple(
+    preference
+    for preference in ReasoningPreference
+    if preference is not ReasoningPreference.INHERIT
+)
+ROUTE_REASONING_PREFERENCES = tuple(ReasoningPreference)

src/free_claude_code/config/settings.py

@@ -14,6 +14,7 @@ from .env_files import (
 )
 from .nim import NimSettings
 from .provider_catalog import SUPPORTED_PROVIDER_IDS
+from .reasoning import ReasoningPreference
 
 
 class Settings(BaseSettings):
@@ -167,20 +168,25 @@ class Settings(BaseSettings):
     provider_max_concurrency: int = Field(
         default=5, validation_alias="PROVIDER_MAX_CONCURRENCY"
     )
-    enable_model_thinking: bool = Field(
-        default=True, validation_alias="ENABLE_MODEL_THINKING"
+    reasoning_policy: ReasoningPreference = Field(
+        default=ReasoningPreference.CLIENT,
+        validation_alias="REASONING_POLICY",
     )
-    enable_fable_thinking: bool | None = Field(
-        default=None, validation_alias="ENABLE_FABLE_THINKING"
+    reasoning_fable: ReasoningPreference = Field(
+        default=ReasoningPreference.INHERIT,
+        validation_alias="REASONING_FABLE",
     )
-    enable_opus_thinking: bool | None = Field(
-        default=None, validation_alias="ENABLE_OPUS_THINKING"
+    reasoning_opus: ReasoningPreference = Field(
+        default=ReasoningPreference.INHERIT,
+        validation_alias="REASONING_OPUS",
     )
-    enable_sonnet_thinking: bool | None = Field(
-        default=None, validation_alias="ENABLE_SONNET_THINKING"
+    reasoning_sonnet: ReasoningPreference = Field(
+        default=ReasoningPreference.INHERIT,
+        validation_alias="REASONING_SONNET",
     )
-    enable_haiku_thinking: bool | None = Field(
-        default=None, validation_alias="ENABLE_HAIKU_THINKING"
+    reasoning_haiku: ReasoningPreference = Field(
+        default=ReasoningPreference.INHERIT,
+        validation_alias="REASONING_HAIKU",
     )
 
     # ==================== HTTP Client Timeouts ====================
@@ -301,10 +307,6 @@ class Settings(BaseSettings):
         "model_opus",
         "model_sonnet",
         "model_haiku",
-        "enable_fable_thinking",
-        "enable_opus_thinking",
-        "enable_sonnet_thinking",
-        "enable_haiku_thinking",
         mode="before",
     )
     @classmethod
@@ -329,6 +331,15 @@ class Settings(BaseSettings):
             raise ValueError(f"LOG_LEVEL must be one of {sorted(valid)}, got {v!r}")
         return upper
 
+    @field_validator("reasoning_policy")
+    @classmethod
+    def validate_root_reasoning_policy(
+        cls, value: ReasoningPreference
+    ) -> ReasoningPreference:
+        if value is ReasoningPreference.INHERIT:
+            raise ValueError("REASONING_POLICY cannot inherit")
+        return value
+
     @field_validator("whisper_device")
     @classmethod
     def validate_whisper_device(cls, v: str) -> str:

src/free_claude_code/core/__init__.py

@@ -1 +1,15 @@
 """Neutral shared application core."""
+
+from .reasoning import (
+    DEFAULT_REASONING_POLICY,
+    ReasoningControl,
+    ReasoningEffort,
+    ReasoningPolicy,
+)
+
+__all__ = [
+    "DEFAULT_REASONING_POLICY",
+    "ReasoningControl",
+    "ReasoningEffort",
+    "ReasoningPolicy",
+]

src/free_claude_code/core/anthropic/request_snapshot.py

@@ -28,7 +28,6 @@ def anthropic_request_snapshot(
             "stop_sequences",
             "metadata",
             "stream",
-            "thinking_enabled",
         )
         if key in data and data[key] is not None
     }

src/free_claude_code/core/gateway_model_ids.py

@@ -14,7 +14,7 @@ NO_THINKING_GATEWAY_MODEL_ID_PREFIX = "claude-3-freecc-no-thinking"
 class DecodedGatewayModelId:
     provider_id: str
     provider_model: str
-    force_thinking_enabled: bool | None = None
+    force_reasoning_off: bool = False
 
 
 def gateway_model_id(provider_model_ref: str) -> str:
@@ -33,11 +33,10 @@ def decode_gateway_model_id(model_name: str) -> DecodedGatewayModelId | None:
     if not separator:
         return None
 
-    force_thinking_enabled: bool | None
     if prefix == GATEWAY_MODEL_ID_PREFIX:
-        force_thinking_enabled = None
+        force_reasoning_off = False
     elif prefix == NO_THINKING_GATEWAY_MODEL_ID_PREFIX:
-        force_thinking_enabled = False
+        force_reasoning_off = True
     else:
         return None
 
@@ -48,5 +47,5 @@ def decode_gateway_model_id(model_name: str) -> DecodedGatewayModelId | None:
     return DecodedGatewayModelId(
         provider_id=provider_id,
         provider_model=provider_model,
-        force_thinking_enabled=force_thinking_enabled,
+        force_reasoning_off=force_reasoning_off,
     )

src/free_claude_code/core/openai_responses/input.py

@@ -10,7 +10,7 @@ from .models import OpenAIResponsesRequest
 from .reasoning import (
     combine_reasoning,
     reasoning_text_from_item,
-    responses_reasoning_to_thinking,
+    responses_reasoning_to_output_config,
 )
 from .tools import (
     call_id_from_item,
@@ -65,8 +65,8 @@ def convert_request_to_anthropic_payload(
     if request.metadata is not None:
         payload["metadata"] = request.metadata
 
-    if thinking := responses_reasoning_to_thinking(request.reasoning):
-        payload["thinking"] = thinking
+    if output_config := responses_reasoning_to_output_config(request.reasoning):
+        payload["output_config"] = output_config
 
     raw_tool_choice = request.tool_choice
     tools = convert_tools(request.tools)

src/free_claude_code/core/openai_responses/reasoning.py

@@ -32,13 +32,13 @@ def combine_reasoning(existing: str | None, addition: str | None) -> str | None:
     return f"{existing}\n{addition}"
 
 
-def responses_reasoning_to_thinking(value: Any) -> dict[str, Any] | None:
+def responses_reasoning_to_output_config(value: Any) -> dict[str, Any] | None:
+    """Preserve the client's named effort for application-level resolution."""
     if not isinstance(value, Mapping):
         return None
-    if value.get("effort") == "none":
-        return {"type": "disabled", "enabled": False}
-    if any(item is not None for item in value.values()):
-        return {"type": "enabled", "enabled": True}
+    effort = value.get("effort")
+    if isinstance(effort, str) and effort.strip():
+        return {"effort": effort.strip().lower()}
     return None
 
 

src/free_claude_code/core/reasoning.py

@@ -0,0 +1,93 @@
+"""Provider-neutral reasoning intent."""
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class ReasoningControl(StrEnum):
+    """Whether a request explicitly controls reasoning computation."""
+
+    DEFAULT = "default"
+    OFF = "off"
+    ON = "on"
+
+
+class ReasoningEffort(StrEnum):
+    """Named reasoning effort understood at the FCC application boundary."""
+
+    MINIMAL = "minimal"
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    XHIGH = "xhigh"
+    MAX = "max"
+
+
+@dataclass(frozen=True, slots=True)
+class ReasoningPolicy:
+    """Resolved client and configuration intent passed to one provider.
+
+    ``control`` and ``effort`` remain independent because clients may set an
+    overall effort while separately disabling extended thinking. Providers
+    translate the representable subset without changing the original intent.
+    """
+
+    control: ReasoningControl = ReasoningControl.DEFAULT
+    effort: ReasoningEffort | None = None
+    budget_tokens: int | None = None
+
+    def __post_init__(self) -> None:
+        if self.budget_tokens is not None and (
+            not isinstance(self.budget_tokens, int)
+            or isinstance(self.budget_tokens, bool)
+            or self.budget_tokens <= 0
+        ):
+            raise ValueError("Reasoning budget must be a positive integer.")
+        if self.budget_tokens is not None and self.control is not ReasoningControl.ON:
+            raise ValueError("A reasoning budget requires reasoning control to be on.")
+
+    @classmethod
+    def provider_default(cls) -> ReasoningPolicy:
+        """Leave reasoning computation to the provider."""
+
+        return cls()
+
+    @classmethod
+    def off(cls) -> ReasoningPolicy:
+        """Explicitly disable reasoning computation and output."""
+
+        return cls(control=ReasoningControl.OFF)
+
+    @classmethod
+    def on(
+        cls,
+        *,
+        effort: ReasoningEffort | None = None,
+        budget_tokens: int | None = None,
+    ) -> ReasoningPolicy:
+        """Explicitly enable reasoning with optional client controls."""
+
+        return cls(
+            control=ReasoningControl.ON,
+            effort=effort,
+            budget_tokens=budget_tokens,
+        )
+
+    @property
+    def output_enabled(self) -> bool:
+        """Return whether provider reasoning may be exposed to the client."""
+
+        return self.control is not ReasoningControl.OFF
+
+    @property
+    def requests_reasoning(self) -> bool:
+        """Return whether the request explicitly asks the provider to reason."""
+
+        return self.control is not ReasoningControl.OFF and (
+            self.control is ReasoningControl.ON
+            or self.effort is not None
+            or self.budget_tokens is not None
+        )
+
+
+DEFAULT_REASONING_POLICY = ReasoningPolicy.provider_default()

src/free_claude_code/providers/base.py

@@ -13,6 +13,7 @@ from free_claude_code.core.diagnostics import (
     exception_cause_types,
     redacted_exception_traceback,
 )
+from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
 from free_claude_code.core.trace import trace_event
 from free_claude_code.providers.model_listing import model_infos_from_ids
 
@@ -33,7 +34,6 @@ class ProviderConfig:
     http_read_timeout: float = 300.0
     http_write_timeout: float = 10.0
     http_connect_timeout: float = HTTP_CONNECT_TIMEOUT_DEFAULT
-    enable_thinking: bool = True
     proxy: str = ""
     log_raw_sse_events: bool = False
     log_api_error_tracebacks: bool = False
@@ -45,27 +45,12 @@ class BaseProvider(ABC):
     def __init__(self, config: ProviderConfig):
         self._config = config
 
-    def _is_thinking_enabled(
-        self, request: MessagesRequest, thinking_enabled: bool | None = None
-    ) -> bool:
-        """Return whether thinking should be enabled for this request."""
-        thinking = request.thinking
-        config_enabled = (
-            self._config.enable_thinking
-            if thinking_enabled is None
-            else thinking_enabled
-        )
-        request_enabled = True
-        if thinking is not None:
-            if "enabled" in thinking.model_fields_set and thinking.enabled is not None:
-                request_enabled = thinking.enabled
-            if thinking.type == "disabled":
-                request_enabled = False
-        return config_enabled and request_enabled
-
     @abstractmethod
     def preflight_stream(
-        self, request: MessagesRequest, *, thinking_enabled: bool | None = None
+        self,
+        request: MessagesRequest,
+        *,
+        reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
     ) -> None:
         """Validate the upstream request before opening an SSE stream."""
 
@@ -131,6 +116,6 @@ class BaseProvider(ABC):
         input_tokens: int = 0,
         *,
         request_id: str | None = None,
-        thinking_enabled: bool | None = None,
+        reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
     ) -> AsyncIterator[str]:
         """Stream response in Anthropic SSE format."""

src/free_claude_code/providers/cloudflare/client.py

@@ -10,7 +10,7 @@ import httpx
 from free_claude_code.application.errors import ApplicationUnavailableError
 from free_claude_code.application.model_metadata import ProviderModelInfo
 from free_claude_code.config.provider_catalog import CLOUDFLARE_AI_REST_ROOT
-from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.anthropic import ReasoningReplayMode
 from free_claude_code.providers.base import ProviderConfig
 from free_claude_code.providers.http import maybe_await_aclose
 from free_claude_code.providers.model_listing import (
@@ -19,19 +19,22 @@ from free_claude_code.providers.model_listing import (
     model_infos_from_ids,
 )
 from free_claude_code.providers.openai_chat import (
+    ChatTemplateReasoning,
     OpenAIChatProfile,
     OpenAIChatProvider,
     OpenAIChatRequestPolicy,
-    build_openai_chat_request_body,
+    validate_extra_body_does_not_override_canonical_fields,
 )
 from free_claude_code.providers.rate_limit import ProviderRateLimiter
 
 _REQUEST_POLICY = OpenAIChatRequestPolicy(
     provider_name="CLOUDFLARE",
+    reasoning_replay=ReasoningReplayMode.REASONING_CONTENT,
     include_extra_body=True,
+    extra_body_validator=validate_extra_body_does_not_override_canonical_fields,
     max_tokens_field="max_completion_tokens",
 )
-_PROFILE = OpenAIChatProfile(_REQUEST_POLICY)
+_PROFILE = OpenAIChatProfile(_REQUEST_POLICY, ChatTemplateReasoning())
 
 
 def cloudflare_ai_base_url(api_root: str | None, account_id: str) -> str:
@@ -118,22 +121,12 @@ class CloudflareProvider(OpenAIChatProvider):
         finally:
             await maybe_await_aclose(response)
 
-    def _build_request_body(
-        self, request: MessagesRequest, thinking_enabled: bool | None = None
-    ) -> dict:
-        return build_openai_chat_request_body(
-            request,
-            thinking_enabled=self._is_thinking_enabled(request, thinking_enabled),
-            policy=_REQUEST_POLICY,
-            postprocessors=(_apply_cloudflare_request_quirks,),
-        )
-
     def _handle_extra_reasoning(
-        self, delta: Any, ledger: Any, *, thinking_enabled: bool
+        self, delta: Any, ledger: Any, *, output_reasoning: bool
     ) -> Iterator[str]:
         """Map Cloudflare's ``reasoning`` delta field to Anthropic thinking."""
         reasoning = _cloudflare_reasoning(delta)
-        if not thinking_enabled or not reasoning:
+        if not output_reasoning or not reasoning:
             return
         yield from ledger.ensure_thinking_block()
         yield ledger.emit_thinking_delta(reasoning)
@@ -142,18 +135,6 @@ class CloudflareProvider(OpenAIChatProvider):
         return {"Authorization": f"Bearer {self._api_key}"}
 
 
-def _apply_cloudflare_request_quirks(
-    body: dict[str, Any], _request: MessagesRequest, thinking_enabled: bool
-) -> None:
-    """Attach Cloudflare Workers AI chat-template thinking control."""
-    extra_body = body.setdefault("extra_body", {})
-    if not isinstance(extra_body, dict):
-        return
-    chat_template_kwargs = extra_body.setdefault("chat_template_kwargs", {})
-    if isinstance(chat_template_kwargs, dict):
-        chat_template_kwargs.setdefault("thinking", thinking_enabled)
-
-
 def _cloudflare_reasoning(delta: Any) -> str | None:
     reasoning = getattr(delta, "reasoning", None)
     if isinstance(reasoning, str) and reasoning:

src/free_claude_code/providers/deepseek/client.py

@@ -3,18 +3,22 @@
 from typing import Any
 
 from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
 from free_claude_code.providers.base import ProviderConfig
 from free_claude_code.providers.openai_chat import (
+    NO_REASONING,
     OpenAIChatProfile,
     OpenAIChatProvider,
-    OpenAIChatRequestPolicy,
     usage_int,
 )
 from free_claude_code.providers.rate_limit import ProviderRateLimiter
 
-from .compat import build_deepseek_request_body
+from .compat import DEEPSEEK_REQUEST_POLICY, build_deepseek_request_body
 
-_PROFILE = OpenAIChatProfile(OpenAIChatRequestPolicy(provider_name="DEEPSEEK"))
+_PROFILE = OpenAIChatProfile(
+    DEEPSEEK_REQUEST_POLICY,
+    NO_REASONING,
+)
 
 
 class DeepSeekProvider(OpenAIChatProvider):
@@ -28,11 +32,14 @@ class DeepSeekProvider(OpenAIChatProvider):
         )
 
     def _build_request_body(
-        self, request: MessagesRequest, thinking_enabled: bool | None = None
+        self,
+        request: MessagesRequest,
+        *,
+        reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
     ) -> dict:
         return build_deepseek_request_body(
             request,
-            thinking_enabled=self._is_thinking_enabled(request, thinking_enabled),
+            reasoning=reasoning,
         )
 
     def _anthropic_usage_fields(self, usage_info: Any) -> dict[str, int]:

src/free_claude_code/providers/deepseek/compat.py

@@ -8,17 +8,24 @@ from loguru import logger
 from free_claude_code.application.errors import InvalidRequestError
 from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
 from free_claude_code.core.anthropic import (
+    ReasoningReplayMode,
     dump_messages_request,
     serialize_tool_result_content,
 )
 from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.reasoning import (
+    ReasoningControl,
+    ReasoningEffort,
+    ReasoningPolicy,
+)
 from free_claude_code.providers.openai_chat import (
     OpenAIChatRequestPolicy,
     build_openai_chat_request_body,
 )
 
-_REQUEST_POLICY = OpenAIChatRequestPolicy(
+DEEPSEEK_REQUEST_POLICY = OpenAIChatRequestPolicy(
     provider_name="DEEPSEEK",
+    reasoning_replay=ReasoningReplayMode.REASONING_CONTENT,
     include_extra_body=True,
 )
 
@@ -39,7 +46,7 @@ _OMITTED_ATTACHMENT_BLOCK = {"type": "text", "text": _OMITTED_ATTACHMENT_TEXT}
 
 
 def build_deepseek_request_body(
-    request_data: MessagesRequest, *, thinking_enabled: bool
+    request_data: MessagesRequest, *, reasoning: ReasoningPolicy
 ) -> dict:
     """Build a DeepSeek Chat Completions body from an Anthropic request."""
     logger.debug(
@@ -57,8 +64,8 @@ def build_deepseek_request_body(
     has_tool_history = _has_tool_history(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:
+    effective_reasoning = reasoning
+    if reasoning.control is not ReasoningControl.OFF:
         if unsafe_tool_followup:
             logger.debug(
                 "DEEPSEEK_REQUEST: disabling thinking for tool follow-up without "
@@ -68,6 +75,7 @@ def build_deepseek_request_body(
                 len(data.get("tools", [])),
             )
             _remove_deepseek_thinking_hints(data)
+            effective_reasoning = ReasoningPolicy.off()
         elif has_tool_history:
             logger.debug(
                 "DEEPSEEK_REQUEST: keeping thinking for tool follow-up with "
@@ -93,9 +101,8 @@ def build_deepseek_request_body(
     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,
+        reasoning=effective_reasoning,
+        policy=DEEPSEEK_REQUEST_POLICY,
         postprocessors=(_apply_deepseek_chat_extras,),
     )
     if "max_tokens" not in body or body.get("max_tokens") is None:
@@ -427,10 +434,17 @@ def _downgrade_forced_tool_choice(data: dict[str, Any]) -> None:
 
 
 def _apply_deepseek_chat_extras(
-    body: dict[str, Any], _request_data: MessagesRequest, thinking_enabled: bool
+    body: dict[str, Any], _request_data: MessagesRequest, policy: ReasoningPolicy
 ) -> None:
-    if not thinking_enabled or body.get("model") == "deepseek-reasoner":
-        return
     extra_body = body.setdefault("extra_body", {})
-    if isinstance(extra_body, dict):
-        extra_body.setdefault("thinking", {"type": "enabled"})
+    if not isinstance(extra_body, dict):
+        return
+    if policy.control is ReasoningControl.OFF:
+        extra_body["thinking"] = {"type": "disabled"}
+        return
+    if policy.effort in {ReasoningEffort.XHIGH, ReasoningEffort.MAX}:
+        body["reasoning_effort"] = "max"
+    elif policy.effort is not None:
+        body["reasoning_effort"] = "high"
+    elif policy.requests_reasoning:
+        extra_body["thinking"] = {"type": "enabled"}

src/free_claude_code/providers/gemini/client.py

@@ -3,9 +3,16 @@
 from copy import deepcopy
 from typing import Any
 
+from free_claude_code.core.anthropic import ReasoningReplayMode
 from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.reasoning import (
+    DEFAULT_REASONING_POLICY,
+    ReasoningEffort,
+    ReasoningPolicy,
+)
 from free_claude_code.providers.base import ProviderConfig
 from free_claude_code.providers.openai_chat import (
+    NamedEffortReasoning,
     OpenAIChatProfile,
     OpenAIChatProvider,
     OpenAIChatRequestPolicy,
@@ -16,8 +23,24 @@ from free_claude_code.providers.rate_limit import ProviderRateLimiter
 from .quirks import apply_gemini_request_quirks
 
 _MAX_TOOL_CALL_EXTRA_CONTENT_CACHE = 4096
-_REQUEST_POLICY = OpenAIChatRequestPolicy(provider_name="GEMINI")
-_PROFILE = OpenAIChatProfile(_REQUEST_POLICY)
+_REQUEST_POLICY = OpenAIChatRequestPolicy(
+    provider_name="GEMINI",
+    reasoning_replay=ReasoningReplayMode.REASONING_CONTENT,
+)
+_PROFILE = OpenAIChatProfile(
+    _REQUEST_POLICY,
+    NamedEffortReasoning(
+        (
+            (ReasoningEffort.MINIMAL, "minimal"),
+            (ReasoningEffort.LOW, "low"),
+            (ReasoningEffort.MEDIUM, "medium"),
+            (ReasoningEffort.HIGH, "high"),
+            (ReasoningEffort.XHIGH, "high"),
+            (ReasoningEffort.MAX, "high"),
+        ),
+        disabled_value="none",
+    ),
+)
 
 
 class GeminiProvider(OpenAIChatProvider):
@@ -45,18 +68,22 @@ class GeminiProvider(OpenAIChatProvider):
         self._tool_call_extra_content_by_id[tool_call_id] = deepcopy(extra_content)
 
     def _build_request_body(
-        self, request: MessagesRequest, thinking_enabled: bool | None = None
+        self,
+        request: MessagesRequest,
+        *,
+        reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
     ) -> dict:
         return build_openai_chat_request_body(
             request,
-            thinking_enabled=self._is_thinking_enabled(request, thinking_enabled),
+            reasoning=reasoning,
             policy=_REQUEST_POLICY,
             postprocessors=(
-                lambda body, request_data, enabled: apply_gemini_request_quirks(
+                lambda body, request_data, policy: apply_gemini_request_quirks(
                     body,
                     request_data,
-                    enabled,
+                    policy,
                     tool_call_extra_content_by_id=self._tool_call_extra_content_by_id,
                 ),
+                _PROFILE.apply_reasoning,
             ),
         )

src/free_claude_code/providers/gemini/quirks.py

@@ -4,6 +4,7 @@ from copy import deepcopy
 from typing import Any, cast
 
 from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.reasoning import ReasoningPolicy
 
 GEMINI_SKIP_THOUGHT_SIGNATURE_VALIDATOR = "skip_thought_signature_validator"
 
@@ -11,7 +12,7 @@ GEMINI_SKIP_THOUGHT_SIGNATURE_VALIDATOR = "skip_thought_signature_validator"
 def apply_gemini_request_quirks(
     body: dict[str, Any],
     request_data: MessagesRequest,
-    thinking_enabled: bool,
+    reasoning: ReasoningPolicy,
     *,
     tool_call_extra_content_by_id: dict[str, dict[str, Any]] | None = None,
 ) -> None:
@@ -21,10 +22,8 @@ def apply_gemini_request_quirks(
     if isinstance(request_extra, dict):
         extra_body.update(deepcopy(request_extra))
 
-    if thinking_enabled:
+    if reasoning.requests_reasoning:
         _apply_thinking_config(extra_body)
-    else:
-        body["reasoning_effort"] = "none"
 
     if extra_body:
         body["extra_body"] = extra_body
@@ -53,10 +52,6 @@ def _apply_thinking_config(extra_body: dict[str, Any]) -> None:
     thinking_cfg.setdefault("include_thoughts", True)
 
 
-def _is_gemini_3_model(model: Any) -> bool:
-    return "gemini-3" in str(model).lower()
-
-
 def _thought_signature_from_extra_content(extra_content: Any) -> str | None:
     if not isinstance(extra_content, dict):
         return None
@@ -136,12 +131,7 @@ def _apply_cached_tool_call_signatures(
                 tool_call["extra_content"] = deepcopy(cached_extra_content)
 
 
-def _apply_gemini_3_missing_current_turn_signatures(
-    body: dict[str, Any], messages: list[Any]
-) -> None:
-    if not _is_gemini_3_model(body.get("model")):
-        return
-
+def _apply_missing_current_turn_signatures(messages: list[Any]) -> None:
     start_index = _current_turn_start_index(messages)
     for message in messages[start_index + 1 :]:
         if not isinstance(message, dict) or message.get("role") != "assistant":
@@ -168,4 +158,4 @@ def _apply_gemini_tool_call_signatures(
     if not isinstance(messages, list):
         return
     _apply_cached_tool_call_signatures(messages, tool_call_extra_content_by_id or {})
-    _apply_gemini_3_missing_current_turn_signatures(body, messages)
+    _apply_missing_current_turn_signatures(messages)

src/free_claude_code/providers/github_models/client.py

@@ -6,7 +6,7 @@ from typing import Any
 import httpx
 
 from free_claude_code.application.model_metadata import ProviderModelInfo
-from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.anthropic import ReasoningReplayMode
 from free_claude_code.providers.base import ProviderConfig
 from free_claude_code.providers.http import maybe_await_aclose
 from free_claude_code.providers.model_listing import (
@@ -14,10 +14,10 @@ from free_claude_code.providers.model_listing import (
     model_infos_from_ids,
 )
 from free_claude_code.providers.openai_chat import (
+    NO_REASONING,
     OpenAIChatProfile,
     OpenAIChatProvider,
     OpenAIChatRequestPolicy,
-    build_openai_chat_request_body,
 )
 from free_claude_code.providers.rate_limit import ProviderRateLimiter
 
@@ -26,8 +26,9 @@ GITHUB_MODELS_API_VERSION = "2026-03-10"
 
 _REQUEST_POLICY = OpenAIChatRequestPolicy(
     provider_name="GITHUB_MODELS",
+    reasoning_replay=ReasoningReplayMode.THINK_TAGS,
 )
-_PROFILE = OpenAIChatProfile(_REQUEST_POLICY)
+_PROFILE = OpenAIChatProfile(_REQUEST_POLICY, NO_REASONING)
 _REQUIRED_MODEL_CAPABILITIES = frozenset({"streaming", "tool-calling"})
 
 
@@ -81,15 +82,6 @@ class GitHubModelsProvider(OpenAIChatProvider):
         finally:
             await maybe_await_aclose(response)
 
-    def _build_request_body(
-        self, request: MessagesRequest, thinking_enabled: bool | None = None
-    ) -> dict:
-        return build_openai_chat_request_body(
-            request,
-            thinking_enabled=self._is_thinking_enabled(request, thinking_enabled),
-            policy=_REQUEST_POLICY,
-        )
-
     def _model_list_headers(self) -> dict[str, str]:
         return _github_models_api_headers(self._api_key)
 

src/free_claude_code/providers/lmstudio/client.py

@@ -17,22 +17,41 @@ import httpx
 from loguru import logger
 
 from free_claude_code.application.errors import InvalidRequestError
-from free_claude_code.core.anthropic import (
-    ReasoningReplayMode,
-    build_base_request_body,
-    get_token_count,
-)
-from free_claude_code.core.anthropic.conversion import OpenAIConversionError
+from free_claude_code.core.anthropic import ReasoningReplayMode, get_token_count
 from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.reasoning import (
+    DEFAULT_REASONING_POLICY,
+    ReasoningEffort,
+    ReasoningPolicy,
+)
 from free_claude_code.providers.base import ProviderConfig
 from free_claude_code.providers.openai_chat import (
+    NamedEffortReasoning,
     OpenAIChatProfile,
     OpenAIChatProvider,
     OpenAIChatRequestPolicy,
 )
 from free_claude_code.providers.rate_limit import ProviderRateLimiter
 
-_PROFILE = OpenAIChatProfile(OpenAIChatRequestPolicy(provider_name="LMSTUDIO"))
+_PROFILE = OpenAIChatProfile(
+    OpenAIChatRequestPolicy(
+        provider_name="LMSTUDIO",
+        reasoning_replay=ReasoningReplayMode.DISABLED,
+    ),
+    NamedEffortReasoning(
+        (
+            (ReasoningEffort.MINIMAL, "low"),
+            (ReasoningEffort.LOW, "low"),
+            (ReasoningEffort.MEDIUM, "medium"),
+            (ReasoningEffort.HIGH, "high"),
+            (ReasoningEffort.XHIGH, "high"),
+            (ReasoningEffort.MAX, "high"),
+        ),
+        disabled_value="none",
+        enabled_value="high",
+        budget_field="reasoning_tokens",
+    ),
+)
 
 
 class LMStudioProvider(OpenAIChatProvider):
@@ -53,28 +72,13 @@ class LMStudioProvider(OpenAIChatProvider):
         )
         self._loaded_context_cache: tuple[float, int | None] = (0.0, None)
 
-    def _build_request_body(
-        self, request: MessagesRequest, thinking_enabled: bool | None = None
-    ) -> dict:
-        """Build an OpenAI chat body from the Anthropic request.
-
-        Prior-turn thinking is never replayed: Mistral-family templates have
-        no assistant reasoning field, and replaying ``<think>`` text inflates
-        the local context for no benefit. New-response thinking still streams
-        back via ``reasoning_content``/``<think>`` parsing in the provider.
-        """
-        try:
-            return build_base_request_body(
-                request,
-                reasoning_replay=ReasoningReplayMode.DISABLED,
-            )
-        except OpenAIConversionError as exc:
-            raise InvalidRequestError(str(exc)) from exc
-
     def preflight_stream(
-        self, request: MessagesRequest, *, thinking_enabled: bool | None = None
+        self,
+        request: MessagesRequest,
+        *,
+        reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
     ) -> None:
-        super().preflight_stream(request, thinking_enabled=thinking_enabled)
+        super().preflight_stream(request, reasoning=reasoning)
         self._preflight_context_budget(request)
 
     def _preflight_context_budget(self, request: MessagesRequest) -> None:

src/free_claude_code/providers/mistral/client.py

@@ -4,9 +4,12 @@ from typing import Any
 
 from loguru import logger
 
+from free_claude_code.core.anthropic import ReasoningReplayMode
 from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
 from free_claude_code.providers.base import ProviderConfig
 from free_claude_code.providers.openai_chat import (
+    NO_REASONING,
     OpenAIChatProfile,
     OpenAIChatProvider,
     OpenAIChatRequestPolicy,
@@ -21,8 +24,11 @@ from .reasoning import (
     normalize_mistral_stream,
 )
 
-_REQUEST_POLICY = OpenAIChatRequestPolicy(provider_name="MISTRAL")
-_PROFILE = OpenAIChatProfile(_REQUEST_POLICY)
+_REQUEST_POLICY = OpenAIChatRequestPolicy(
+    provider_name="MISTRAL",
+    reasoning_replay=ReasoningReplayMode.REASONING_CONTENT,
+)
+_PROFILE = OpenAIChatProfile(_REQUEST_POLICY, NO_REASONING)
 
 
 class MistralProvider(OpenAIChatProvider):
@@ -36,19 +42,17 @@ class MistralProvider(OpenAIChatProvider):
         )
 
     def _build_request_body(
-        self, request: MessagesRequest, thinking_enabled: bool | None = None
+        self,
+        request: MessagesRequest,
+        *,
+        reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
     ) -> dict:
-        effective_thinking_enabled = self._is_thinking_enabled(
-            request, thinking_enabled
-        )
         body = build_openai_chat_request_body(
             request,
-            thinking_enabled=effective_thinking_enabled,
+            reasoning=reasoning,
             policy=_REQUEST_POLICY,
         )
-        apply_mistral_reasoning_request_shape(
-            body, thinking_enabled=effective_thinking_enabled
-        )
+        apply_mistral_reasoning_request_shape(body, reasoning=reasoning)
         return body
 
     def _get_retry_request_body(self, error: Exception, body: dict) -> dict | None:

src/free_claude_code/providers/mistral/reasoning.py

@@ -8,6 +8,7 @@ from typing import Any
 
 import openai
 
+from free_claude_code.core.reasoning import ReasoningControl, ReasoningPolicy
 from free_claude_code.providers.http import maybe_await_aclose
 
 MISTRAL_REASONING_EFFORT = "high"
@@ -23,10 +24,12 @@ _REJECTION_WORDS = ("unsupported", "unknown", "invalid", "forbidden", "extra")
 
 
 def apply_mistral_reasoning_request_shape(
-    body: dict[str, Any], *, thinking_enabled: bool
+    body: dict[str, Any], *, reasoning: ReasoningPolicy
 ) -> None:
     """Apply Mistral's native reasoning request shape in-place."""
-    if thinking_enabled:
+    if reasoning.control is ReasoningControl.OFF:
+        body["reasoning_effort"] = "none"
+    elif reasoning.requests_reasoning:
         body["reasoning_effort"] = MISTRAL_REASONING_EFFORT
     else:
         body.pop("reasoning_effort", None)
@@ -38,13 +41,11 @@ def apply_mistral_reasoning_request_shape(
     for message in messages:
         if not isinstance(message, dict) or message.get("role") != "assistant":
             continue
-        reasoning = _clean_text(message.pop("reasoning_content", None))
-        if thinking_enabled and reasoning:
+        replayed_reasoning = _clean_text(message.pop("reasoning_content", None))
+        if replayed_reasoning:
             message["content"] = _content_with_prepended_thinking(
-                message.get("content"), reasoning
+                message.get("content"), replayed_reasoning
             )
-        elif not thinking_enabled:
-            message["content"] = _content_without_thinking(message.get("content"))
 
 
 def clone_body_without_mistral_reasoning(
@@ -178,11 +179,6 @@ def _content_with_prepended_thinking(
     return chunks
 
 
-def _content_without_thinking(content: Any) -> Any:
-    stripped, _ = _strip_mistral_thinking_content(content)
-    return stripped
-
-
 def _strip_mistral_thinking_content(content: Any) -> tuple[Any, bool]:
     if not _is_sequence(content):
         return content, False

src/free_claude_code/providers/nvidia_nim/client.py

@@ -10,18 +10,19 @@ from loguru import logger
 from free_claude_code.config.nim import NimSettings
 from free_claude_code.core.anthropic.models import MessagesRequest
 from free_claude_code.core.failures import ExecutionFailure
+from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
 from free_claude_code.providers.base import ProviderConfig
 from free_claude_code.providers.failure_policy import (
     overloaded_provider_failure,
 )
 from free_claude_code.providers.openai_chat import (
+    NO_REASONING,
     OpenAIChatProfile,
     OpenAIChatProvider,
-    OpenAIChatRequestPolicy,
 )
 from free_claude_code.providers.rate_limit import ProviderRateLimiter
 
-from .request_options import build_nim_request_body
+from .request_options import NIM_REQUEST_POLICY, build_nim_request_body
 from .retry import (
     clone_body_without_chat_template,
     clone_body_without_reasoning_budget,
@@ -33,7 +34,10 @@ from .tool_schema import (
 )
 
 _DEGRADED_FUNCTION_STATE = "degraded function cannot be invoked"
-_PROFILE = OpenAIChatProfile(OpenAIChatRequestPolicy(provider_name="NIM"))
+_PROFILE = OpenAIChatProfile(
+    NIM_REQUEST_POLICY,
+    NO_REASONING,
+)
 
 
 class NvidiaNimProvider(OpenAIChatProvider):
@@ -54,13 +58,16 @@ class NvidiaNimProvider(OpenAIChatProvider):
         self._nim_settings = nim_settings
 
     def _build_request_body(
-        self, request: MessagesRequest, thinking_enabled: bool | None = None
+        self,
+        request: MessagesRequest,
+        *,
+        reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
     ) -> dict:
         """Internal helper for tests and shared building."""
         return build_nim_request_body(
             request,
             self._nim_settings,
-            thinking_enabled=self._is_thinking_enabled(request, thinking_enabled),
+            reasoning=reasoning,
         )
 
     def _prepare_create_body(self, body: dict[str, Any]) -> dict[str, Any]:

src/free_claude_code/providers/nvidia_nim/request_options.py

@@ -1,10 +1,12 @@
 """NVIDIA NIM request option injection."""
 
+from copy import deepcopy
 from typing import Any
 
 from free_claude_code.config.nim import NimSettings
-from free_claude_code.core.anthropic import set_if_not_none
+from free_claude_code.core.anthropic import ReasoningReplayMode, set_if_not_none
 from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.reasoning import ReasoningControl, ReasoningPolicy
 from free_claude_code.providers.openai_chat import (
     OpenAIChatRequestPolicy,
     build_openai_chat_request_body,
@@ -12,22 +14,25 @@ from free_claude_code.providers.openai_chat import (
 
 from .tool_schema import sanitize_nim_tool_schemas
 
-_REQUEST_POLICY = OpenAIChatRequestPolicy(provider_name="NIM")
+NIM_REQUEST_POLICY = OpenAIChatRequestPolicy(
+    provider_name="NIM",
+    reasoning_replay=ReasoningReplayMode.REASONING_CONTENT,
+)
 
 
 def build_nim_request_body(
-    request_data: MessagesRequest, nim: NimSettings, *, thinking_enabled: bool
+    request_data: MessagesRequest, nim: NimSettings, *, reasoning: ReasoningPolicy
 ) -> dict[str, Any]:
     """Build OpenAI-format request body from Anthropic request plus NIM settings."""
     return build_openai_chat_request_body(
         request_data,
-        thinking_enabled=thinking_enabled,
-        policy=_REQUEST_POLICY,
+        reasoning=reasoning,
+        policy=NIM_REQUEST_POLICY,
         postprocessors=(
-            lambda body, request, enabled: apply_nim_request_options(
+            lambda body, request, policy: apply_nim_request_options(
                 body,
                 request,
-                enabled,
+                policy,
                 nim=nim,
             ),
         ),
@@ -37,7 +42,7 @@ def build_nim_request_body(
 def apply_nim_request_options(
     body: dict[str, Any],
     request_data: MessagesRequest,
-    thinking_enabled: bool,
+    reasoning: ReasoningPolicy,
     *,
     nim: NimSettings,
 ) -> None:
@@ -71,14 +76,30 @@ def apply_nim_request_options(
     extra_body: dict[str, Any] = {}
     request_extra = request_data.extra_body
     if request_extra:
-        extra_body.update(request_extra)
-
-    if thinking_enabled:
-        chat_template_kwargs = extra_body.setdefault(
-            "chat_template_kwargs", {"thinking": True, "enable_thinking": True}
-        )
+        extra_body.update(deepcopy(request_extra))
+    for key in (
+        "reasoning",
+        "reasoning_effort",
+        "reasoning_tokens",
+        "thinking",
+        "thinking_budget_tokens",
+    ):
+        extra_body.pop(key, None)
+    request_template_kwargs = extra_body.get("chat_template_kwargs")
+    if isinstance(request_template_kwargs, dict):
+        for key in ("thinking", "enable_thinking", "reasoning_budget"):
+            request_template_kwargs.pop(key, None)
+        if not request_template_kwargs:
+            extra_body.pop("chat_template_kwargs", None)
+
+    if reasoning.control is ReasoningControl.OFF or reasoning.requests_reasoning:
+        chat_template_kwargs = extra_body.setdefault("chat_template_kwargs", {})
         if isinstance(chat_template_kwargs, dict):
-            chat_template_kwargs.setdefault("reasoning_budget", max_tokens)
+            enabled = reasoning.control is not ReasoningControl.OFF
+            chat_template_kwargs["thinking"] = enabled
+            chat_template_kwargs["enable_thinking"] = enabled
+            if enabled and reasoning.budget_tokens is not None:
+                chat_template_kwargs["reasoning_budget"] = reasoning.budget_tokens
 
     req_top_k = request_data.top_k
     top_k = req_top_k if req_top_k is not None else nim.top_k

src/free_claude_code/providers/open_router/client.py

@@ -6,8 +6,10 @@ from typing import Any
 
 from free_claude_code.application.model_metadata import ProviderModelInfo
 from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
-from free_claude_code.core.anthropic.models import MessagesRequest, ThinkingConfig
+from free_claude_code.core.anthropic import ReasoningReplayMode
+from free_claude_code.core.anthropic.models import MessagesRequest
 from free_claude_code.core.anthropic.streaming import AnthropicStreamLedger
+from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
 from free_claude_code.providers.base import ProviderConfig
 from free_claude_code.providers.model_listing import (
     extract_openrouter_tool_model_ids,
@@ -17,18 +19,18 @@ from free_claude_code.providers.openai_chat import (
     OpenAIChatProfile,
     OpenAIChatProvider,
     OpenAIChatRequestPolicy,
-    build_openai_chat_request_body,
+    ReasoningObject,
     validate_extra_body_does_not_override_canonical_fields,
 )
 from free_claude_code.providers.rate_limit import ProviderRateLimiter
 
 _REQUEST_POLICY = OpenAIChatRequestPolicy(
     provider_name="OPENROUTER",
+    reasoning_replay=ReasoningReplayMode.REASONING_CONTENT,
     include_extra_body=True,
     extra_body_validator=validate_extra_body_does_not_override_canonical_fields,
     default_max_tokens=ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
 )
-_PROFILE = OpenAIChatProfile(_REQUEST_POLICY)
 
 
 class OpenRouterProvider(OpenAIChatProvider):
@@ -41,22 +43,6 @@ class OpenRouterProvider(OpenAIChatProvider):
             rate_limiter=rate_limiter,
         )
 
-    def _build_request_body(
-        self, request: MessagesRequest, thinking_enabled: bool | None = None
-    ) -> dict:
-        effective_thinking_enabled = self._is_thinking_enabled(
-            request, thinking_enabled
-        )
-        return build_openai_chat_request_body(
-            request,
-            thinking_enabled=effective_thinking_enabled,
-            policy=_REQUEST_POLICY,
-            postprocessors=(
-                _apply_openrouter_reasoning_policy,
-                _apply_openrouter_reasoning_details_replay,
-            ),
-        )
-
     async def list_model_ids(self) -> frozenset[str]:
         """Only advertise OpenRouter models that can run Claude Code tools."""
         payload = await self._client.models.list()
@@ -72,36 +58,17 @@ class OpenRouterProvider(OpenAIChatProvider):
         )
 
     def _handle_extra_reasoning(
-        self, delta: Any, ledger: AnthropicStreamLedger, *, thinking_enabled: bool
+        self, delta: Any, ledger: AnthropicStreamLedger, *, output_reasoning: bool
     ) -> Iterator[str]:
         """Map OpenRouter reasoning details onto Anthropic thinking blocks."""
-        if not thinking_enabled:
+        if not output_reasoning:
             return iter(())
         return _iter_openrouter_reasoning_detail_events(delta, ledger)
 
 
-def _apply_openrouter_reasoning_policy(
-    body: dict[str, Any], request: MessagesRequest, thinking_enabled: bool
-) -> None:
-    if not thinking_enabled:
-        return
-    extra_body = body.setdefault("extra_body", {})
-    if not isinstance(extra_body, dict):
-        return
-    reasoning = extra_body.setdefault("reasoning", {"enabled": True})
-    if not isinstance(reasoning, dict):
-        return
-    reasoning.setdefault("enabled", True)
-    budget_tokens = _thinking_budget_tokens(request.thinking)
-    if isinstance(budget_tokens, int):
-        reasoning.setdefault("max_tokens", budget_tokens)
-
-
 def _apply_openrouter_reasoning_details_replay(
-    body: dict[str, Any], request: MessagesRequest, thinking_enabled: bool
+    body: dict[str, Any], request: MessagesRequest, _policy: ReasoningPolicy
 ) -> None:
-    if not thinking_enabled:
-        return
     assistant_details = _assistant_reasoning_details(request.messages)
     if not assistant_details:
         return
@@ -124,6 +91,13 @@ def _apply_openrouter_reasoning_details_replay(
             break
 
 
+_PROFILE = OpenAIChatProfile(
+    _REQUEST_POLICY,
+    ReasoningObject(tuple((effort, effort.value) for effort in ReasoningEffort)),
+    postprocessors=(_apply_openrouter_reasoning_details_replay,),
+)
+
+
 def _assistant_reasoning_details(messages: Any) -> list[list[dict[str, Any]]]:
     if not _is_sequence(messages):
         return []
@@ -157,11 +131,6 @@ def _redacted_reasoning_details(content: Any) -> list[dict[str, Any]]:
     return details
 
 
-def _thinking_budget_tokens(thinking: ThinkingConfig | None) -> int | None:
-    value = thinking.budget_tokens if thinking is not None else None
-    return value if isinstance(value, int) and not isinstance(value, bool) else None
-
-
 def _iter_openrouter_reasoning_detail_events(
     delta: Any, ledger: AnthropicStreamLedger
 ) -> Iterator[str]:

src/free_claude_code/providers/openai_chat/__init__.py

@@ -7,6 +7,12 @@ from .base_url import openai_v1_base_url
 from .extra_body import validate_extra_body_does_not_override_canonical_fields
 from .profiles import OPENAI_CHAT_PROFILES, OpenAIChatProfile
 from .provider import OpenAIChatProvider
+from .reasoning import (
+    NO_REASONING,
+    ChatTemplateReasoning,
+    NamedEffortReasoning,
+    ReasoningObject,
+)
 from .request_policy import OpenAIChatRequestPolicy, build_openai_chat_request_body
 from .usage import usage_int
 
@@ -28,10 +34,14 @@ def create_openai_chat_provider(
 
 
 __all__ = [
+    "NO_REASONING",
     "OPENAI_CHAT_PROFILES",
+    "ChatTemplateReasoning",
+    "NamedEffortReasoning",
     "OpenAIChatProfile",
     "OpenAIChatProvider",
     "OpenAIChatRequestPolicy",
+    "ReasoningObject",
     "build_openai_chat_request_body",
     "create_openai_chat_provider",
     "openai_v1_base_url",

src/free_claude_code/providers/openai_chat/extra_body.py

@@ -17,6 +17,21 @@ CANONICAL_OPENAI_CHAT_BODY_KEYS = frozenset(
         "stop",
         "stop_sequences",
         "stream_options",
+        "reasoning",
+        "reasoning_effort",
+        "reasoning_tokens",
+        "thinking",
+        "thinking_budget_tokens",
+    }
+)
+
+REASONING_OPENAI_CHAT_BODY_KEYS = frozenset(
+    {
+        "reasoning",
+        "reasoning_effort",
+        "reasoning_tokens",
+        "thinking",
+        "thinking_budget_tokens",
     }
 )
 
@@ -30,3 +45,15 @@ def validate_extra_body_does_not_override_canonical_fields(
         raise ValueError(
             f"extra_body must not override canonical request fields: {sorted(bad)}"
         )
+
+
+def validate_extra_body_does_not_override_reasoning_fields(
+    extra: dict[str, Any],
+) -> None:
+    """Keep provider reasoning translation authoritative over caller extras."""
+
+    bad = REASONING_OPENAI_CHAT_BODY_KEYS & extra.keys()
+    if bad:
+        raise ValueError(
+            f"extra_body must not override reasoning fields: {sorted(bad)}"
+        )

src/free_claude_code/providers/openai_chat/profiles.py

@@ -1,4 +1,4 @@
-"""Declarative profiles for providers with no adapter-specific runtime behavior."""
+"""Declarative profiles for ordinary OpenAI-compatible providers."""
 
 from collections.abc import Mapping
 from copy import deepcopy
@@ -9,17 +9,49 @@ from free_claude_code.application.errors import InvalidRequestError
 from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
 from free_claude_code.core.anthropic import ReasoningReplayMode
 from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
 
 from .base_url import openai_v1_base_url
-from .extra_body import validate_extra_body_does_not_override_canonical_fields
+from .extra_body import (
+    validate_extra_body_does_not_override_canonical_fields,
+    validate_extra_body_does_not_override_reasoning_fields,
+)
+from .reasoning import (
+    LLAMACPP_REASONING,
+    NO_REASONING,
+    SPLIT_REASONING_OUTPUT,
+    NamedEffortReasoning,
+    ReasoningEncoder,
+    ReasoningObject,
+    ThinkingObjectReasoning,
+)
 from .request_policy import OpenAIChatPostprocessor, OpenAIChatRequestPolicy
 
+_ALL_EFFORTS = tuple((effort, effort.value) for effort in ReasoningEffort)
+_LOW_MEDIUM_HIGH = (
+    (ReasoningEffort.MINIMAL, "low"),
+    (ReasoningEffort.LOW, "low"),
+    (ReasoningEffort.MEDIUM, "medium"),
+    (ReasoningEffort.HIGH, "high"),
+    (ReasoningEffort.XHIGH, "high"),
+    (ReasoningEffort.MAX, "high"),
+)
+_LOW_TO_MAX = (
+    (ReasoningEffort.MINIMAL, "low"),
+    (ReasoningEffort.LOW, "low"),
+    (ReasoningEffort.MEDIUM, "medium"),
+    (ReasoningEffort.HIGH, "high"),
+    (ReasoningEffort.XHIGH, "max"),
+    (ReasoningEffort.MAX, "max"),
+)
+
 
 @dataclass(frozen=True, slots=True)
 class OpenAIChatProfile:
-    """Immutable behavior differences for one ordinary OpenAI-chat provider."""
+    """Immutable transport and reasoning behavior for one provider."""
 
     request_policy: OpenAIChatRequestPolicy
+    reasoning: ReasoningEncoder
     postprocessors: tuple[OpenAIChatPostprocessor, ...] = ()
     normalize_base_url: bool = False
     reasoning_delta_field: Literal["reasoning_content", "reasoning"] = (
@@ -37,12 +69,23 @@ class OpenAIChatProfile:
         value = getattr(delta, self.reasoning_delta_field, None)
         return value if isinstance(value, str) else None
 
+    def apply_reasoning(
+        self,
+        body: dict[str, Any],
+        _request: MessagesRequest,
+        policy: ReasoningPolicy,
+    ) -> None:
+        self.reasoning.encode(body, policy)
+
+    @property
+    def request_postprocessors(self) -> tuple[OpenAIChatPostprocessor, ...]:
+        return (*self.postprocessors, self.apply_reasoning)
+
 
 def _apply_cohere_request_quirks(
-    body: dict[str, Any], request: MessagesRequest, thinking_enabled: bool
+    body: dict[str, Any], request: MessagesRequest, _policy: ReasoningPolicy
 ) -> None:
     _merge_allowed_cohere_extra_body(body, request.extra_body)
-    body["reasoning_effort"] = "high" if thinking_enabled else "none"
 
 
 _COHERE_EXTRA_BODY_KEYS = frozenset(
@@ -72,78 +115,53 @@ def _merge_allowed_cohere_extra_body(body: dict[str, Any], extra_body: Any) -> N
     body.update({str(key): deepcopy(value) for key, value in extra_body.items()})
 
 
-def _apply_kimi_thinking_policy(
-    body: dict[str, Any], _request: MessagesRequest, thinking_enabled: bool
-) -> None:
-    if thinking_enabled:
-        return
-    extra_body = body.setdefault("extra_body", {})
-    if isinstance(extra_body, dict):
-        extra_body["thinking"] = {"type": "disabled"}
-
-
-def _apply_minimax_thinking_policy(
-    body: dict[str, Any], _request: MessagesRequest, thinking_enabled: bool
-) -> None:
-    extra_body = body.setdefault("extra_body", {})
-    if not isinstance(extra_body, dict):
-        return
-    extra_body["reasoning_split"] = True
-    extra_body["thinking"] = (
-        {"type": "adaptive"} if thinking_enabled else {"type": "disabled"}
-    )
-
-
-def _apply_ollama_thinking_policy(
-    body: dict[str, Any], _request: MessagesRequest, thinking_enabled: bool
-) -> None:
-    body["reasoning_effort"] = "high" if thinking_enabled else "none"
-
-
-def _apply_wafer_thinking_policy(
-    body: dict[str, Any], _request: MessagesRequest, thinking_enabled: bool
-) -> None:
-    extra_body = body.setdefault("extra_body", {})
-    if isinstance(extra_body, dict):
-        extra_body["thinking"] = (
-            {"type": "enabled"} if thinking_enabled else {"type": "disabled"}
-        )
-
-
-def _apply_zai_thinking_policy(
-    body: dict[str, Any], _request: MessagesRequest, thinking_enabled: bool
-) -> None:
-    extra_body = body.setdefault("extra_body", {})
-    if not isinstance(extra_body, dict):
-        return
-    extra_body["thinking"] = (
-        {"type": "enabled", "clear_thinking": False}
-        if thinking_enabled
-        else {"type": "disabled"}
+def _policy(
+    provider_name: str,
+    replay: ReasoningReplayMode,
+    **kwargs: Any,
+) -> OpenAIChatRequestPolicy:
+    return OpenAIChatRequestPolicy(
+        provider_name=provider_name,
+        reasoning_replay=replay,
+        **kwargs,
     )
 
 
 OPENAI_CHAT_PROFILES: dict[str, OpenAIChatProfile] = {
     "mistral_codestral": OpenAIChatProfile(
-        OpenAIChatRequestPolicy(provider_name="CODESTRAL")
+        _policy("CODESTRAL", ReasoningReplayMode.THINK_TAGS),
+        NO_REASONING,
+    ),
+    "opencode": OpenAIChatProfile(
+        _policy("OPENCODE", ReasoningReplayMode.THINK_TAGS),
+        NO_REASONING,
     ),
-    "opencode": OpenAIChatProfile(OpenAIChatRequestPolicy(provider_name="OPENCODE")),
     "opencode_go": OpenAIChatProfile(
-        OpenAIChatRequestPolicy(provider_name="OPENCODE_GO")
+        _policy("OPENCODE_GO", ReasoningReplayMode.THINK_TAGS),
+        NO_REASONING,
     ),
     "vercel": OpenAIChatProfile(
-        OpenAIChatRequestPolicy(provider_name="VERCEL", include_extra_body=True)
+        _policy(
+            "VERCEL",
+            ReasoningReplayMode.THINK_TAGS,
+            include_extra_body=True,
+            extra_body_validator=validate_extra_body_does_not_override_reasoning_fields,
+        ),
+        ReasoningObject(_ALL_EFFORTS),
     ),
     "huggingface": OpenAIChatProfile(
-        OpenAIChatRequestPolicy(
-            provider_name="HUGGINGFACE",
+        _policy(
+            "HUGGINGFACE",
+            ReasoningReplayMode.DISABLED,
             include_extra_body=True,
-            reasoning_replay=ReasoningReplayMode.DISABLED,
-        )
+            extra_body_validator=validate_extra_body_does_not_override_reasoning_fields,
+        ),
+        NO_REASONING,
     ),
     "cohere": OpenAIChatProfile(
-        OpenAIChatRequestPolicy(
-            provider_name="COHERE",
+        _policy(
+            "COHERE",
+            ReasoningReplayMode.REASONING_CONTENT,
             strip_message_names=True,
             unsupported_body_keys=frozenset(
                 {
@@ -160,94 +178,162 @@ OPENAI_CHAT_PROFILES: dict[str, OpenAIChatProfile] = {
                 }
             ),
         ),
+        NamedEffortReasoning(
+            tuple((effort, "high") for effort in ReasoningEffort),
+            disabled_value="none",
+            enabled_value="high",
+        ),
         postprocessors=(_apply_cohere_request_quirks,),
     ),
     "wafer": OpenAIChatProfile(
-        OpenAIChatRequestPolicy(
-            provider_name="WAFER",
+        _policy(
+            "WAFER",
+            ReasoningReplayMode.REASONING_CONTENT,
             default_max_tokens=ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
         ),
-        postprocessors=(_apply_wafer_thinking_policy,),
+        NamedEffortReasoning(
+            _LOW_TO_MAX,
+            disabled_value="none",
+            enabled_value="high",
+        ),
     ),
     "kimi": OpenAIChatProfile(
-        OpenAIChatRequestPolicy(
-            provider_name="KIMI",
+        _policy(
+            "KIMI",
+            ReasoningReplayMode.REASONING_CONTENT,
             reject_extra_body_message=(
                 "Kimi Chat Completions API does not support caller extra_body on requests."
             ),
             default_max_tokens=ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
         ),
-        postprocessors=(_apply_kimi_thinking_policy,),
+        ThinkingObjectReasoning(
+            enabled={"type": "enabled"},
+            disabled={"type": "disabled"},
+        ),
     ),
     "minimax": OpenAIChatProfile(
-        OpenAIChatRequestPolicy(
-            provider_name="MINIMAX",
+        _policy(
+            "MINIMAX",
+            ReasoningReplayMode.REASONING_CONTENT,
             default_max_tokens=ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
             max_tokens_field="max_completion_tokens",
         ),
-        postprocessors=(_apply_minimax_thinking_policy,),
+        SPLIT_REASONING_OUTPUT,
     ),
     "cerebras": OpenAIChatProfile(
-        OpenAIChatRequestPolicy(
-            provider_name="CEREBRAS",
+        _policy(
+            "CEREBRAS",
+            ReasoningReplayMode.THINK_TAGS,
             include_extra_body=True,
+            extra_body_validator=validate_extra_body_does_not_override_reasoning_fields,
             max_tokens_field="max_completion_tokens",
-            reasoning_replay=ReasoningReplayMode.THINK_TAGS,
+        ),
+        NamedEffortReasoning(
+            _LOW_MEDIUM_HIGH,
+            disabled_value="none",
+            enabled_value="medium",
         ),
         reasoning_delta_field="reasoning",
     ),
     "groq": OpenAIChatProfile(
-        OpenAIChatRequestPolicy(
-            provider_name="GROQ",
+        _policy(
+            "GROQ",
+            ReasoningReplayMode.REASONING_CONTENT,
             include_extra_body=True,
+            extra_body_validator=validate_extra_body_does_not_override_reasoning_fields,
             max_tokens_field="max_completion_tokens",
             strip_message_names=True,
             unsupported_body_keys=frozenset({"logprobs", "logit_bias", "top_logprobs"}),
             normalize_n_to_one=True,
-        )
+        ),
+        NamedEffortReasoning(
+            _LOW_MEDIUM_HIGH,
+            disabled_value="none",
+            enabled_value="medium",
+        ),
     ),
     "sambanova": OpenAIChatProfile(
-        OpenAIChatRequestPolicy(provider_name="SAMBANOVA", include_extra_body=True)
+        _policy(
+            "SAMBANOVA",
+            ReasoningReplayMode.REASONING_CONTENT,
+            include_extra_body=True,
+            extra_body_validator=validate_extra_body_does_not_override_reasoning_fields,
+        ),
+        NamedEffortReasoning(
+            _LOW_MEDIUM_HIGH,
+            enabled_value="medium",
+        ),
     ),
     "fireworks": OpenAIChatProfile(
-        OpenAIChatRequestPolicy(
-            provider_name="FIREWORKS",
+        _policy(
+            "FIREWORKS",
+            ReasoningReplayMode.REASONING_CONTENT,
             include_extra_body=True,
             extra_body_validator=validate_extra_body_does_not_override_canonical_fields,
             default_max_tokens=ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
-        )
+        ),
+        NamedEffortReasoning(
+            (
+                (ReasoningEffort.MINIMAL, "low"),
+                (ReasoningEffort.LOW, "low"),
+                (ReasoningEffort.MEDIUM, "medium"),
+                (ReasoningEffort.HIGH, "high"),
+                (ReasoningEffort.XHIGH, "xhigh"),
+                (ReasoningEffort.MAX, "max"),
+            ),
+            disabled_value="none",
+            enabled_value="high",
+            budget_field="reasoning_effort",
+        ),
     ),
     "zai": OpenAIChatProfile(
-        OpenAIChatRequestPolicy(
-            provider_name="ZAI",
+        _policy(
+            "ZAI",
+            ReasoningReplayMode.REASONING_CONTENT,
             reject_extra_body_message=(
                 "Z.ai Chat Completions API does not support caller extra_body on requests."
             ),
             default_max_tokens=ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
         ),
-        postprocessors=(_apply_zai_thinking_policy,),
+        ThinkingObjectReasoning(
+            enabled={"type": "enabled", "clear_thinking": False},
+            disabled={"type": "disabled"},
+        ),
     ),
     "ollama_cloud": OpenAIChatProfile(
-        OpenAIChatRequestPolicy(
-            provider_name="OLLAMA_CLOUD",
+        _policy(
+            "OLLAMA_CLOUD",
+            ReasoningReplayMode.REASONING,
             default_max_tokens=ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
-            reasoning_replay=ReasoningReplayMode.REASONING,
         ),
-        postprocessors=(_apply_ollama_thinking_policy,),
+        NamedEffortReasoning(
+            _LOW_TO_MAX,
+            disabled_value="none",
+            enabled_value="high",
+        ),
         reasoning_delta_field="reasoning",
     ),
     "llamacpp": OpenAIChatProfile(
-        OpenAIChatRequestPolicy(
-            provider_name="LLAMACPP",
+        _policy(
+            "LLAMACPP",
+            ReasoningReplayMode.THINK_TAGS,
             default_max_tokens=ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
         ),
+        LLAMACPP_REASONING,
         normalize_base_url=True,
     ),
     "ollama": OpenAIChatProfile(
-        OpenAIChatRequestPolicy(
-            provider_name="OLLAMA",
+        _policy(
+            "OLLAMA",
+            ReasoningReplayMode.REASONING,
             default_max_tokens=ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
         ),
+        NamedEffortReasoning(
+            _LOW_TO_MAX,
+            disabled_value="none",
+            enabled_value="high",
+        ),
         normalize_base_url=True,
+        reasoning_delta_field="reasoning",
     ),
 }

src/free_claude_code/providers/openai_chat/provider.py

@@ -27,6 +27,7 @@ from free_claude_code.core.anthropic.streaming import (
     tool_schemas_by_name,
 )
 from free_claude_code.core.failures import ExecutionFailure
+from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
 from free_claude_code.core.trace import provider_chat_body_snapshot, trace_event
 from free_claude_code.providers.base import BaseProvider, ProviderConfig
 from free_claude_code.providers.failure_policy import classify_provider_failure
@@ -120,24 +121,30 @@ class OpenAIChatProvider(BaseProvider):
         return extract_openai_model_ids(payload, provider_name=self._provider_name)
 
     def _build_request_body(
-        self, request: MessagesRequest, thinking_enabled: bool | None = None
+        self,
+        request: MessagesRequest,
+        *,
+        reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
     ) -> dict[str, Any]:
         """Build a provider request from the immutable profile."""
         return build_openai_chat_request_body(
             request,
-            thinking_enabled=self._is_thinking_enabled(request, thinking_enabled),
+            reasoning=reasoning,
             policy=self._profile.request_policy,
-            postprocessors=self._profile.postprocessors,
+            postprocessors=self._profile.request_postprocessors,
         )
 
     def preflight_stream(
-        self, request: MessagesRequest, *, thinking_enabled: bool | None = None
+        self,
+        request: MessagesRequest,
+        *,
+        reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
     ) -> None:
         """Validate OpenAI-chat request conversion before streaming."""
-        self._build_request_body(request, thinking_enabled=thinking_enabled)
+        self._build_request_body(request, reasoning=reasoning)
 
     def _handle_extra_reasoning(
-        self, delta: Any, ledger: AnthropicStreamLedger, *, thinking_enabled: bool
+        self, delta: Any, ledger: AnthropicStreamLedger, *, output_reasoning: bool
     ) -> Iterator[str]:
         """Hook for provider-specific reasoning."""
         return iter(())
@@ -254,7 +261,7 @@ class OpenAIChatProvider(BaseProvider):
         input_tokens: int = 0,
         *,
         request_id: str | None = None,
-        thinking_enabled: bool | None = None,
+        reasoning: ReasoningPolicy = DEFAULT_REASONING_POLICY,
     ) -> AsyncIterator[str]:
         """Stream response in Anthropic SSE format."""
         runner = _OpenAIChatStreamRunner(
@@ -262,7 +269,7 @@ class OpenAIChatProvider(BaseProvider):
             request=request,
             input_tokens=input_tokens,
             request_id=request_id,
-            thinking_enabled=thinking_enabled,
+            reasoning=reasoning,
         )
         return runner.run()
 
@@ -277,13 +284,13 @@ class _OpenAIChatStreamRunner:
         request: MessagesRequest,
         input_tokens: int,
         request_id: str | None,
-        thinking_enabled: bool | None,
+        reasoning: ReasoningPolicy,
     ) -> None:
         self._provider = provider
         self._request = request
         self._input_tokens = input_tokens
         self._request_id = request_id
-        self._thinking_enabled = thinking_enabled
+        self._reasoning = reasoning
         self._message_id = f"msg_{uuid.uuid4()}"
         self._tool_calls = OpenAIToolCallAssembler(
             record_extra_content=provider._record_tool_call_extra_content
@@ -307,12 +314,11 @@ class _OpenAIChatStreamRunner:
                 yield from hold_event(event)
 
         body = self._provider._build_request_body(
-            self._request, thinking_enabled=self._thinking_enabled
+            self._request,
+            reasoning=self._reasoning,
         )
         request_stream_usage(body)
-        thinking_enabled = self._provider._is_thinking_enabled(
-            self._request, self._thinking_enabled
-        )
+        output_reasoning = self._reasoning.output_enabled
         trace_event(
             stage="provider",
             event="provider.request.sent",
@@ -362,7 +368,7 @@ class _OpenAIChatStreamRunner:
                             logger.debug("{} finish_reason: {}", tag, finish_reason)
 
                         reasoning = self._provider._profile.reasoning_delta(delta)
-                        if thinking_enabled and reasoning is not None:
+                        if output_reasoning and reasoning is not None:
                             for event in hold_events(ledger.ensure_thinking_block()):
                                 yield event
                             if reasoning:
@@ -374,7 +380,7 @@ class _OpenAIChatStreamRunner:
                         for event in self._provider._handle_extra_reasoning(
                             delta,
                             ledger,
-                            thinking_enabled=thinking_enabled,
+                            output_reasoning=output_reasoning,
                         ):
                             for out_event in hold_event(event):
                                 yield out_event
@@ -382,7 +388,7 @@ class _OpenAIChatStreamRunner:
                         if delta.content:
                             for part in think_parser.feed(delta.content):
                                 if part.type == ContentType.THINKING:
-                                    if not thinking_enabled:
+                                    if not output_reasoning:
                                         continue
                                     for event in hold_events(
                                         ledger.ensure_thinking_block()
@@ -477,7 +483,7 @@ class _OpenAIChatStreamRunner:
                                 ledger=ledger,
                                 error=error,
                                 tool_argument_alias_buffers=tool_argument_alias_buffers,
-                                thinking_enabled=thinking_enabled,
+                                output_reasoning=output_reasoning,
                             )
                         except Exception as recovery_error:
                             trace_event(
@@ -550,7 +556,7 @@ class _OpenAIChatStreamRunner:
         remaining = think_parser.flush()
         if remaining:
             if remaining.type == ContentType.THINKING:
-                if not thinking_enabled:
+                if not output_reasoning:
                     remaining = None
                 else:
                     for event in hold_events(ledger.ensure_thinking_block()):
@@ -701,7 +707,7 @@ class _OpenAIChatStreamRunner:
         ledger: AnthropicStreamLedger,
         error: Exception,
         tool_argument_alias_buffers: dict[int, str],
-        thinking_enabled: bool,
+        output_reasoning: bool,
     ) -> list[str] | None:
         """Build terminal recovery events when the interrupted stream permits it."""
         if not is_retryable_stream_error(error):
@@ -743,7 +749,7 @@ class _OpenAIChatStreamRunner:
 
         recovery_body = make_text_recovery_body(body, partial_text, partial_thinking)
         text, thinking = await self._collect_recovery_text(
-            recovery_body, include_reasoning=thinking_enabled
+            recovery_body, include_reasoning=output_reasoning
         )
         text_suffix = continuation_suffix(partial_text, text)
         thinking_suffix = continuation_suffix(partial_thinking, thinking)

src/free_claude_code/providers/openai_chat/reasoning.py

@@ -0,0 +1,146 @@
+"""Provider-owned reasoning translations for OpenAI-compatible APIs."""
+
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from free_claude_code.core.reasoning import (
+    ReasoningControl,
+    ReasoningEffort,
+    ReasoningPolicy,
+)
+
+EffortValues = tuple[tuple[ReasoningEffort, str], ...]
+
+
+class ReasoningEncoder(Protocol):
+    """Translate provider-neutral reasoning intent into one wire shape."""
+
+    def encode(self, body: dict[str, Any], policy: ReasoningPolicy) -> None: ...
+
+
+@dataclass(frozen=True, slots=True)
+class NoReasoning:
+    """Leave reasoning computation entirely to the upstream provider."""
+
+    def encode(self, body: dict[str, Any], policy: ReasoningPolicy) -> None:
+        return
+
+
+@dataclass(frozen=True, slots=True)
+class NamedEffortReasoning:
+    """Encode a provider's documented named-effort vocabulary."""
+
+    efforts: EffortValues
+    disabled_value: str | bool | None = None
+    enabled_value: str | bool | None = None
+    field: str = "reasoning_effort"
+    budget_field: str | None = None
+    use_extra_body: bool = False
+
+    def encode(self, body: dict[str, Any], policy: ReasoningPolicy) -> None:
+        target = _extra_body(body) if self.use_extra_body else body
+        if policy.control is ReasoningControl.OFF:
+            if self.disabled_value is not None:
+                target[self.field] = self.disabled_value
+            return
+
+        if policy.budget_tokens is not None and self.budget_field is not None:
+            target[self.budget_field] = policy.budget_tokens
+            return
+
+        effort = dict(self.efforts).get(policy.effort)
+        if effort is not None:
+            target[self.field] = effort
+            return
+
+        if policy.control is ReasoningControl.ON and self.enabled_value is not None:
+            target[self.field] = self.enabled_value
+
+
+@dataclass(frozen=True, slots=True)
+class ReasoningObject:
+    """Encode gateways that accept a top-level ``reasoning`` object."""
+
+    efforts: EffortValues
+    supports_budget: bool = True
+
+    def encode(self, body: dict[str, Any], policy: ReasoningPolicy) -> None:
+        if policy.control is ReasoningControl.OFF:
+            _extra_body(body)["reasoning"] = {"enabled": False}
+            return
+
+        reasoning: dict[str, Any] = {}
+        if policy.budget_tokens is not None and self.supports_budget:
+            reasoning["max_tokens"] = policy.budget_tokens
+        elif effort := dict(self.efforts).get(policy.effort):
+            reasoning["effort"] = effort
+        elif policy.control is ReasoningControl.ON:
+            reasoning["enabled"] = True
+
+        if reasoning:
+            _extra_body(body)["reasoning"] = reasoning
+
+
+@dataclass(frozen=True, slots=True)
+class ThinkingObjectReasoning:
+    """Encode providers with an enabled/disabled ``thinking`` object."""
+
+    enabled: dict[str, Any]
+    disabled: dict[str, Any]
+
+    def encode(self, body: dict[str, Any], policy: ReasoningPolicy) -> None:
+        if policy.control is ReasoningControl.OFF:
+            _extra_body(body)["thinking"] = dict(self.disabled)
+        elif policy.requests_reasoning:
+            _extra_body(body)["thinking"] = dict(self.enabled)
+
+
+@dataclass(frozen=True, slots=True)
+class ChatTemplateReasoning:
+    """Encode a provider-wide chat-template boolean without model guessing."""
+
+    field: str = "thinking"
+
+    def encode(self, body: dict[str, Any], policy: ReasoningPolicy) -> None:
+        if not policy.requests_reasoning and policy.control is not ReasoningControl.OFF:
+            return
+        kwargs = _nested_dict(_extra_body(body), "chat_template_kwargs")
+        kwargs[self.field] = policy.control is not ReasoningControl.OFF
+
+
+@dataclass(frozen=True, slots=True)
+class LlamaCppReasoning:
+    """Encode llama.cpp's exact per-request numeric thinking budget."""
+
+    def encode(self, body: dict[str, Any], policy: ReasoningPolicy) -> None:
+        if policy.control is ReasoningControl.OFF:
+            _extra_body(body)["thinking_budget_tokens"] = 0
+        elif policy.budget_tokens is not None:
+            _extra_body(body)["thinking_budget_tokens"] = policy.budget_tokens
+
+
+@dataclass(frozen=True, slots=True)
+class SplitReasoningOutput:
+    """Request separate reasoning output where compute is not controllable."""
+
+    def encode(self, body: dict[str, Any], policy: ReasoningPolicy) -> None:
+        _extra_body(body)["reasoning_split"] = True
+
+
+def _extra_body(body: dict[str, Any]) -> dict[str, Any]:
+    value = body.setdefault("extra_body", {})
+    if not isinstance(value, dict):
+        raise TypeError("OpenAI extra_body must be an object.")
+    return value
+
+
+def _nested_dict(container: dict[str, Any], key: str) -> dict[str, Any]:
+    value = container.setdefault(key, {})
+    if not isinstance(value, dict):
+        raise TypeError(f"{key} must be an object.")
+    return value
+
+
+NO_REASONING = NoReasoning()
+LLAMACPP_REASONING = LlamaCppReasoning()
+SPLIT_REASONING_OUTPUT = SplitReasoningOutput()

src/free_claude_code/providers/openai_chat/request_policy.py

@@ -11,9 +11,12 @@ from free_claude_code.application.errors import InvalidRequestError
 from free_claude_code.core.anthropic import ReasoningReplayMode, build_base_request_body
 from free_claude_code.core.anthropic.conversion import OpenAIConversionError
 from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.reasoning import ReasoningPolicy
 
 MaxTokensField = Literal["max_tokens", "max_completion_tokens"]
-OpenAIChatPostprocessor = Callable[[dict[str, Any], MessagesRequest, bool], None]
+OpenAIChatPostprocessor = Callable[
+    [dict[str, Any], MessagesRequest, ReasoningPolicy], None
+]
 ExtraBodyValidator = Callable[[dict[str, Any]], None]
 
 
@@ -22,12 +25,12 @@ class OpenAIChatRequestPolicy:
     """Provider policy for Anthropic-to-OpenAI chat request conversion."""
 
     provider_name: str
+    reasoning_replay: ReasoningReplayMode
     include_extra_body: bool = False
     extra_body_validator: ExtraBodyValidator | None = None
     reject_extra_body_message: str | None = None
     default_max_tokens: int | None = None
     max_tokens_field: MaxTokensField = "max_tokens"
-    reasoning_replay: ReasoningReplayMode | None = None
     strip_message_names: bool = False
     unsupported_body_keys: frozenset[str] = field(default_factory=frozenset)
     normalize_n_to_one: bool = False
@@ -36,8 +39,7 @@ class OpenAIChatRequestPolicy:
 def build_openai_chat_request_body(
     request_data: MessagesRequest,
     *,
-    thinking_enabled: bool,
-    reasoning_history_enabled: bool | None = None,
+    reasoning: ReasoningPolicy,
     policy: OpenAIChatRequestPolicy,
     postprocessors: Iterable[OpenAIChatPostprocessor] = (),
 ) -> dict[str, Any]:
@@ -49,18 +51,10 @@ def build_openai_chat_request_body(
         len(request_data.messages),
     )
     try:
-        if reasoning_history_enabled is None:
-            reasoning_history_enabled = thinking_enabled
-        if not reasoning_history_enabled:
-            reasoning_replay = ReasoningReplayMode.DISABLED
-        else:
-            reasoning_replay = (
-                policy.reasoning_replay or ReasoningReplayMode.REASONING_CONTENT
-            )
         body = build_base_request_body(
             request_data,
             default_max_tokens=policy.default_max_tokens,
-            reasoning_replay=reasoning_replay,
+            reasoning_replay=policy.reasoning_replay,
         )
     except OpenAIConversionError as exc:
         raise InvalidRequestError(str(exc)) from exc
@@ -81,7 +75,7 @@ def build_openai_chat_request_body(
     _apply_common_openai_chat_policy(body, policy)
 
     for postprocess in postprocessors:
-        postprocess(body, request_data, thinking_enabled)
+        postprocess(body, request_data, reasoning)
 
     logger.debug(
         "{}_REQUEST: conversion done model={} msgs={} tools={}",