ouroboros-ai 0.42.2.dev4__tar.gz → 0.42.2.dev6__tar.gz

{ouroboros_ai-0.42.2.dev4 → ouroboros_ai-0.42.2.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.42.2.dev4
+Version: 0.42.2.dev6
 Summary: Specification-first workflow engine for AI coding agents. Works with Claude Code and Codex CLI.
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE

{ouroboros_ai-0.42.2.dev4 → ouroboros_ai-0.42.2.dev6}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.42.2.dev4'
-__version_tuple__ = version_tuple = (0, 42, 2, 'dev4')
+__version__ = version = '0.42.2.dev6'
+__version_tuple__ = version_tuple = (0, 42, 2, 'dev6')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.42.2.dev4 → ouroboros_ai-0.42.2.dev6}/src/ouroboros/orchestrator/coordinator.py

@@ -215,6 +215,13 @@ class LevelCoordinator:
         self._task_cwd = task_cwd
         self._level_runtime_handles: dict[tuple[str, int], RuntimeHandle] = {}
         self._announced_param_degradations: set[tuple[str, str]] = set()
+        # Effort-first investment dial (RFC #1405): the coordinator's review pass
+        # is a top-level unit (never a decomposed child), so it runs at the base
+        # level on runtimes that enforce it. None ⇒ dormant. No effort_routed
+        # event is emitted here because a review is not an acceptance criterion.
+        from ouroboros.config import get_agent_reasoning_effort
+
+        self._reasoning_effort = get_agent_reasoning_effort()
 
     def _build_level_runtime_handle(
         self,
@@ -392,11 +399,19 @@ class LevelCoordinator:
                 announced=self._announced_param_degradations,
                 log_event="coordinator.param_degraded",
             )
+            from ouroboros.orchestrator.effort_routing import resolve_execute_effort
+
+            _, effort_kwargs = resolve_execute_effort(
+                self._adapter,
+                base_effort=self._reasoning_effort,
+                is_decomposed_child=False,
+            )
             async for message in self._adapter.execute_task(
                 prompt=prompt,
                 tools=tools,
                 system_prompt=COORDINATOR_SYSTEM_PROMPT,
                 resume_handle=runtime_handle,
+                **effort_kwargs,
             ):
                 messages.append(message)
                 if message.resume_handle is not None:

{ouroboros_ai-0.42.2.dev4 → ouroboros_ai-0.42.2.dev6}/src/ouroboros/orchestrator/copilot_cli_runtime.py

@@ -53,6 +53,9 @@ log = structlog.get_logger(__name__)
 # uses everywhere; permission mode is mapped through ``copilot_permissions``.
 _COPILOT_PERMISSION_MODES = frozenset({"default", "acceptEdits", "bypassPermissions"})
 _COPILOT_DEFAULT_PERMISSION_MODE = "default"
+# Levels Copilot CLI's --reasoning-effort flag accepts (verified via --help).
+# Allow-listed so an unexpected effort string is never forwarded to the flag.
+_COPILOT_REASONING_EFFORT_LEVELS = frozenset({"none", "low", "medium", "high", "xhigh", "max"})
 
 #: Maximum Ouroboros nesting depth to prevent fork bombs when Copilot
 #: spawns Ouroboros which spawns Copilot.
@@ -101,6 +104,16 @@ class CopilotCliRuntime(CodexCliRuntime):
             system_prompt_support=ParamSupport.TRANSLATED,
             tool_restriction_support=ParamSupport.TRANSLATED,
             permission_mode_support=ParamSupport.NATIVE,
