Skip to content
Python

Add a reasoning_effort setting translated per provider and recorded per reply (OPE-176)

Devika Verma1746c9ae20ea
diff --git a/coworker/agent.py b/coworker/agent.py
index 8ea2100e..29fde87a 100644
--- a/coworker/agent.py
+++ b/coworker/agent.py
@@ -269,6 +269,9 @@ def build_engine(
# An explicit `max_tokens` from the caller wins over the config value.
if config.max_output_tokens is not None and "max_tokens" not in (model_settings or {}):
model_settings = {**(model_settings or {}), "max_tokens": config.max_output_tokens}
+ # OPE-176: the reasoning-effort level takes the same route; providers translate it.
+ if config.reasoning_effort and "reasoning_effort" not in (model_settings or {}):
+ model_settings = {**(model_settings or {}), "reasoning_effort": config.reasoning_effort}
executor = LocalExecutor(cwd=ws) if ws is not None else None
todo = TodoList()
context = AgentContext(
diff --git a/coworker/config.py b/coworker/config.py
index 60cb69e3..f98f2c76 100644
--- a/coworker/config.py
+++ b/coworker/config.py
@@ -29,6 +29,11 @@ from .secrets import state_dir
DEFAULT_ALLOWED_COMMANDS: list[str] = []
+# Reasoning-effort levels (OPE-176), mirroring Anthropic's vocabulary; each provider
+# maps a level to what its wire accepts (coworker/providers/effort.py).
+EFFORT_LEVELS: tuple[str, ...] = ("low", "medium", "high", "xhigh", "max")
+
+
@dataclass
class Config:
model: str = "gpt-5.6-sol"
@@ -40,6 +45,12 @@ class Config:
# Bedrock 4,096). Anthropic recommends ~64,000 at high effort. Environment override:
# COWORKER_MAX_OUTPUT_TOKENS. Explicit `build_engine(model_settings=...)` wins.
max_output_tokens: Optional[int] = None
+ # How hard the model should think per reply: one of EFFORT_LEVELS. Unset = send no
+ # effort parameter at all (Anthropic's API default is high; Together's default for
+ # Kimi K3 is max), so existing requests are unchanged. Held constant for a whole
+ # session — changing it mid-conversation restarts the prompt cache. Environment
+ # override: COWORKER_REASONING_EFFORT.
+ reasoning_effort: Optional[str] = None
allowed_commands: list[str] = field(
default_factory=lambda: list(DEFAULT_ALLOWED_COMMANDS)
)
@@ -88,6 +99,7 @@ _FIELDS = {
"mode",
"max_iterations",
"max_output_tokens",
+ "reasoning_effort",
"allowed_commands",
"auto_allow",
"allowed_domains",
@@ -139,6 +151,21 @@ def workspace_allowed_commands(workspace: str | Path) -> list[str]:
MAX_OUTPUT_TOKENS_ENV = "COWORKER_MAX_OUTPUT_TOKENS"
+REASONING_EFFORT_ENV = "COWORKER_REASONING_EFFORT"
+
+
+def _effort_level(value: Any, source: str) -> Optional[str]:
+ """`reasoning_effort` must be one of EFFORT_LEVELS (case-insensitive); empty = unset."""
+ if value is None:
+ return None
+ text = str(value).strip().lower()
+ if not text:
+ return None
+ if text not in EFFORT_LEVELS:
+ raise ValueError(
+ f"reasoning_effort must be one of {', '.join(EFFORT_LEVELS)}, got {value!r} ({source})"
+ )
+ return text
def _positive_int(value: Any, source: str) -> Optional[int]:
@@ -186,4 +213,8 @@ def load_config(
except ValueError:
parsed = raw
cfg.max_output_tokens = _positive_int(parsed, MAX_OUTPUT_TOKENS_ENV)
+ cfg.reasoning_effort = _effort_level(cfg.reasoning_effort, "config.toml")
+ raw_effort = os.environ.get(REASONING_EFFORT_ENV)
+ if raw_effort is not None and raw_effort.strip():
+ cfg.reasoning_effort = _effort_level(raw_effort, REASONING_EFFORT_ENV)
return cfg
diff --git a/coworker/engine.py b/coworker/engine.py
index 92ea9dc2..6383bcdf 100644
--- a/coworker/engine.py
+++ b/coworker/engine.py
@@ -576,7 +576,13 @@ class TurnEngine:
if not self._turn_truncated:
self._continuations = 0
_sanitize_mangled_calls(turn)
- self.messages.append(_assistant_message(turn, model=self.model))
+ self.messages.append(
+ _assistant_message(
+ turn,
+ model=self.model,
+ effort_setting=self.model_settings.get("reasoning_effort"),
+ )
+ )
payload: dict[str, Any] = {
"text": turn.text,
"tool_calls": [tc.name for tc in turn.tool_calls],
@@ -591,6 +597,9 @@ class TurnEngine:
if turn.output_limit:
# The output ceiling the provider sent (OPE-177).
payload["max_output_tokens"] = turn.output_limit
+ effort_record = _effort_record(turn, self.model_settings.get("reasoning_effort"))
+ if effort_record:
+ payload["reasoning_effort"] = effort_record
yield Event(EventType.ASSISTANT_MESSAGE, payload)
if not turn.tool_calls:
@@ -2097,6 +2106,7 @@ class TurnEngine:
"usage",
"finish_reason",
"max_output_tokens",
+ "reasoning_effort",
"replay",
)
# Auto-compaction (OPE-27): everything before the boundary is represented by the
@@ -2200,7 +2210,24 @@ class TurnEngine:
return out
-def _assistant_message(turn: AssistantTurn, model: Optional[str] = None) -> dict[str, Any]:
+def _effort_record(turn: AssistantTurn, setting: Optional[str]) -> Optional[dict[str, Any]]:
+ """What the run record says about reasoning effort for this reply (OPE-176): the
+ provider's own mapping when it reported one; otherwise, when a level was configured,
+ an explicit "requested but not reported" so the setting is never silently lost."""
+ if turn.effort:
+ return dict(turn.effort)
+ if setting:
+ return {
+ "requested": setting,
+ "effective": None,
+ "note": "provider did not report an effort parameter (no knob on this path)",
+ }
+ return None
+
+
+def _assistant_message(
+ turn: AssistantTurn, model: Optional[str] = None, effort_setting: Optional[str] = None
+) -> dict[str, Any]:
message: dict[str, Any] = {
"role": "assistant",
"content": turn.text or "",
@@ -2225,6 +2252,11 @@ def _assistant_message(turn: AssistantTurn, model: Optional[str] = None) -> dict
# `length` finish can be read against the limit that produced it. Display
# sidecar like `usage`: stripped before every provider call.
message["max_output_tokens"] = turn.output_limit
+ effort_record = _effort_record(turn, effort_setting)
+ if effort_record:
+ # The reasoning-effort mapping for this reply (OPE-176). Display sidecar like
+ # `usage`: stripped before every provider call.
+ message["reasoning_effort"] = effort_record
if turn.reasoning:
# Display-only thinking text — rendered by the GUI, stripped for every provider
# (`_outbound_messages`); provider-private replay blocks go via `extras` instead.
diff --git a/coworker/providers/anthropic_provider.py b/coworker/providers/anthropic_provider.py
index 7d26de17..6187ccca 100644
--- a/coworker/providers/anthropic_provider.py
+++ b/coworker/providers/anthropic_provider.py
@@ -25,6 +25,7 @@ import json
import re
from typing import Any, Optional
+from .effort import EffortPlan, anthropic_effort, mentions_effort
from .base import (
AssistantTurn,
ModelCapabilities,
@@ -380,6 +381,14 @@ def _reasoning_text(thinking_blocks: list[dict[str, Any]]) -> Optional[str]:
return text or None
+def _effort_record(plan: Optional[EffortPlan], fallback_note: Optional[str]) -> Optional[dict[str, Any]]:
+ if plan is None:
+ return None
+ if fallback_note:
+ return plan.without_param(fallback_note).record()
+ return plan.record()
+
+
def _anthropic_extras(
thinking_blocks: list[dict[str, Any]], stop_reason: Any = None
) -> dict[str, Any]:
@@ -415,6 +424,9 @@ class AnthropicProvider(ProviderClient):
self._secrets = secrets
self.default_model = default_model
self.thinking_budget = thinking_budget or 0
+ # Models whose endpoint rejected `output_config.effort` this run (OPE-176): the
+ # parameter is not sent to them again; the record says so.
+ self._effort_rejected: set[str] = set()
def _ensure_client(self) -> Any:
if self._client is None:
@@ -437,6 +449,7 @@ class AnthropicProvider(ProviderClient):
messages: list[dict[str, Any]],
tools: Optional[list[dict[str, Any]]],
settings: dict[str, Any],
+ effort: Optional[EffortPlan] = None,
) -> dict[str, Any]:
system, converted = convert_messages(messages)
if "stop" in settings and "stop_sequences" not in settings:
@@ -453,6 +466,10 @@ class AnthropicProvider(ProviderClient):
# 4.6+/Claude 5 family: adaptive only (budget_tokens 400s on 4.7+);
# display opt-in or the trace text arrives empty.
filtered["thinking"] = {"type": "adaptive", "display": "summarized"}
+ if effort is not None and effort.params:
+ # OPE-176: a configured level becomes `output_config.effort` (adaptive models)
+ # or the thinking budget (budget-mode models); the floor below still applies.
+ filtered.update(effort.params)
thinking = filtered.get("thinking") or {}
if thinking.get("type") == "enabled":
# Budget must fit under max_tokens.
@@ -493,8 +510,9 @@ class AnthropicProvider(ProviderClient):
tools: Optional[list[dict[str, Any]]] = None,
**settings: Any,
) -> AssistantTurn:
+ plan = self._effort_plan(model, settings)
kwargs = self._request_kwargs(
- model=model, messages=messages, tools=tools, settings=settings
+ model=model, messages=messages, tools=tools, settings=settings, effort=plan
)
client = self._ensure_client()
# Stream-and-accumulate, not a plain create: the SDK REFUSES non-streaming
@@ -504,16 +522,20 @@ class AnthropicProvider(ProviderClient):
# for every Anthropic model (found by the 2026-08-31 eval run; fail-closed,
# so verdicts fell back to asking a human). get_final_message() returns the
# same Message shape create() would.
- if _needs_refusal_fallback(model):
- with client.beta.messages.stream(
- **kwargs,
- betas=[_FALLBACK_BETA],
- fallbacks=[{"model": _FALLBACK_MODEL}],
- ) as stream:
- response = stream.get_final_message()
- else:
- with client.messages.stream(**kwargs) as stream:
- response = stream.get_final_message()
+ def _final(kw: dict[str, Any]) -> Any:
+ if _needs_refusal_fallback(model):
+ with client.beta.messages.stream(
+ **kw,
+ betas=[_FALLBACK_BETA],
+ fallbacks=[{"model": _FALLBACK_MODEL}],
+ ) as stream:
+ return stream.get_final_message()
+ with client.messages.stream(**kw) as stream:
+ return stream.get_final_message()
+
+ response, kwargs, fallback_note = self._call_with_effort_fallback(
+ model, kwargs, _final
+ )
text_parts: list[str] = []
tool_calls: list[ToolCall] = []
@@ -556,11 +578,44 @@ class AnthropicProvider(ProviderClient):
extras=_anthropic_extras(thinking_blocks, stop_reason),
usage=_usage_from(getattr(response, "usage", None)),
output_limit=kwargs.get("max_tokens"),
+ effort=_effort_record(plan, fallback_note),
)
def capabilities(self, model: str) -> ModelCapabilities:
return capabilities_for(model)
+ # -- reasoning effort (OPE-176) ---------------------------------------------------
+
+ def _effort_plan(self, model: str, settings: dict[str, Any]) -> Optional[EffortPlan]:
+ level = settings.get("reasoning_effort")
+ if not level:
+ return None
+ if model in self._effort_rejected:
+ return EffortPlan(
+ str(level),
+ None,
+ {},
+ "endpoint rejected output_config.effort earlier in this run; not sent",
+ )
+ return anthropic_effort(model, str(level), budget_mode=_uses_budget_thinking(model))
+
+ def _call_with_effort_fallback(self, model: str, kwargs: dict[str, Any], fn: Any):
+ """Run `fn(kwargs)`; if the endpoint rejects the effort parameter (HTTP 400 naming
+ it), drop it, remember the model, and run once more. Returns (result, kwargs
+ actually used, fallback note or None). Any other error propagates unchanged."""
+ try:
+ return fn(kwargs), kwargs, None
+ except Exception as exc:
+ if "output_config" in kwargs and mentions_effort(exc):
+ self._effort_rejected.add(model)
+ retry = {k: v for k, v in kwargs.items() if k != "output_config"}
+ return (
+ fn(retry),
+ retry,
+ "endpoint rejected output_config.effort; resent without it",
+ )
+ raise
+
def stream(
self,
*,
@@ -569,19 +624,22 @@ class AnthropicProvider(ProviderClient):
tools: Optional[list[dict[str, Any]]] = None,
**settings: Any,
):
+ plan = self._effort_plan(model, settings)
kwargs = self._request_kwargs(
- model=model, messages=messages, tools=tools, settings=settings
+ model=model, messages=messages, tools=tools, settings=settings, effort=plan
)
kwargs["stream"] = True
client = self._ensure_client()
- if _needs_refusal_fallback(model):
- events = client.beta.messages.create(
- **kwargs,
- betas=[_FALLBACK_BETA],
- fallbacks=[{"model": _FALLBACK_MODEL}],
- )
- else:
- events = client.messages.create(**kwargs)
+ def _open(kw: dict[str, Any]) -> Any:
+ if _needs_refusal_fallback(model):
+ return client.beta.messages.create(
+ **kw,
+ betas=[_FALLBACK_BETA],
+ fallbacks=[{"model": _FALLBACK_MODEL}],
+ )
+ return client.messages.create(**kw)
+
+ events, kwargs, fallback_note = self._call_with_effort_fallback(model, kwargs, _open)
text_parts: list[str] = []
tool_accum: dict[int, dict[str, str]] = {}
@@ -678,5 +736,6 @@ class AnthropicProvider(ProviderClient):
extras=_anthropic_extras(thinking_blocks, stop_reason),
usage=usage,
output_limit=kwargs.get("max_tokens"),
+ effort=_effort_record(plan, fallback_note),
)
)
diff --git a/coworker/providers/base.py b/coworker/providers/base.py
index 694b3d8c..6799b4b6 100644
--- a/coworker/providers/base.py
+++ b/coworker/providers/base.py
@@ -77,6 +77,11 @@ class AssistantTurn:
# provider left it to the server. Persisted on the assistant message as the
# `max_output_tokens` sidecar so a run record states its ceiling (OPE-177).
output_limit: Optional[int] = None
+ # The reasoning-effort mapping used for this request (OPE-176):
+ # {requested, effective, param?, note?} — see providers/effort.py. None when no
+ # level was configured or the provider has no such knob. Persisted on the
+ # assistant message as the `reasoning_effort` sidecar.
+ effort: Optional[dict[str, Any]] = None
@property
def has_tool_calls(self) -> bool:
diff --git a/coworker/providers/effort.py b/coworker/providers/effort.py
new file mode 100644
index 00000000..d7cf5b10
--- /dev/null
+++ b/coworker/providers/effort.py
@@ -0,0 +1,174 @@
+"""Reasoning-effort levels and their per-provider translation (OPE-176).
+
+One setting, `reasoning_effort`, five levels mirroring Anthropic's: low, medium, high,
+xhigh, max. Unset means "send nothing" — every provider's request stays byte-identical to
+before the setting existed (Anthropic's API default is `high`; Together's default for
+Kimi K3 is `max`). Each provider client translates a level into the parameter its wire
+accepts, records what it actually sent, and falls back (once, per model, per run) when
+the endpoint rejects the parameter.
+
+Level names a model does not accept map to the NEAREST accepted level by rank, ties going
+UP (xhigh on Kimi K3 → max; medium on Kimi K3 → high). The mapping is recorded on every
+reply as `{requested, effective, param, note}` so a run record states its effort.
+
+Sources (read 2026-09-08): platform.claude.com/docs/en/build-with-claude/effort (supported
+models per level; `high` == omitted; hold the level constant within a conversation or
+the prompt cache restarts); Moonshot/Together Kimi K3 docs (`reasoning_effort` low/high/max,
+default max).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional, Sequence
+
+from ..config import EFFORT_LEVELS
+
+_RANK = {level: i for i, level in enumerate(EFFORT_LEVELS)}
+
+
+@dataclass(frozen=True)
+class EffortPlan:
+ requested: str
+ # The level/value actually sent; None when nothing was sent (unsupported, rejected).
+ effective: Optional[str]
+ # Provider request parameters to merge (empty when nothing is sent).
+ params: dict[str, Any] = field(default_factory=dict)
+ note: str = ""
+
+ def record(self) -> dict[str, Any]:
+ """The sidecar persisted on the assistant message / run record."""
+ out: dict[str, Any] = {"requested": self.requested, "effective": self.effective}
+ if self.params:
+ out["param"] = self.params
+ if self.note:
+ out["note"] = self.note
+ return out
+
+ def without_param(self, note: str) -> "EffortPlan":
+ """The plan after the endpoint rejected the parameter and it was dropped."""
+ return EffortPlan(self.requested, None, {}, note)
+
+
+def validate_level(value: Any, source: str = "reasoning_effort") -> Optional[str]:
+ """Normalise a configured value to one of EFFORT_LEVELS (case-insensitive) or raise."""
+ if value is None:
+ return None
+ text = str(value).strip().lower()
+ if not text:
+ return None
+ if text not in _RANK:
+ raise ValueError(
+ f"{source} must be one of {', '.join(EFFORT_LEVELS)}; got {value!r}"
+ )
+ return text
+
+
+def nearest_supported(level: str, supported: Sequence[str]) -> Optional[str]:
+ """The accepted level closest in rank to `level`; ties resolve to the higher one."""
+ if not supported:
+ return None
+ if level in supported:
+ return level
+ target = _RANK[level]
+ return min(supported, key=lambda s: (abs(_RANK[s] - target), -_RANK[s]))
+
+
+# -- Anthropic -----------------------------------------------------------------------
+
+_ALL = tuple(EFFORT_LEVELS)
+_NO_XHIGH = ("low", "medium", "high", "max")
+# Longest prefix wins. Per the effort doc's "Supported models" + per-level availability.
+_ANTHROPIC_EFFORT: tuple[tuple[str, tuple[str, ...]], ...] = (
+ ("claude-fable-5-1", _ALL),
+ ("claude-mythos-5-1", _ALL),
+ ("claude-fable-5", _ALL),
+ ("claude-mythos-5", _ALL),
+ ("claude-mythos-preview", _NO_XHIGH),
+ ("claude-opus-5", _ALL),
+ ("claude-opus-4-8", _ALL),
+ ("claude-opus-4-7", _ALL),
+ ("claude-opus-4-6", _NO_XHIGH),
+ ("claude-opus-4-5", ("low", "medium", "high")),
+ ("claude-sonnet-5", _ALL),
+ ("claude-sonnet-4-6", _NO_XHIGH),
+)
+# Budget-thinking models (older Claude): the level becomes a thinking budget. Anthropic
+# requires budget_tokens >= 1,024 and < max_tokens; the provider floors max_tokens.
+BUDGET_TOKENS_BY_LEVEL = {
+ "low": 2_048,
+ "medium": 8_192,
+ "high": 16_000,
+ "xhigh": 24_000,
+ "max": 32_000,
+}
+
+
+def _anthropic_supported(model: str) -> Optional[tuple[str, ...]]:
+ best: Optional[tuple[str, ...]] = None
+ best_len = -1
+ for prefix, levels in _ANTHROPIC_EFFORT:
+ if model.startswith(prefix) and len(prefix) > best_len:
+ best, best_len = levels, len(prefix)
+ return best
+
+
+def anthropic_effort(model: str, level: str, *, budget_mode: bool) -> EffortPlan:
+ """`output_config.effort` on adaptive-thinking models; `thinking.budget_tokens` on
+ budget-mode models. Unknown adaptive models get the level as-is (the 400 fallback
+ covers a wrong guess); the mapping is recorded either way."""
+ if budget_mode:
+ budget = BUDGET_TOKENS_BY_LEVEL[level]
+ return EffortPlan(
+ level,
+ level,
+ {"thinking": {"type": "enabled", "budget_tokens": budget}},
+ f"budget-thinking model: {level} -> budget_tokens {budget}",
+ )
+ supported = _anthropic_supported(model)
+ if supported is None:
+ return EffortPlan(
+ level,
+ level,
+ {"output_config": {"effort": level}},
+ "model not in the documented effort table; sent unverified",
+ )
+ effective = nearest_supported(level, supported)
+ assert effective is not None
+ note = "" if effective == level else f"{level} not accepted by {model}; sent {effective}"
+ return EffortPlan(level, effective, {"output_config": {"effort": effective}}, note)
+
+
+# -- OpenAI-compatible endpoints (Together, Moonshot, DeepSeek, …) -------------------
+
+# Bare model id (as the OpenAI-compatible client receives it) → accepted values.
+# Only rows with a verified source; everything else gets the OpenAI vocabulary.
+_OPENAI_COMPAT: dict[str, tuple[str, ...]] = {
+ # Kimi K3: Moonshot and Together document reasoning_effort low / high / max.
+ "moonshotai/Kimi-K3": ("low", "high", "max"),
+ "kimi-k3": ("low", "high", "max"),
+}
+_OPENAI_DEFAULT = ("low", "medium", "high")
+
+
+def openai_compat_effort(model: str, level: str) -> EffortPlan:
+ supported = _OPENAI_COMPAT.get(model) or _OPENAI_COMPAT.get(model.lower()) or _OPENAI_DEFAULT
+ effective = nearest_supported(level, supported)
+ assert effective is not None
+ verified = model in _OPENAI_COMPAT or model.lower() in _OPENAI_COMPAT
+ note = ""
+ if effective != level:
+ note = f"{level} not accepted by {model}; sent {effective}"
+ elif not verified:
+ note = "model not in the verified table; OpenAI vocabulary assumed"
+ return EffortPlan(level, effective, {"reasoning_effort": effective}, note)
+
+
+def unsupported(level: str, why: str) -> EffortPlan:
+ return EffortPlan(level, None, {}, why)
+
+
+def mentions_effort(exc: BaseException) -> bool:
+ """Does an endpoint error name the effort parameter (so dropping it is the fix)?"""
+ msg = str(exc).lower()
+ return "effort" in msg or "output_config" in msg
diff --git a/coworker/providers/openai_provider.py b/coworker/providers/openai_provider.py
index c98d0352..0ec70c6c 100644
--- a/coworker/providers/openai_provider.py
+++ b/coworker/providers/openai_provider.py
@@ -14,6 +14,7 @@ import json
import re
from typing import Any, Optional
+from .effort import EffortPlan, mentions_effort, openai_compat_effort
from .base import (
AssistantTurn,
ModelCapabilities,
@@ -100,6 +101,16 @@ def _param_fix_retry(kwargs: dict[str, Any], exc: Exception) -> dict[str, Any]:
msg = str(exc).lower()
if _EFFORT_ERROR in msg and kwargs.get("reasoning_effort") != "none":
return {**kwargs, "reasoning_effort": "none"}
+ if (
+ "reasoning_effort" in kwargs
+ and kwargs.get("reasoning_effort") != "none"
+ and ("reasoning_effort" in msg or "effort" in msg)
+ ):
+ # OPE-176: the endpoint has no effort knob under that name — drop it and run on
+ # the server default; the reply's `effort` record says it was rejected.
+ fixed = dict(kwargs)
+ fixed.pop("reasoning_effort")
+ return fixed
if _MAX_TOKENS_ERROR in msg and "max_tokens" in kwargs:
fixed = dict(kwargs)
fixed["max_completion_tokens"] = fixed.pop("max_tokens")
@@ -120,6 +131,23 @@ def _param_fix_retry(kwargs: dict[str, Any], exc: Exception) -> dict[str, Any]:
raise exc
+def _effort_record(plan: Optional[EffortPlan], kwargs: dict[str, Any]) -> Optional[dict[str, Any]]:
+ """The effort record for a reply, read from the kwargs that were finally sent (after
+ the param-fix retries may have dropped or pinned the parameter)."""
+ if plan is None:
+ return None
+ if not plan.params:
+ return plan.record()
+ sent = kwargs.get("reasoning_effort")
+ if sent is None:
+ return plan.without_param("endpoint rejected reasoning_effort; resent without it").record()
+ if sent != plan.effective:
+ return EffortPlan(
+ plan.requested, str(sent), {"reasoning_effort": sent}, f"endpoint accepted only {sent}"
+ ).record()
+ return plan.record()
+
+
def _output_limit(kwargs: dict[str, Any]) -> Optional[int]:
"""The completion ceiling actually sent, after `_param_fix_retry` may have renamed
`max_tokens` to `max_completion_tokens` or dropped it (server default -> None)."""
@@ -193,6 +221,7 @@ class OpenAIProvider(ProviderClient):
tools: Optional[list[dict[str, Any]]] = None,
**settings: Any,
) -> AssistantTurn:
+ plan = self._effort_plan(model, settings)
kwargs: dict[str, Any] = {
"model": model,
"messages": _strip_foreign_sidecars(messages),
@@ -201,6 +230,8 @@ class OpenAIProvider(ProviderClient):
if tools:
kwargs["tools"] = tools
kwargs.setdefault("max_tokens", DEFAULT_MAX_TOKENS)
+ if plan is not None and plan.params:
+ kwargs.update(plan.params)
_pin_reasoning_effort(kwargs)
client = self._ensure_client()
@@ -227,11 +258,35 @@ class OpenAIProvider(ProviderClient):
reasoning=_delta_reasoning(message),
usage=_usage_from(getattr(response, "usage", None)),
output_limit=_output_limit(kwargs),
+ effort=self._note_effort(model, plan, kwargs),
)
def capabilities(self, model: str) -> ModelCapabilities:
return capabilities_for(model)
+ # -- reasoning effort (OPE-176) ---------------------------------------------------
+
+ def _effort_plan(self, model: str, settings: dict[str, Any]) -> Optional[EffortPlan]:
+ """Pop the engine-level `reasoning_effort` setting (it must never ride the wire
+ unmapped) and translate it for this model; None when unset."""
+ level = settings.pop("reasoning_effort", None)
+ if not level:
+ return None
+ rejected = self.__dict__.setdefault("_effort_rejected", set())
+ if model in rejected:
+ return EffortPlan(
+ str(level), None, {}, "endpoint rejected reasoning_effort earlier in this run; not sent"
+ )
+ return openai_compat_effort(model, str(level))
+
+ def _note_effort(
+ self, model: str, plan: Optional[EffortPlan], kwargs: dict[str, Any]
+ ) -> Optional[dict[str, Any]]:
+ record = _effort_record(plan, kwargs)
+ if plan is not None and plan.params and kwargs.get("reasoning_effort") is None:
+ self.__dict__.setdefault("_effort_rejected", set()).add(model)
+ return record
+
def stream(
self,
*,
@@ -240,6 +295,7 @@ class OpenAIProvider(ProviderClient):
tools: Optional[list[dict[str, Any]]] = None,
**settings: Any,
):
+ plan = self._effort_plan(model, settings)
kwargs: dict[str, Any] = {
"model": model,
"messages": _strip_foreign_sidecars(messages),
@@ -252,6 +308,8 @@ class OpenAIProvider(ProviderClient):
if tools:
kwargs["tools"] = tools
kwargs.setdefault("max_tokens", DEFAULT_MAX_TOKENS)
+ if plan is not None and plan.params:
+ kwargs.update(plan.params)
_pin_reasoning_effort(kwargs)
client = self._ensure_client()
@@ -326,6 +384,7 @@ class OpenAIProvider(ProviderClient):
reasoning="".join(reasoning_parts) or None,
usage=usage,
output_limit=_output_limit(kwargs),
+ effort=self._note_effort(model, plan, kwargs),
)
)
diff --git a/docs/config.example.toml b/docs/config.example.toml
index b3b6b0c9..b3c592bb 100644
--- a/docs/config.example.toml
+++ b/docs/config.example.toml
@@ -10,6 +10,11 @@ max_iterations = 12 # max model<->tool iterations per turn before stopp
# max_output_tokens = 64000 # per-reply output cap sent as max_tokens (thinking + text +
# tool arguments). Unset = provider default (32000; Bedrock
# 4096). Env override: COWORKER_MAX_OUTPUT_TOKENS.
+# reasoning_effort = "high" # low | medium | high | xhigh | max — how hard the model thinks
+ # per reply, translated per provider (Anthropic output_config
+ # .effort; Together/Moonshot reasoning_effort). Unset = provider
+ # default (Anthropic high, Kimi K3 max). Env override:
+ # COWORKER_REASONING_EFFORT.
# Commands auto-allowed without an approval prompt (prefix match).
allowed_commands = [
diff --git a/tests/test_reasoning_effort.py b/tests/test_reasoning_effort.py
new file mode 100644
index 00000000..fecc6506
--- /dev/null
+++ b/tests/test_reasoning_effort.py
@@ -0,0 +1,387 @@
+"""OPE-176: the `reasoning_effort` setting, its per-provider translation and its record.
+
+Unset keeps every request byte-identical to before (Anthropic = API default high, Kimi K3
+on Together = its default max). Set, the level travels via `model_settings`, each provider
+maps it to its own parameter, drops it once per model if the endpoint rejects it, and the
+engine persists `{requested, effective, param, note}` on every assistant message.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import contextmanager
+from types import SimpleNamespace
+
+import aisuite as ai
+import pytest
+from coworker.agent import build_code_engine
+from coworker.config import EFFORT_LEVELS, load_config
+from coworker.engine import TurnEngine, _assistant_message
+from coworker.events import EventType
+from coworker.permissions import PermissionEngine
+from coworker.providers import (
+ AnthropicProvider,
+ AssistantTurn,
+ ModelCapabilities,
+ OpenAIProvider,
+ ProviderClient,
+)
+from coworker.providers.anthropic_provider import _uses_budget_thinking
+from coworker.providers.effort import (
+ BUDGET_TOKENS_BY_LEVEL,
+ anthropic_effort,
+ nearest_supported,
+ openai_compat_effort,
+ validate_level,
+)
+from coworker.providers.matrix import MATRIX
+from coworker.tools import ToolRegistry
+
+# -- levels and config --------------------------------------------------------------
+
+
+def test_levels_are_anthropics_five_in_order():
+ assert EFFORT_LEVELS == ("low", "medium", "high", "xhigh", "max")
+
+
[email protected]("raw,expected", [("high", "high"), (" XHigh ", "xhigh"), ("", None), (None, None)])
+def test_validate_level_normalises(raw, expected):
+ assert validate_level(raw) == expected
+
+
[email protected]("bad", ["highest", "adaptive", "1", "none"])
+def test_validate_level_rejects_unknown(bad):
+ with pytest.raises(ValueError, match="reasoning_effort"):
+ validate_level(bad)
+
+
+def test_config_default_unset_and_layering(tmp_path, monkeypatch):
+ g = tmp_path / "global.toml"
+ assert load_config(global_path=tmp_path / "nope.toml").reasoning_effort is None
+ g.write_text('reasoning_effort = "medium"\n')
+ assert load_config(global_path=g).reasoning_effort == "medium"
+ ws = tmp_path / "ws"
+ (ws / ".coworker").mkdir(parents=True)
+ (ws / ".coworker" / "config.toml").write_text('reasoning_effort = "XHIGH"\n')
+ assert load_config(ws, global_path=g).reasoning_effort == "xhigh"
+ monkeypatch.setenv("COWORKER_REASONING_EFFORT", "low")
+ assert load_config(ws, global_path=g).reasoning_effort == "low"
+ monkeypatch.setenv("COWORKER_REASONING_EFFORT", "turbo")
+ with pytest.raises(ValueError, match="COWORKER_REASONING_EFFORT"):
+ load_config(ws, global_path=g)
+
+
+# -- build_engine ---------------------------------------------------------------------
+
+
+class _Stub(ProviderClient):
+ def complete(self, **k): # pragma: no cover
+ raise NotImplementedError
+
+ def capabilities(self, m):
+ return ModelCapabilities()
+
+
+def _engine_with_config(tmp_path, toml, **kwargs):
+ (tmp_path / ".coworker").mkdir(exist_ok=True)
+ (tmp_path / ".coworker" / "config.toml").write_text(toml)
+ return build_code_engine(workspace=tmp_path, provider=_Stub(), **kwargs)
+
+
+def test_build_engine_threads_the_level_into_model_settings(tmp_path):
+ engine = _engine_with_config(tmp_path, 'reasoning_effort = "xhigh"\nmax_output_tokens = 64000\n')
+ try:
+ assert engine.model_settings == {"max_tokens": 64000, "reasoning_effort": "xhigh"}
+ finally:
+ engine.executor.close()
+
+
+def test_build_engine_explicit_setting_wins_and_unset_is_empty(tmp_path):
+ engine = _engine_with_config(
+ tmp_path, 'reasoning_effort = "xhigh"\n', model_settings={"reasoning_effort": "low"}
+ )
+ try:
+ assert engine.model_settings["reasoning_effort"] == "low"
+ finally:
+ engine.executor.close()
+ (tmp_path / "b").mkdir()
+ engine = _engine_with_config(tmp_path / "b", "max_iterations = 3\n")
+ try:
+ assert engine.model_settings == {}
+ finally:
+ engine.executor.close()
+
+
+# -- mapping tables -------------------------------------------------------------------
+
+
+def test_nearest_supported_ties_go_up():
+ assert nearest_supported("xhigh", ("low", "high", "max")) == "max"
+ assert nearest_supported("medium", ("low", "high", "max")) == "high"
+ assert nearest_supported("xhigh", ("low", "medium", "high")) == "high"
+ assert nearest_supported("max", ("low", "medium", "high")) == "high"
+ assert nearest_supported("high", ("low", "high", "max")) == "high"
+ assert nearest_supported("low", ()) is None
+
+
+ "model,level,effective",
+ [
+ ("claude-fable-5-1", "xhigh", "xhigh"),
+ ("claude-fable-5-1", "max", "max"),
+ ("claude-sonnet-5", "low", "low"),
+ ("claude-opus-5", "medium", "medium"),
+ ("claude-sonnet-4-6", "xhigh", "max"), # no xhigh on 4.6 → nearest, tie up
+ ("claude-opus-4-5-20251101", "max", "high"), # low/medium/high only
+ ("claude-opus-4-6", "xhigh", "max"),
+ ],
+)
+def test_anthropic_adaptive_mapping(model, level, effective):
+ plan = anthropic_effort(model, level, budget_mode=False)
+ assert plan.effective == effective
+ assert plan.params == {"output_config": {"effort": effective}}
+ assert (plan.note == "") == (effective == level)
+
+
+def test_anthropic_budget_mode_mapping():
+ for level in EFFORT_LEVELS:
+ plan = anthropic_effort("claude-haiku-4-5", level, budget_mode=True)
+ assert plan.params == {"thinking": {"type": "enabled", "budget_tokens": BUDGET_TOKENS_BY_LEVEL[level]}}
+ assert plan.effective == level
+ assert BUDGET_TOKENS_BY_LEVEL["low"] >= 1024 # Anthropic minimum
+
+
+def test_anthropic_unknown_model_sends_level_unverified():
+ plan = anthropic_effort("claude-next-9", "xhigh", budget_mode=False)
+ assert plan.params == {"output_config": {"effort": "xhigh"}} and "unverified" in plan.note
+
+
+ "model,level,effective,noted",
+ [
+ ("moonshotai/Kimi-K3", "high", "high", False),
+ ("moonshotai/Kimi-K3", "max", "max", False),
+ ("moonshotai/Kimi-K3", "xhigh", "max", True),
+ ("moonshotai/Kimi-K3", "medium", "high", True),
+ ("deepseek-ai/DeepSeek-V4-Pro", "max", "high", True), # unverified → OpenAI vocabulary
+ ("gpt-5.6-sol", "medium", "medium", True), # unverified table → note, value as-is
+ ],
+)
+def test_openai_compat_mapping(model, level, effective, noted):
+ plan = openai_compat_effort(model, level)
+ assert plan.effective == effective
+ assert plan.params == {"reasoning_effort": effective}
+ assert bool(plan.note) == noted
+
+
+def test_every_curated_model_resolves_every_level():
+ """No level on any curated row may raise; providers without a knob are simply skipped."""
+ for mid in MATRIX:
+ provider, _, bare = mid.partition(":") if ":" in mid else ("openai", "", mid)
+ for level in EFFORT_LEVELS:
+ if provider == "anthropic":
+ plan = anthropic_effort(bare, level, budget_mode=_uses_budget_thinking(bare))
+ elif provider in ("gemini", "bedrock", "vertex", "ark", "ark-agent-plan-cn", "openai-codex", "openai"):
+ continue # no chat-completions effort knob on these paths (recorded as such)
+ else:
+ plan = openai_compat_effort(bare, level)
+ assert plan.requested == level and plan.effective in EFFORT_LEVELS, (mid, level)
+
+
+# -- Anthropic provider ---------------------------------------------------------------
+
+
+class _FakeAnthropic:
+ def __init__(self, response=None, events=None, *, reject_effort=False):
+ self.kwargs_seen: list[dict] = []
+ self._reject = reject_effort
+
+ def _check(kwargs):
+ self.kwargs_seen.append(kwargs)
+ if self._reject and "output_config" in kwargs:
+ raise RuntimeError("400: output_config.effort: Extra inputs are not permitted")
+
+ def create(**kwargs):
+ _check(kwargs)
+ if kwargs.get("stream"):
+ return iter(events or [])
+ return response
+
+ @contextmanager
+ def stream(**kwargs):
+ _check(kwargs)
+ yield SimpleNamespace(get_final_message=lambda: response)
+
+ self.messages = SimpleNamespace(create=create, stream=stream)
+ self.beta = SimpleNamespace(messages=SimpleNamespace(create=create, stream=stream))
+
+ @property
+ def kwargs(self):
+ return self.kwargs_seen[-1]
+
+
+def _anthropic_response():
+ return SimpleNamespace(content=[SimpleNamespace(type="text", text="hi")], stop_reason="end_turn")
+
+
+def _anthropic_events():
+ return [
+ SimpleNamespace(type="content_block_start", index=0, content_block=SimpleNamespace(type="text", text="")),
+ SimpleNamespace(type="content_block_delta", index=0, delta=SimpleNamespace(type="text_delta", text="hi")),
+ SimpleNamespace(type="message_delta", delta=SimpleNamespace(stop_reason="end_turn")),
+ ]
+
+
+def test_anthropic_unset_sends_no_effort_field():
+ fake = _FakeAnthropic(response=_anthropic_response())
+ turn = AnthropicProvider(client=fake).complete(model="claude-sonnet-5", messages=[{"role": "user", "content": "x"}])
+ assert "output_config" not in fake.kwargs and "reasoning_effort" not in fake.kwargs
+ assert turn.effort is None
+
+
+def test_anthropic_complete_and_stream_send_output_config():
+ fake = _FakeAnthropic(response=_anthropic_response(), events=_anthropic_events())
+ provider = AnthropicProvider(client=fake)
+ turn = provider.complete(model="claude-fable-5-1", messages=[{"role": "user", "content": "x"}], reasoning_effort="xhigh")
+ assert fake.kwargs["output_config"] == {"effort": "xhigh"}
+ assert "reasoning_effort" not in fake.kwargs
+ assert turn.effort == {"requested": "xhigh", "effective": "xhigh", "param": {"output_config": {"effort": "xhigh"}}}
+ chunks = list(provider.stream(model="claude-fable-5-1", messages=[{"role": "user", "content": "x"}], reasoning_effort="low"))
+ assert fake.kwargs["output_config"] == {"effort": "low"}
+ assert chunks[-1].turn.effort["effective"] == "low"
+
+
+def test_anthropic_budget_model_maps_to_budget_and_floors_max_tokens():
+ fake = _FakeAnthropic(response=_anthropic_response())
+ turn = AnthropicProvider(client=fake).complete(model="claude-haiku-4-5", messages=[{"role": "user", "content": "x"}], reasoning_effort="max")
+ assert fake.kwargs["thinking"] == {"type": "enabled", "budget_tokens": 32_000}
+ assert fake.kwargs["max_tokens"] > 32_000
+ assert "output_config" not in fake.kwargs
+ assert turn.effort["effective"] == "max" and "budget_tokens" in turn.effort["note"]
+
+
+def test_anthropic_rejection_falls_back_once_and_is_remembered():
+ fake = _FakeAnthropic(response=_anthropic_response(), reject_effort=True)
+ provider = AnthropicProvider(client=fake)
+ turn = provider.complete(model="claude-sonnet-5", messages=[{"role": "user", "content": "x"}], reasoning_effort="low")
+ assert len(fake.kwargs_seen) == 2 # rejected, then resent without the field
+ assert "output_config" not in fake.kwargs
+ assert turn.effort["requested"] == "low" and turn.effort["effective"] is None
+ assert "rejected" in turn.effort["note"]
+ # Next call on the same model does not try again.
+ turn2 = provider.complete(model="claude-sonnet-5", messages=[{"role": "user", "content": "y"}], reasoning_effort="low")
+ assert len(fake.kwargs_seen) == 3 and "output_config" not in fake.kwargs
+ assert turn2.effort["effective"] is None
+
+
+def test_anthropic_unrelated_error_still_raises():
+ class _Boom(_FakeAnthropic):
+ pass
+
+ fake = _Boom(response=_anthropic_response())
+
+ def create(**kwargs):
+ raise RuntimeError("overloaded_error")
+
+ fake.messages = SimpleNamespace(create=create, stream=fake.messages.stream)
+ with pytest.raises(RuntimeError, match="overloaded"):
+ list(AnthropicProvider(client=fake).stream(model="claude-sonnet-5", messages=[{"role": "user", "content": "x"}], reasoning_effort="low"))
+
+
+# -- OpenAI-compatible provider -------------------------------------------------------
+
+
+class _FakeOpenAI:
+ def __init__(self, *, response=None, stream_chunks=None, reject_effort=False):
+ self.calls: list[dict] = []
+ self._reject = reject_effort
+
+ def create(**kwargs):
+ self.calls.append(kwargs)
+ if self._reject and "reasoning_effort" in kwargs:
+ raise RuntimeError("Unrecognized request argument supplied: reasoning_effort")
+ return stream_chunks if kwargs.get("stream") else response
+
+ self.chat = SimpleNamespace(completions=SimpleNamespace(create=create))
+
+
+def _openai_response():
+ return SimpleNamespace(choices=[SimpleNamespace(message=SimpleNamespace(content="hi", tool_calls=None), finish_reason="stop")], usage=None)
+
+
+def _openai_chunks():
+ return [SimpleNamespace(choices=[SimpleNamespace(delta=SimpleNamespace(content="hi", tool_calls=None), finish_reason="stop")], usage=None)]
+
+
+def test_openai_compat_unset_sends_nothing():
+ fake = _FakeOpenAI(response=_openai_response())
+ turn = OpenAIProvider(client=fake).complete(model="moonshotai/Kimi-K3", messages=[{"role": "user", "content": "x"}])
+ assert "reasoning_effort" not in fake.calls[-1] and turn.effort is None
+
+
+def test_openai_compat_kimi_sends_mapped_value_on_both_paths():
+ fake = _FakeOpenAI(response=_openai_response(), stream_chunks=_openai_chunks())
+ provider = OpenAIProvider(client=fake)
+ turn = provider.complete(model="moonshotai/Kimi-K3", messages=[{"role": "user", "content": "x"}], reasoning_effort="high")
+ assert fake.calls[-1]["reasoning_effort"] == "high"
+ assert turn.effort == {"requested": "high", "effective": "high", "param": {"reasoning_effort": "high"}}
+ chunks = list(provider.stream(model="moonshotai/Kimi-K3", messages=[{"role": "user", "content": "x"}], reasoning_effort="xhigh"))
+ assert fake.calls[-1]["reasoning_effort"] == "max"
+ assert chunks[-1].turn.effort["effective"] == "max" and "sent max" in chunks[-1].turn.effort["note"]
+
+
+def test_openai_compat_rejection_drops_the_parameter_and_records_it():
+ fake = _FakeOpenAI(response=_openai_response(), reject_effort=True)
+ provider = OpenAIProvider(client=fake)
+ turn = provider.complete(model="some/other-model", messages=[{"role": "user", "content": "x"}], reasoning_effort="high")
+ assert len(fake.calls) == 2 and "reasoning_effort" not in fake.calls[-1]
+ assert turn.effort["effective"] is None and "rejected" in turn.effort["note"]
+ provider.complete(model="some/other-model", messages=[{"role": "user", "content": "y"}], reasoning_effort="high")
+ assert len(fake.calls) == 3 and "reasoning_effort" not in fake.calls[-1]
+
+
+# -- engine record --------------------------------------------------------------------
+
+
+class _EffortProvider(ProviderClient):
+ def __init__(self, effort):
+ self._effort = effort
+
+ def complete(self, *, model, messages, tools=None, **settings):
+ return AssistantTurn(text="done", finish_reason="stop", effort=self._effort)
+
+ def capabilities(self, model):
+ return ModelCapabilities()
+
+
+def _run(tmp_path, provider, **engine_kwargs):
+ registry = ToolRegistry()
+ registry.register_all(ai.toolkits.files(root=str(tmp_path), allow_write=True))
+ engine = TurnEngine(provider=provider, registry=registry, permissions=PermissionEngine(workspace_root=tmp_path), model="m", **engine_kwargs)
+
+ async def _collect():
+ return [ev async for ev in engine.run("hello")]
+
+ return engine, asyncio.run(_collect())
+
+
+def test_engine_persists_the_provider_record_and_strips_it_outbound(tmp_path):
+ rec = {"requested": "xhigh", "effective": "xhigh", "param": {"output_config": {"effort": "xhigh"}}}
+ engine, events = _run(tmp_path, _EffortProvider(rec), model_settings={"reasoning_effort": "xhigh"})
+ assistant = next(ev for ev in events if ev.type == EventType.ASSISTANT_MESSAGE)
+ assert assistant.data["reasoning_effort"] == rec
+ persisted = next(m for m in engine.messages if m.get("role") == "assistant")
+ assert persisted["reasoning_effort"] == rec
+ assert all("reasoning_effort" not in m for m in engine._outbound_messages())
+
+
+def test_engine_records_a_requested_level_even_when_the_provider_reports_nothing(tmp_path):
+ engine, _ = _run(tmp_path, _EffortProvider(None), model_settings={"reasoning_effort": "low"})
+ persisted = next(m for m in engine.messages if m.get("role") == "assistant")
+ assert persisted["reasoning_effort"]["requested"] == "low"
+ assert persisted["reasoning_effort"]["effective"] is None
+ assert "not report" in persisted["reasoning_effort"]["note"]
+
+
+def test_no_record_when_unset():
+ assert "reasoning_effort" not in _assistant_message(AssistantTurn(text="x"))