+            # Copilot CLI enforces effort via a per-invocation --reasoning-effort
+            # flag (verified via --help: none/low/medium/high/xhigh/max).
+            reasoning_effort_support=ParamSupport.NATIVE,
+            # Declare the exact vocabulary the flag accepts. Without this, the
+            # shared contract treats an omitted set as "every level is enforced",
+            # so a caller using a level outside _COPILOT_REASONING_EFFORT_LEVELS
+            # would record an "enforced" proof row while _build_command silently
+            # drops the flag. Pinning the vocabulary downgrades such a level to
+            # "advised" in decide_effort, keeping the proof rows honest.
+            enforceable_reasoning_efforts=_COPILOT_REASONING_EFFORT_LEVELS,
         )
 
     def __init__(
@@ -179,6 +192,7 @@ class CopilotCliRuntime(CodexCliRuntime):
         resume_session_id: str | None = None,
         prompt: str | None = None,
         runtime_handle: RuntimeHandle | None = None,
+        reasoning_effort: str | None = None,
     ) -> list[str]:
         """Build the Copilot CLI command for non-interactive execution.
 
@@ -225,6 +239,13 @@ class CopilotCliRuntime(CodexCliRuntime):
                         mapped = map_to_copilot_model(normalized_runtime_model)
                         command.extend(["--model", mapped])
 
+        # Effort-first investment dial (RFC #1405). Copilot CLI honors a
+        # per-invocation --reasoning-effort flag (verified via --help), so the
+        # orchestrator's chosen level is ENFORCED. Allow-listed so an unexpected
+        # value can never be forwarded.
+        if reasoning_effort and reasoning_effort in _COPILOT_REASONING_EFFORT_LEVELS:
+            command.extend(["--reasoning-effort", reasoning_effort])
+
         command.extend(["-p", prompt or ""])
         return command
 

{ouroboros_ai-0.42.2.dev4 → ouroboros_ai-0.42.2.dev6}/src/ouroboros/orchestrator/effort_routing.py

@@ -112,3 +112,43 @@ def decide_effort(
         else EFFORT_MODE_ADVISED
     )
     return EffortDecision(level=level, mode=mode)
+
+
+def resolve_execute_effort(
+    adapter: object,
+    *,
+    base_effort: str | None,
+    is_decomposed_child: bool,
+    floor: str = DEFAULT_EFFORT_FLOOR,
+) -> tuple[EffortDecision, dict[str, str]]:
+    """Decide effort for one ``execute_task`` call and build its kwargs.
+
+    The single place every live execute_task call site lays itself on the
+    capability contract. Reads ``adapter.capabilities.reasoning_effort_support``
+    (defaulting to IGNORED when an adapter declares no capabilities), decides the
+    level, and returns the ``execute_task`` kwargs — which are **empty unless the
+    runtime enforces effort**, so a runtime that does not accept the parameter is
+    never handed it.
+
+    Returns:
+        ``(decision, execute_kwargs)``. ``execute_kwargs`` is ``{"reasoning_effort":
+        <level>}`` only when the chosen runtime declared NATIVE support, else ``{}``.
+    """
+    capabilities = getattr(adapter, "capabilities", None)
+    support = (
+        capabilities.reasoning_effort_support if capabilities is not None else ParamSupport.IGNORED
+    )
+    enforceable_levels = (
+        getattr(capabilities, "enforceable_reasoning_efforts", None)
+        if capabilities is not None
+        else None
+    )
+    decision = decide_effort(
+        support,
+        base_effort=base_effort,
+        is_decomposed_child=is_decomposed_child,
+        floor=floor,
+        enforceable_levels=enforceable_levels,
+    )
+    kwargs = {"reasoning_effort": decision.level} if decision.is_enforced else {}
+    return decision, kwargs

{ouroboros_ai-0.42.2.dev4 → ouroboros_ai-0.42.2.dev6}/src/ouroboros/orchestrator/gemini_cli_runtime.py

@@ -215,6 +215,10 @@ class GeminiCLIRuntime(CodexCliRuntime):
         resume_session_id: str | None = None,
         prompt: str | None = None,
         runtime_handle: RuntimeHandle | None = None,
+        # Accepted to honor the shared CodexCliRuntime contract, but ignored:
+        # the Gemini CLI exposes no per-invocation effort flag (capabilities
+        # declares reasoning_effort_support=IGNORED, so it is surfaced as advised).
+        reasoning_effort: str | None = None,
     ) -> list[str]:
         """Build the Gemini CLI command arguments for non-interactive execution.
 
@@ -277,6 +281,11 @@ class GeminiCLIRuntime(CodexCliRuntime):
             # guidance rather than enforcing a Gemini-native allow-list.
             system_prompt_support=ParamSupport.TRANSLATED,
             tool_restriction_support=ParamSupport.TRANSLATED,
+            # Reasoning effort is advised, not enforced: the Gemini API has a
+            # thinkingBudget, but no per-invocation effort flag on the Gemini CLI
+            # has been verified. Declared IGNORED (also the default) until a real
+            # per-call mechanism is confirmed — revisit if the CLI exposes one.
+            reasoning_effort_support=ParamSupport.IGNORED,
         )
 
     # -- Event parsing and normalization -----------------------------------

{ouroboros_ai-0.42.2.dev4 → ouroboros_ai-0.42.2.dev6}/src/ouroboros/orchestrator/goose_runtime.py

@@ -112,6 +112,10 @@ class GooseCliRuntime(CodexCliRuntime):
             # guidance rather than enforcing a Goose-native allow-list.
             system_prompt_support=ParamSupport.TRANSLATED,
             tool_restriction_support=ParamSupport.TRANSLATED,
+            # Reasoning effort is advised, not enforced: `goose run` exposes no
+            # per-invocation effort flag (verified via --help). Declared IGNORED
+            # explicitly (also the default) to document the verified decision.
+            reasoning_effort_support=ParamSupport.IGNORED,
         )
 
     def _resolve_permission_mode(self, permission_mode: str | None) -> str:
@@ -163,6 +167,10 @@ class GooseCliRuntime(CodexCliRuntime):
         resume_session_id: str | None = None,
         prompt: str | None = None,
         runtime_handle: RuntimeHandle | None = None,
+        # Accepted to honor the shared CodexCliRuntime contract, but ignored:
+        # `goose run` exposes no per-invocation effort flag (capabilities declares
+        # reasoning_effort_support=IGNORED, so it is surfaced as advised).
+        reasoning_effort: str | None = None,
     ) -> list[str]:
         """Build ``goose run`` args. Prompt is fed through stdin.
 

{ouroboros_ai-0.42.2.dev4 → ouroboros_ai-0.42.2.dev6}/src/ouroboros/orchestrator/hermes_runtime.py

@@ -238,11 +238,17 @@ class HermesCliRuntime(AgentRuntime):
         # message rather than passing native runtime parameters, and hermes chat
         # has no permission-mode flag. Surface both truthfully for degradation
         # notices.
+        # Reasoning effort is advised, not enforced: `hermes chat` exposes only
+        # -q/--image/-m/-t — no per-invocation effort flag and no `-c` config
+        # override (its config.yaml reasoning_effort is global, not per-call), so
+        # the level cannot be routed deterministically per AC. Declared IGNORED
+        # explicitly (it is also the default) to document the verified decision.
         return replace(
             FULL_CAPABILITIES,
             system_prompt_support=ParamSupport.TRANSLATED,
             tool_restriction_support=ParamSupport.TRANSLATED,
             permission_mode_support=ParamSupport.IGNORED,
+            reasoning_effort_support=ParamSupport.IGNORED,
         )
 
     @property

{ouroboros_ai-0.42.2.dev4 → ouroboros_ai-0.42.2.dev6}/src/ouroboros/orchestrator/parallel_executor.py

@@ -47,7 +47,6 @@ from ouroboros.core.seed_contract_prompt import render_auto_recursion_guard
 from ouroboros.observability.logging import get_logger
 from ouroboros.orchestrator.adapter import (
     AgentMessage,
-    ParamSupport,
     RuntimeHandle,
     runtime_handle_tool_catalog,
 )
@@ -67,7 +66,7 @@ from ouroboros.orchestrator.decomposition_params import (
     build_decomposition_user_prompt,
     params_from_profile,
 )
-from ouroboros.orchestrator.effort_routing import decide_effort
+from ouroboros.orchestrator.effort_routing import resolve_execute_effort
 from ouroboros.orchestrator.events import (
     create_ac_stall_detected_event,
     create_heartbeat_event,
@@ -5510,21 +5509,10 @@ Files present:
         # chosen runtime will honor it from its declared capability — enforced via a
         # native knob, or advised. The level is passed to execute_task; an advised
         # runtime ignores it. Dormant by default (base effort None → level None).
-        effort_capabilities = getattr(self._adapter, "capabilities", None)
-        effort_support = (
-            effort_capabilities.reasoning_effort_support
-            if effort_capabilities is not None
-            else ParamSupport.IGNORED
-        )
-        effort_decision = decide_effort(
-            effort_support,
+        effort_decision, execute_effort_kwargs = resolve_execute_effort(
+            self._adapter,
             base_effort=self._reasoning_effort,
             is_decomposed_child=is_sub_ac,
-            enforceable_levels=(
-                effort_capabilities.enforceable_reasoning_efforts
-                if effort_capabilities is not None
-                else None
-            ),
         )
         if effort_decision.level is not None:
             log.debug(
@@ -5568,13 +5556,9 @@ Files present:
                     },
                 )
             )
-        # Only forward the level to runtimes that ENFORCE it (declared NATIVE and
-        # thus accept the kwarg — Claude SDK, Codex). Advised runtimes ignore it
-        # anyway and do not accept the parameter, so passing it would break them;
-        # the chosen level still lives in effort_decision for honest recording.
-        execute_effort_kwargs: dict[str, Any] = (
-            {"reasoning_effort": effort_decision.level} if effort_decision.is_enforced else {}
-        )
+        # execute_effort_kwargs (from resolve_execute_effort) carries
+        # reasoning_effort ONLY for runtimes that enforce it; advised runtimes that
+        # do not accept the parameter are never handed it.
 
         try:
             with anyio.CancelScope(

{ouroboros_ai-0.42.2.dev4 → ouroboros_ai-0.42.2.dev6}/src/ouroboros/orchestrator/runner.py

@@ -495,6 +495,12 @@ class OrchestratorRunner:
         self._max_decomposition_depth = max(0, max_decomposition_depth)
         self._max_parallel_workers = max(1, max_parallel_workers)
         self._fat_harness_mode = fat_harness_mode
+        # Effort-first investment dial (RFC #1405): base level for the runner's own
+        # direct execution paths (single-AC / resume), which call execute_task
+        # without going through ParallelACExecutor. Resolved once; None ⇒ dormant.
+        from ouroboros.config import get_agent_reasoning_effort
+
+        self._reasoning_effort = get_agent_reasoning_effort()
         self._announced_param_degradations: set[tuple[str, str]] = set()
         # Track active session for external cancellation by execution_id
         self._active_sessions: dict[str, str] = {}  # execution_id -> session_id
@@ -515,6 +521,73 @@ class OrchestratorRunner:
             log_event="orchestrator.runner.param_degraded",
         )
 
+    async def _route_call_effort(
+        self,
+        *,
+        execution_id: str | None,
+        session_id: str | None,
+    ) -> dict[str, str]:
+        """Lay the runner's own execute_task paths on the effort contract.
+
+        These direct paths (single-AC execution, resume) do not go through
+        ParallelACExecutor, so without this they would silently skip effort
+        routing. Returns the execute_task kwargs (empty unless the runtime
+        enforces effort).
+
+        It also records an ``execution.ac.effort_routed`` event for
+        OBSERVABILITY — so a direct run's effort routing is visible in the event
+        stream exactly like the parallel path's. This event is deliberately NOT a
+        frugality-proof contribution: a direct run is a single top-level unit
+        (``is_decomposed_child=False``) with no per-AC decomposition, so the
+        payload carries no ``ac_id``. The deterministic proof excludes it on both
+        counts — ``assemble_triads`` skips ``ac_id``-less events, and
+        ``counts_in_proof`` only admits decomposed children — because the
+        hypothesis is about children running at lower effort, which a top-level
+        direct call has nothing to say about. ``call_site="runner"`` marks the
+        origin so the two emission paths are distinguishable in the stream.
+        """
+        from ouroboros.orchestrator.effort_routing import resolve_execute_effort
+
+        decision, kwargs = resolve_execute_effort(
+            self._adapter,
+            base_effort=self._reasoning_effort,
+            is_decomposed_child=False,
+        )
+        if decision.level is not None:
+            from ouroboros.events.base import BaseEvent
+
+            # Observability-only: this event must never make runtime dispatch/resume
+            # depend on event-store health. _route_call_effort runs BEFORE
+            # execute_task on the direct and resume paths, so a raw append would turn
+            # a degraded/locked store into a dispatch failure. Degrade to a warning
+            # instead — matching how the parallel executor treats the same telemetry.
+            try:
+                await self._event_store.append(
+                    BaseEvent(
+                        type="execution.ac.effort_routed",
+                        aggregate_type="execution",
+                        aggregate_id=execution_id or session_id or "",
+                        data={
+                            "execution_id": execution_id,
+                            "session_id": session_id,
+                            "is_decomposed_child": False,
+                            "effort_level": decision.level,
+                            "effort_mode": decision.mode,
+                            "base_reasoning_effort": self._reasoning_effort,
+                            "runtime_backend": getattr(self._adapter, "runtime_backend", None),
+                            "call_site": "runner",
+                        },
+                    )
+                )
+            except Exception as exc:
+                log.warning(
+                    "orchestrator.runner.effort_routed.persist_failed",
+                    error=str(exc),
+                    effort_level=decision.level,
+                    effort_mode=decision.mode,
+                )
+        return kwargs
+
     def _plan_parallel_workers(self) -> int:
         """Return the effective fan-out worker count for the connected backend.
 
@@ -2283,12 +2356,17 @@ class OrchestratorRunner:
                     system_prompt=system_prompt,
                     tools=merged_tools,
                 )
+                effort_kwargs = await self._route_call_effort(
+                    execution_id=exec_id,
+                    session_id=tracker.session_id,
+                )
                 async with aclosing(
                     self._adapter.execute_task(  # type: ignore[type-var]
                         prompt=prompt,
                         tools=merged_tools,
                         system_prompt=system_prompt,
                         resume_handle=active_runtime_handle,
+                        **effort_kwargs,
                     )
                 ) as message_stream:
                     async for message in message_stream:
@@ -2826,9 +2904,9 @@ class OrchestratorRunner:
                 effective_workers=effective_workers,
             )
 
-        # Execute in parallel
-        from ouroboros.config import get_agent_reasoning_effort
-
+        # Execute in parallel. Reuse the base effort resolved once in __init__
+        # (self._reasoning_effort) so a single runner instance has one consistent
+        # effort source across its direct paths and the parallel executor.
         parallel_executor = ParallelACExecutor(
             adapter=self._adapter,
             event_store=self._event_store,
@@ -2841,7 +2919,7 @@ class OrchestratorRunner:
             checkpoint_store=self._checkpoint_store,
             execution_profile=execution_profile,
             fat_harness_mode=self._fat_harness_mode,
-            reasoning_effort=get_agent_reasoning_effort(),
+            reasoning_effort=self._reasoning_effort,
         )
 
         # Check for cancellation before starting parallel execution
@@ -3210,12 +3288,17 @@ Note: This is a resumed session. Please continue from where execution was interr
                     system_prompt=system_prompt,
                     tools=merged_tools,
                 )
+                effort_kwargs = await self._route_call_effort(
+                    execution_id=None,
+                    session_id=session_id,
+                )
                 async with aclosing(
                     self._adapter.execute_task(  # type: ignore[type-var]
                         prompt=resume_prompt,
                         tools=merged_tools,
                         system_prompt=system_prompt,
                         resume_handle=runtime_handle,
+                        **effort_kwargs,
                     )
                 ) as message_stream:
                     async for message in message_stream:

{ouroboros_ai-0.42.2.dev4 → ouroboros_ai-0.42.2.dev6}/tests/unit/orchestrator/test_effort_routing.py

@@ -108,3 +108,70 @@ class TestDecideEffortEnforceableLevels:
             enforceable_levels=None,
         )
         assert d.mode == "enforced"
+
+
+class _Caps:
+    def __init__(self, support: ParamSupport, enforceable: frozenset[str] | None = None) -> None:
+        self.reasoning_effort_support = support
+        self.enforceable_reasoning_efforts = enforceable
+
+
+class _Adapter:
+    def __init__(self, support: ParamSupport | None) -> None:
+        if support is not None:
+            self.capabilities = _Caps(support)
+
+
+class TestResolveExecuteEffort:
+    """The shared helper every live execute_task call site uses."""
+
+    def test_enforced_runtime_yields_kwarg(self) -> None:
+        from ouroboros.orchestrator.effort_routing import resolve_execute_effort
+
+        decision, kwargs = resolve_execute_effort(
+            _Adapter(ParamSupport.NATIVE), base_effort="high", is_decomposed_child=False
+        )
+        assert decision.mode == "enforced"
+        assert kwargs == {"reasoning_effort": "high"}
+
+    def test_advised_runtime_yields_no_kwarg(self) -> None:
+        from ouroboros.orchestrator.effort_routing import resolve_execute_effort
+
+        decision, kwargs = resolve_execute_effort(
+            _Adapter(ParamSupport.IGNORED), base_effort="high", is_decomposed_child=False
+        )
+        assert decision.mode == "advised"
+        assert kwargs == {}  # never hand the kwarg to a runtime that ignores it
+
+    def test_adapter_without_capabilities_is_treated_as_advised(self) -> None:
+        from ouroboros.orchestrator.effort_routing import resolve_execute_effort
+
+        decision, kwargs = resolve_execute_effort(
+            _Adapter(None), base_effort="high", is_decomposed_child=False
+        )
+        assert decision.mode == "advised"
+        assert kwargs == {}
+
+    def test_dormant_yields_no_kwarg(self) -> None:
+        from ouroboros.orchestrator.effort_routing import resolve_execute_effort
+
+        decision, kwargs = resolve_execute_effort(
+            _Adapter(ParamSupport.NATIVE), base_effort=None, is_decomposed_child=False
+        )
+        assert decision.mode == "none"
+        assert kwargs == {}
+
+    def test_unenforceable_level_is_advised_with_no_kwarg(self) -> None:
+        # A NATIVE runtime that cannot enforce the chosen level (declared via
+        # enforceable_reasoning_efforts) records it advised and is not handed the kwarg.
+        from ouroboros.orchestrator.effort_routing import resolve_execute_effort
+
+        adapter = _Adapter(ParamSupport.NATIVE)
+        adapter.capabilities = _Caps(
+            ParamSupport.NATIVE, enforceable=frozenset({"low", "medium", "high", "xhigh"})
+        )
+        decision, kwargs = resolve_execute_effort(
+            adapter, base_effort="minimal", is_decomposed_child=False
+        )
+        assert decision.mode == "advised"
+        assert kwargs == {}

ouroboros_ai-0.42.2.dev6/tests/unit/orchestrator/test_reasoning_effort_routing.py

@@ -0,0 +1,181 @@
+"""Effort-first investment dial routing across agent runtimes (RFC #1405).
+
+These tests pin the Agent-OS contract: the orchestrator hands every runtime an
+abstract ``reasoning_effort`` level, and each runtime either ENFORCES it through
+its native per-call mechanism (declaring ``reasoning_effort_support = NATIVE``)
+or honestly declares that it cannot (the IGNORED default → advised). The proof's
+"enforced rows" depend on this distinction being truthful, so it is tested
+directly rather than assumed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+from ouroboros.orchestrator.adapter import (
+    FULL_CAPABILITIES,
+    ParamSupport,
+    RuntimeCapabilities,
+)
+from ouroboros.orchestrator.codex_cli_runtime import (
+    _CODEX_REASONING_EFFORT_LEVELS,
+    CodexCliRuntime,
+)
+
+
+class TestCapabilityDeclarations:
+    def test_default_and_full_capabilities_ignore_effort(self) -> None:
+        """A runtime that does not opt in must NOT claim native effort support.
+
+        Guards the latent bug flagged in review: ``replace(FULL_CAPABILITIES, …)``
+        runtimes (opencode, gjc, …) must inherit IGNORED, never a stray NATIVE.
+        """
+        bare = RuntimeCapabilities(
+            skill_dispatch=True, targeted_resume=True, structured_output=True
+        )
+        assert bare.reasoning_effort_support is ParamSupport.IGNORED
+        assert FULL_CAPABILITIES.reasoning_effort_support is ParamSupport.IGNORED
+        # An inheriting runtime that overrides only other fields stays IGNORED.
+        inherited = replace(FULL_CAPABILITIES, system_prompt_support=ParamSupport.TRANSLATED)
+        assert inherited.reasoning_effort_support is ParamSupport.IGNORED
+
+    def test_codex_runtime_declares_native_effort(self) -> None:
+        runtime = CodexCliRuntime(cli_path="codex", cwd="/tmp")
+        assert runtime.capabilities.reasoning_effort_support is ParamSupport.NATIVE
+
+    def test_copilot_runtime_declares_native_effort(self) -> None:
+        from ouroboros.orchestrator.copilot_cli_runtime import (
+            _COPILOT_REASONING_EFFORT_LEVELS,
+            CopilotCliRuntime,
+        )
+
+        runtime = CopilotCliRuntime(cli_path="copilot", cwd="/tmp")
+        assert runtime.capabilities.reasoning_effort_support is ParamSupport.NATIVE
+        # The enforceable vocabulary must be declared so a level the flag does not
+        # accept is downgraded to advised instead of recorded as a false "enforced"
+        # row. It must match exactly the allow-list _build_command applies.
+        assert (
+            runtime.capabilities.enforceable_reasoning_efforts == _COPILOT_REASONING_EFFORT_LEVELS
+        )
+
+    def test_gemini_and_goose_declare_advised_effort(self) -> None:
+        from ouroboros.orchestrator.gemini_cli_runtime import GeminiCLIRuntime
+        from ouroboros.orchestrator.goose_runtime import GooseCliRuntime
+
+        gemini = GeminiCLIRuntime(cli_path="gemini", cwd="/tmp")
+        goose = GooseCliRuntime(cli_path="goose", cwd="/tmp")
+        assert gemini.capabilities.reasoning_effort_support is ParamSupport.IGNORED
+        assert goose.capabilities.reasoning_effort_support is ParamSupport.IGNORED
+
+
+class TestCopilotEffortEnforcement:
+    def _runtime(self):
+        from ouroboros.orchestrator.copilot_cli_runtime import CopilotCliRuntime
+
+        return CopilotCliRuntime(cli_path="copilot", cwd="/tmp")
+
+    def test_known_level_is_enforced_via_flag(self) -> None:
+        command = self._runtime()._build_command("out.txt", prompt="hi", reasoning_effort="high")
+        assert "--reasoning-effort" in command
+        idx = command.index("--reasoning-effort")
+        assert command[idx + 1] == "high"
+
+    def test_unknown_level_is_not_injected(self) -> None:
+        command = self._runtime()._build_command(
+            "out.txt", prompt="hi", reasoning_effort="; rm -rf /"
+        )
+        assert "--reasoning-effort" not in command
+
+    def test_no_effort_emits_no_flag(self) -> None:
+        command = self._runtime()._build_command("out.txt", prompt="hi", reasoning_effort=None)
+        assert "--reasoning-effort" not in command
+
+    def test_subclasses_accept_effort_kwarg_without_error(self) -> None:
+        """codex execute_task forwards reasoning_effort to _build_command on every
+        CodexCliRuntime subclass — each override must accept it (regression guard).
+        """
+        from ouroboros.orchestrator.gemini_cli_runtime import GeminiCLIRuntime
+        from ouroboros.orchestrator.goose_runtime import GooseCliRuntime
+
+        for runtime in (
+            GeminiCLIRuntime(cli_path="gemini", cwd="/tmp"),
+            GooseCliRuntime(cli_path="goose", cwd="/tmp"),
+        ):
+            # Must not raise; gemini/goose accept-and-ignore (no per-call flag).
+            runtime._build_command("out.txt", prompt="hi", reasoning_effort="high")
+
+    def test_supported_level_is_enforced_unsupported_is_advised(self) -> None:
+        """The capability vocabulary keeps proof rows honest end to end.
+
+        decide_effort must mark a level inside Copilot's enforceable set as
+        ``enforced`` and a level outside it (e.g. Codex-only ``minimal``) as
+        ``advised`` even though Copilot declares NATIVE — because _build_command
+        silently drops a flag value it does not accept.
+        """
+        from ouroboros.orchestrator.copilot_cli_runtime import (
+            _COPILOT_REASONING_EFFORT_LEVELS,
+        )
+        from ouroboros.orchestrator.effort_routing import decide_effort
+
+        enforced = decide_effort(
+            ParamSupport.NATIVE,
+            base_effort="high",
+            is_decomposed_child=False,
+            enforceable_levels=_COPILOT_REASONING_EFFORT_LEVELS,
+        )
+        assert enforced.is_enforced
+        assert enforced.mode == "enforced"
+
+        advised = decide_effort(
+            ParamSupport.NATIVE,
+            base_effort="minimal",  # in EFFORT_LADDER, not in Copilot's flag vocab
+            is_decomposed_child=False,
+            enforceable_levels=_COPILOT_REASONING_EFFORT_LEVELS,
+        )
+        assert not advised.is_enforced
+        assert advised.mode == "advised"
+        assert advised.level == "minimal"  # still recorded, just not guaranteed
+
+
+class TestCodexEffortEnforcement:
+    def _runtime(self) -> CodexCliRuntime:
+        return CodexCliRuntime(cli_path="codex", cwd="/tmp")
+
+    def test_known_level_is_enforced_via_config_override(self) -> None:
+        command = self._runtime()._build_command(
+            output_last_message_path="/tmp/out.txt",
+            reasoning_effort="high",
+        )
+        # Codex enforces it as a per-invocation config override, contiguous pair.
+        assert "-c" in command
+        idx = command.index("-c")
+        assert command[idx + 1] == "model_reasoning_effort=high"
+
+    def test_no_effort_emits_no_override(self) -> None:
+        command = self._runtime()._build_command(
+            output_last_message_path="/tmp/out.txt",
+            reasoning_effort=None,
+        )
+        assert "model_reasoning_effort=high" not in command
+        assert not any(
+            isinstance(arg, str) and arg.startswith("model_reasoning_effort=") for arg in command
+        )
+
+    def test_unknown_level_is_not_injected(self) -> None:
+        """An unexpected token must never reach the ``key=value`` override."""
+        command = self._runtime()._build_command(
+            output_last_message_path="/tmp/out.txt",
+            reasoning_effort="; rm -rf /",
+        )
+        assert not any(
+            isinstance(arg, str) and arg.startswith("model_reasoning_effort=") for arg in command
+        )
+
+    def test_every_advertised_level_is_accepted(self) -> None:
+        runtime = self._runtime()
+        for level in _CODEX_REASONING_EFFORT_LEVELS:
+            command = runtime._build_command(
+                output_last_message_path="/tmp/out.txt",
+                reasoning_effort=level,
+            )
+            assert f"model_reasoning_effort={level}" in command