okstra 0.163.2 → 0.165.0

package/runtime/python/okstra_ctl/adapters/hosts/grok/relay.md

@@ -0,0 +1,90 @@
+# Grok Lead Runtime Adapter
+
+## Scope
+
+This adapter maps neutral Okstra lead operations to the Grok CLI. Read it only when the rendered launch prompt selects `leadRuntime=grok`.
+
+## Capability declaration
+
+| Field | Value |
+|---|---|
+| `runtime` | `grok` |
+| `leadRoleLabel` | `Grok lead` |
+| `userPromptMode` | `host-text` |
+| `workerDispatchBackend` | `mixed` |
+| `initialPromptDeliveryMode` | `eager-include` |
+| `sessionAccounting` | `artifact-only` |
+| `resumeMode` | `native-session-id` |
+| `teardownMode` | `process-cleanup` |
+| `leadEventSource` | `lead-events-jsonl` |
+
+## Wizard interaction relay
+
+Read this contract when `okstra preflight` returns this file as `runtimeReadiness.relayContract`. The JSON is the complete interaction mapping for this host. This relay exposes only text input; do not invent a native picker function.
+
+```json
+{
+  "schemaVersion": 1,
+  "runtime": "grok",
+  "semanticFunctions": ["plain_text_input"],
+  "interactions": {
+    "numbered-single": {
+      "function": "host-text",
+      "input": {
+        "questions": "one",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": { "source": "next-message", "submit": "raw" }
+    },
+    "numbered-multi": {
+      "function": "host-text",
+      "input": {
+        "questions": "one",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": { "source": "next-message", "submit": "raw" }
+    },
+    "sequential-group": {
+      "function": "host-text",
+      "input": {
+        "questions": "all-one-at-a-time-in-original-order",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": {
+        "source": "next-message-by-question-position",
+        "submit": "compact-step-json-raw"
+      }
+    },
+    "plain-text": {
+      "function": "host-text",
+      "input": { "questions": "one", "question": "label-with-progress" },
+      "response": { "source": "next-message", "submit": "raw" }
+    }
+  }
+}
+```
+
+Render every numbered item as its option label followed by its description verbatim, preserving every item and its original order. Submit the next user message unchanged. For `sequential-group`, collect one raw reply per question in order and build one compact JSON object keyed by the corresponding `questions[].step`.
+
+## Semantic operation mapping
+
+| Operation | Mapping |
+|---|---|
+| `read_artifacts` | Read the manifest-provided paths through the current Grok host file interface. |
+| `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
+| `prompt_user` | Ask through the current host text interface and wait for an explicit answer. |
+| `dispatch_worker` | Follow each persisted assignment's `runner` and use the common host dispatch boundary. |
+| `await_workers` | Await through the selected common dispatch backend, then verify terminal state and Result Paths. |
+| `redispatch_worker` | Start a fresh attempt from the persisted assignment and record the supplied dispatch kind. |
+| `shutdown_workers` | Clean up only host or process resources owned by this run. |
+| `record_lead_event` | Append the required structured event to `leadEventsPath` and emit the matching progress line. |
+| `collect_usage` | Return explicit unavailable lead usage until Grok registers a session transcript or CLI usage artifact contract. |
+
+## Completion, cleanup, and resume
+
+- Do not infer the current host from an installed `grok` executable. The runtime must come from an explicit request or current-session declaration.
+- Keep persisted provider, model, runner, and dispatch-kind assignments unchanged.
+- Resume with the persisted Grok session ID when one exists; otherwise resume from Okstra run artifacts.

package/runtime/python/okstra_ctl/adapters/hosts/kimi/adapter.py

@@ -0,0 +1,63 @@
+"""Bundled Kimi host strategy."""
+from __future__ import annotations
+
+import shutil
+from collections.abc import Callable
+from pathlib import Path
+
+from okstra_ctl.adapters.accounting import UnavailableUsageAccountingPort
+from okstra_ctl.adapters.hosts.capability_adapter import (
+    INTERACTION_FUNCTIONS,
+    PENDING_HOST_PORT,
+    CapabilityHostAdapter,
+    no_automatic_claim,
+    numbered_interaction_port,
+)
+from okstra_ctl.domain.host import HostDescriptor
+from okstra_ctl.registry.provider_registry import ProviderRegistry
+
+
+DESCRIPTOR = HostDescriptor(
+    id="kimi",
+    aliases=("kimi",),
+    native_provider_id="kimi",
+    required_executables=("kimi",),
+    launch_mode="lead",
+    install_targets=frozenset({"agents"}),
+    agent_id="kimi",
+    agent_label="Kimi CLI",
+    role="Kimi lead",
+    dispatch_mode="render-only",
+    session_accounting="artifact-only",
+    has_claude_session=False,
+    relay_contract=str(Path(__file__).with_name("relay.md").resolve()),
+)
+
+
+def create_adapter(
+    *,
+    executable_finder: Callable[[str], str | None] = shutil.which,
+    interaction_port=None,
+    lead_session_port=PENDING_HOST_PORT,
+    worker_dispatch_port=PENDING_HOST_PORT,
+    usage_accounting_port=UnavailableUsageAccountingPort(
+        "Kimi host usage accounting is unavailable because no session "
+        "transcript or CLI usage artifact contract is registered."
+    ),
+    provider_registry: ProviderRegistry | None = None,
+) -> CapabilityHostAdapter:
+    return CapabilityHostAdapter(
+        DESCRIPTOR,
+        executable_finder=executable_finder,
+        interaction_port=(
+            interaction_port
+            if interaction_port is not None
+            else numbered_interaction_port()
+        ),
+        lead_session_port=lead_session_port,
+        worker_dispatch_port=worker_dispatch_port,
+        usage_accounting_port=usage_accounting_port,
+        supported_functions=INTERACTION_FUNCTIONS,
+        detector=no_automatic_claim,
+        provider_registry=provider_registry,
+    )

package/runtime/python/okstra_ctl/adapters/hosts/kimi/manifest.json

@@ -0,0 +1 @@
+{"schemaVersion": 1, "id": "kimi", "factory": "adapter.py:create_adapter", "nativeProviderId": "kimi", "requiredExecutables": ["kimi"], "relayContract": "relay.md"}

package/runtime/python/okstra_ctl/adapters/hosts/kimi/relay.md

@@ -0,0 +1,90 @@
+# Kimi Lead Runtime Adapter
+
+## Scope
+
+This adapter maps neutral Okstra lead operations to the Kimi CLI. Read it only when the rendered launch prompt selects `leadRuntime=kimi`.
+
+## Capability declaration
+
+| Field | Value |
+|---|---|
+| `runtime` | `kimi` |
+| `leadRoleLabel` | `Kimi lead` |
+| `userPromptMode` | `host-text` |
+| `workerDispatchBackend` | `mixed` |
+| `initialPromptDeliveryMode` | `eager-include` |
+| `sessionAccounting` | `artifact-only` |
+| `resumeMode` | `native-session-id` |
+| `teardownMode` | `process-cleanup` |
+| `leadEventSource` | `lead-events-jsonl` |
+
+## Wizard interaction relay
+
+Read this contract when `okstra preflight` returns this file as `runtimeReadiness.relayContract`. The JSON is the complete interaction mapping for this host. This relay exposes only text input; do not invent a native picker function.
+
+```json
+{
+  "schemaVersion": 1,
+  "runtime": "kimi",
+  "semanticFunctions": ["plain_text_input"],
+  "interactions": {
+    "numbered-single": {
+      "function": "host-text",
+      "input": {
+        "questions": "one",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": { "source": "next-message", "submit": "raw" }
+    },
+    "numbered-multi": {
+      "function": "host-text",
+      "input": {
+        "questions": "one",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": { "source": "next-message", "submit": "raw" }
+    },
+    "sequential-group": {
+      "function": "host-text",
+      "input": {
+        "questions": "all-one-at-a-time-in-original-order",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": {
+        "source": "next-message-by-question-position",
+        "submit": "compact-step-json-raw"
+      }
+    },
+    "plain-text": {
+      "function": "host-text",
+      "input": { "questions": "one", "question": "label-with-progress" },
+      "response": { "source": "next-message", "submit": "raw" }
+    }
+  }
+}
+```
+
+Render every numbered item as its option label followed by its description verbatim, preserving every item and its original order. Submit the next user message unchanged. For `sequential-group`, collect one raw reply per question in order and build one compact JSON object keyed by the corresponding `questions[].step`.
+
+## Semantic operation mapping
+
+| Operation | Mapping |
+|---|---|
+| `read_artifacts` | Read the manifest-provided paths through the current Kimi host file interface. |
+| `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
+| `prompt_user` | Ask through the current host text interface and wait for an explicit answer. |
+| `dispatch_worker` | Follow each persisted assignment's `runner` and use the common host dispatch boundary. |
+| `await_workers` | Await through the selected common dispatch backend, then verify terminal state and Result Paths. |
+| `redispatch_worker` | Start a fresh attempt from the persisted assignment and record the supplied dispatch kind. |
+| `shutdown_workers` | Clean up only host or process resources owned by this run. |
+| `record_lead_event` | Append the required structured event to `leadEventsPath` and emit the matching progress line. |
+| `collect_usage` | Return explicit unavailable lead usage until Kimi registers a session transcript or CLI usage artifact contract. |
+
+## Completion, cleanup, and resume
+
+- Do not infer the current host from an installed `kimi` executable. The runtime must come from an explicit request or current-session declaration.
+- Keep persisted provider, model, runner, and dispatch-kind assignments unchanged.
+- Resume with the persisted Kimi session ID when one exists; otherwise resume from Okstra run artifacts.

package/runtime/python/okstra_ctl/adapters/providers/antigravity/adapter.py

@@ -0,0 +1,183 @@
+"""Bundled Antigravity provider catalog."""
+from typing import Any, Mapping
+
+from okstra_ctl.domain.provider import LeadLaunchSpec, ModelSpec, ProviderSpec
+from okstra_ctl.domain.worker_exec import (
+    STREAM_JSON,
+    ExecCommand,
+    PolicySupport,
+    WorkerExecRequest,
+)
+from okstra_ctl.domain.worker_stream import (
+    Result,
+    StreamEvent,
+    Text,
+    ToolCall,
+    ToolResult,
+)
+
+
+# `agy` needs a tier suffix at dispatch time; model_discovery owns that host
+# specific normalization so catalog display values never reach the CLI.
+ANTIGRAVITY = {
+    "gemini-3.1-pro": ModelSpec("Gemini 3.1 Pro", "gemini-3.1-pro", in_picker=True),
+    "gemini 3.1 pro": ModelSpec("Gemini 3.1 Pro", "gemini-3.1-pro"),
+    "gemini-3.6-flash": ModelSpec(
+        "Gemini 3.6 Flash", "gemini-3.6-flash", in_picker=True
+    ),
+    "gemini 3.6 flash": ModelSpec("Gemini 3.6 Flash", "gemini-3.6-flash"),
+    "gemini-3.5-flash": ModelSpec(
+        "Gemini 3.5 Flash", "gemini-3.5-flash", in_picker=True
+    ),
+    "gemini 3.5 flash": ModelSpec("Gemini 3.5 Flash", "gemini-3.5-flash"),
+}
+
+
+# The wall-clock cap on one print run, carried over from the wrapper. It is
+# deliberately not derived from the idle budget: an analyser legitimately works
+# for far longer than it goes quiet, so folding the idle budget in here would
+# kill a healthy worker mid-run. Idle is the runner's watchdog to enforce.
+_PRINT_TIMEOUT = "7200s"
+
+_STEP_UPDATE = "step_update"
+_RESULT = "result"
+_CALL_STARTED = "ACTIVE"
+_CALL_FINISHED = "DONE"
+
+
+def step_update_events(event: Mapping[str, Any]) -> tuple[StreamEvent, ...]:
+    """Normalise this CLI's stream-json, which shares no key with the other four.
+
+    Measured 2026-08-11 against agy 1.1.11. Events are keyed on `event` rather
+    than `type`, and progress arrives as one `step_update` per step transition:
+
+    - `step_type: agent_response` carries the worker's prose in `text_delta`
+      (absent on the turns that only planned a tool call).
+    - `step_type: tool` arrives twice for one call — `ACTIVE` with the
+      arguments, then `DONE` with the tool's output.
+    - the closing `result` carries `response`, and an `error` string when
+      `status` is anything but SUCCESS. A failed run's `response` is empty, so
+      without the error text such a run would leave nothing behind at all.
+    """
+    kind = event.get("event")
+    if kind == _RESULT:
+        return _result_events(event.get(_RESULT))
+    if kind != _STEP_UPDATE:
+        return ()
+    step = event.get(_STEP_UPDATE)
+    if not isinstance(step, Mapping):
+        return ()
+    if step.get("step_type") == "agent_response":
+        text = step.get("text_delta")
+        return (Text(body=text),) if isinstance(text, str) and text.strip() else ()
+    if step.get("step_type") == "tool":
+        return _tool_events(step)
+    return ()
+
+
+def _tool_events(step: Mapping[str, Any]) -> tuple[StreamEvent, ...]:
+    info = step.get("tool_info")
+    info = info if isinstance(info, Mapping) else {}
+    name = str(step.get("tool_name") or info.get("name") or "tool")
+    if step.get("state") == _CALL_STARTED:
+        return (ToolCall(name=name, detail=_argument(info.get("parameters"))),)
+    if step.get("state") != _CALL_FINISHED:
+        return ()
+    output = str(info.get("output", ""))
+    # No outcome field: a `run_command` whose command exited non-zero was
+    # measured closing as `DONE` with the failure text in `output` and nothing
+    # else to distinguish it, so the outcome is left unreported rather than
+    # rendered as success.
+    return (ToolResult(body=output, size_bytes=len(output.encode("utf-8"))),)
+
+
+def _argument(parameters: Any) -> str:
+    """The one argument worth a row, without guessing at the parameter names.
+
+    Parameter keys belong to each tool, not to this CLI — `view_file` names its
+    path `AbsolutePath` while `run_command` names its command `CommandLine` —
+    so an allowlist of key names would cover only the tools that happened to be
+    observed. The first string argument is the subject of every tool measured.
+    """
+    if not isinstance(parameters, Mapping):
+        return ""
+    return next(
+        (str(value) for value in parameters.values() if isinstance(value, str) and value),
+        "",
+    )
+
+
+def _result_events(result: Any) -> tuple[StreamEvent, ...]:
+    if not isinstance(result, Mapping):
+        return ()
+    error = result.get("error")
+    failure = (Text(body=error),) if isinstance(error, str) and error.strip() else ()
+    response = result.get("response")
+    if not isinstance(response, str):
+        return failure
+    return (*failure, Result(text=response))
+
+
+class AntigravityExecution:
+    """agy CLI invocation.
+
+    `--add-dir` defines the workspace rather than widening a default one, so the
+    project root is included instead of skipped.
+
+    The prompt is an argument, not stdin: this CLI does not read stdin.
+
+    `--dangerously-skip-permissions` is required rather than convenient. Headless
+    `--print` has nobody to answer a permission request, so without it every
+    command tool is auto-denied and the run still reports SUCCESS with an empty
+    response.
+
+    No flag bounds what this worker may write. `--sandbox` was measured on
+    2026-08-10 (agy 1.1.11) and did not block writes outside the `--add-dir`
+    workspace through either the shell tool or the file tool — identically to a
+    control run without it. It is therefore not passed, and `policy_support`
+    reports the gap rather than claiming a boundary that was not observed.
+    """
+
+    def build_command(self, request: WorkerExecRequest) -> ExecCommand:
+        argv = ["agy", "--print", request.prompt_text, "--model", request.model]
+        for directory in request.policy.write_scope:
+            argv += ["--add-dir", str(directory)]
+        argv += ["--output-format", "stream-json"]
+        argv += ["--print-timeout", _PRINT_TIMEOUT]
+        if request.policy.auto_approve:
+            argv.append("--dangerously-skip-permissions")
+        return ExecCommand(
+            argv=tuple(argv),
+            stdin_text=None,
+            stream_format=STREAM_JSON,
+            normalise=step_update_events,
+            cwd=request.project_root,
+        )
+
+    def policy_support(self) -> PolicySupport:
+        return PolicySupport(
+            can_auto_approve=True,
+            can_bound_write_scope=False,
+            note=(
+                "measured 2026-08-10 (agy 1.1.11): --sandbox did not block writes "
+                "outside the --add-dir workspace, so no flag bounds this provider"
+            ),
+        )
+
+
+def create_provider() -> ProviderSpec:
+    return ProviderSpec(
+        provider="antigravity",
+        display_label="Antigravity",
+        models=ANTIGRAVITY,
+        default_models={
+            role: "gemini-3.1-pro"
+            for role in ("lead", "analyser", "critic", "executor", "verifier")
+        },
+        wrapper="okstra-antigravity-exec.sh",
+        supported_roles=frozenset({"lead", "analyser", "critic", "executor", "verifier"}),
+        lead_launch=LeadLaunchSpec(
+            executable="agy", model_flag="--model", prompt_flag="--prompt-interactive"
+        ),
+        exec_strategy=AntigravityExecution(),
+    )

package/runtime/python/okstra_ctl/adapters/providers/antigravity/manifest.json

@@ -0,0 +1 @@
+{"schemaVersion": 1, "id": "antigravity", "factory": "adapter.py:create_provider"}

package/runtime/python/okstra_ctl/adapters/providers/claude/adapter.py

@@ -0,0 +1,110 @@
+"""Bundled Claude provider catalog."""
+from okstra_ctl.domain.provider import LeadLaunchSpec, ModelSpec, ProviderSpec
+from okstra_ctl.domain.worker_exec import (
+    STREAM_JSON,
+    ExecCommand,
+    PolicySupport,
+    WorkerExecRequest,
+)
+from okstra_ctl.domain.worker_stream import content_block_events
+
+
+CLAUDE = {
+    "fable": ModelSpec("fable", "fable", in_picker=True),
+    "fable-5": ModelSpec("fable-5", "claude-fable-5"),
+    "claude-fable-5": ModelSpec("fable-5", "claude-fable-5"),
+    "opus": ModelSpec("opus", "opus", in_picker=True),
+    "opus-5": ModelSpec("opus-5", "claude-opus-5"),
+    "claude-opus-5": ModelSpec("opus-5", "claude-opus-5"),
+    "opus-4-8": ModelSpec("opus-4-8", "claude-opus-4-8"),
+    "claude-opus-4-8": ModelSpec("opus-4-8", "claude-opus-4-8"),
+    "opus-4-7": ModelSpec("opus-4-7", "claude-opus-4-7"),
+    "claude-opus-4-7": ModelSpec("opus-4-7", "claude-opus-4-7"),
+    "opus-4-6": ModelSpec("opus-4-6", "claude-opus-4-6"),
+    "claude-opus-4-6": ModelSpec("opus-4-6", "claude-opus-4-6"),
+    "sonnet": ModelSpec("sonnet", "sonnet", in_picker=True),
+    "sonnet-5": ModelSpec("sonnet-5", "claude-sonnet-5", in_picker=True),
+    "claude-sonnet-5": ModelSpec("sonnet-5", "claude-sonnet-5"),
+    "sonnet-4-6": ModelSpec("sonnet-4-6", "claude-sonnet-4-6"),
+    "claude-sonnet-4-6": ModelSpec("sonnet-4-6", "claude-sonnet-4-6"),
+    "haiku": ModelSpec("haiku", "haiku", in_picker=True),
+    "haiku-4-5": ModelSpec("haiku-4-5", "claude-haiku-4-5"),
+    "claude-haiku-4-5": ModelSpec("haiku-4-5", "claude-haiku-4-5"),
+    "claude-haiku-4-5-20251001": ModelSpec(
+        "haiku-4-5", "claude-haiku-4-5-20251001"
+    ),
+}
+
+
+# Opening the approval gate for a non-interactive run. Without it this CLI
+# auto-denies any tool call outside the seeded allowlist and the worker silently
+# routes around the denial, which reads as a thinner analysis rather than as a
+# failure. The value is taken from the CLI's own help text; it has not been
+# observed end to end, which is why policy_support claims no write boundary.
+_APPROVAL_ARGS = ("--permission-mode", "bypassPermissions")
+
+
+class ClaudeExecution:
+    """claude CLI invocation.
+
+    Working directory is the project root even when a stage worktree exists:
+    this CLI attaches the worktree with `--add-dir` and runs from the root,
+    unlike grok/kimi which run inside the worktree.
+    """
+
+    def build_command(self, request: WorkerExecRequest) -> ExecCommand:
+        argv = ["claude", "-p", "--model", request.model]
+        for directory in request.policy.write_scope:
+            if directory != request.project_root:
+                argv += ["--add-dir", str(directory)]
+        if request.policy.auto_approve:
+            argv += list(_APPROVAL_ARGS)
+        # `--verbose` is mandatory, not cosmetic: Claude Code rejects `--print`
+        # combined with `--output-format=stream-json` without it and exits 1 in
+        # under a second.
+        argv += ["--output-format=stream-json", "--verbose"]
+        return ExecCommand(
+            argv=tuple(argv),
+            stdin_text=request.prompt_text,
+            stream_format=STREAM_JSON,
+            normalise=content_block_events,
+            cwd=request.project_root,
+        )
+
+    def policy_support(self) -> PolicySupport:
+        return PolicySupport(
+            can_auto_approve=True,
+            can_bound_write_scope=False,
+            note=(
+                "the approval flag is taken from help text and has not been "
+                "observed end to end; no flag is known to bound this provider's "
+                "writes, so none is claimed"
+            ),
+        )
+
+
+def create_provider() -> ProviderSpec:
+    return ProviderSpec(
+        provider="claude",
+        display_label="Claude",
+        models=CLAUDE,
+        default_models={
+            "lead": "opus",
+            "analyser": "opus",
+            "critic": "opus",
+            "executor": "opus",
+            "verifier": "opus",
+            "report-writer": "sonnet",
+        },
+        wrapper="okstra-claude-exec.sh",
+        supported_roles=frozenset(
+            {"lead", "analyser", "critic", "executor", "verifier", "report-writer"}
+        ),
+        lead_launch=LeadLaunchSpec(
+            executable="claude",
+            model_flag="--model",
+            start_session_id_flag="--session-id",
+            resume_session_id_flag="--resume",
+        ),
+        exec_strategy=ClaudeExecution(),
+    )

package/runtime/python/okstra_ctl/adapters/providers/claude/manifest.json

@@ -0,0 +1 @@
+{"schemaVersion": 1, "id": "claude", "factory": "adapter.py:create_provider"}

package/runtime/python/okstra_ctl/adapters/providers/codex/adapter.py

@@ -0,0 +1,84 @@
+"""Bundled Codex provider catalog."""
+from okstra_ctl.domain.provider import LeadLaunchSpec, ModelSpec, ProviderSpec
+from okstra_ctl.domain.worker_exec import (
+    TEXT,
+    ExecCommand,
+    PolicySupport,
+    WorkerExecRequest,
+)
+
+
+CODEX = {
+    # ChatGPT-account hosts serve this model without per-token billing.
+    "gpt-5.6-sol": ModelSpec("gpt-5.6-sol", "gpt-5.6-sol", None, in_picker=True),
+    "gpt-5.6": ModelSpec("gpt-5.6", "gpt-5.6", (5.00, 0.50, 30.0), in_picker=True),
+    "gpt-5.5": ModelSpec("gpt-5.5", "gpt-5.5", (5.00, 0.50, 30.0), in_picker=True),
+    "gpt-5.4": ModelSpec("gpt-5.4", "gpt-5.4", (2.50, 0.25, 15.00), in_picker=True),
+    "gpt-5.4-mini": ModelSpec(
+        "gpt-5.4-mini", "gpt-5.4-mini", (0.75, 0.075, 4.50), in_picker=True
+    ),
+    "gpt-5.3-codex": ModelSpec("gpt-5.4", "gpt-5.4"),
+    "gpt-5.2": ModelSpec("gpt-5.2", "gpt-5.2", (1.75, 0.175, 14.0)),
+    "codex-auto-review": ModelSpec("codex-auto-review", "codex-auto-review"),
+}
+
+
+class CodexExecution:
+    """codex CLI invocation.
+
+    The sandbox stays `workspace-write` even when the approval gate is opened:
+    removing the gate is not the same as removing the boundary. A non-interactive
+    codex run under the default `on-request` policy blocks on the first approval
+    it wants, and with no TTY to answer it ends the turn with exit 0 and no
+    output — a success that produced nothing.
+
+    Working directory is the project root even when a stage worktree exists:
+    this CLI attaches the worktree with `--add-dir` and runs from the root,
+    unlike grok/kimi which run inside the worktree.
+    """
+
+    def build_command(self, request: WorkerExecRequest) -> ExecCommand:
+        argv = ["codex", "exec", "-C", str(request.project_root)]
+        for directory in request.policy.write_scope:
+            if directory != request.project_root:
+                argv += ["--add-dir", str(directory)]
+        argv += ["--model", request.model, "--sandbox", "workspace-write"]
+        if request.policy.auto_approve:
+            argv += ["-c", "approval_policy=never"]
+        argv.append("-")
+        return ExecCommand(
+            argv=tuple(argv),
+            stdin_text=request.prompt_text,
+            stream_format=TEXT,
+            cwd=request.project_root,
+        )
+
+    def policy_support(self) -> PolicySupport:
+        return PolicySupport(can_auto_approve=True, can_bound_write_scope=True)
+
+
+def create_provider() -> ProviderSpec:
+    return ProviderSpec(
+        provider="codex",
+        display_label="Codex",
+        models=CODEX,
+        default_models={
+            role: "gpt-5.6-sol"
+            for role in ("lead", "analyser", "critic", "executor", "verifier", "report-writer")
+        },
+        wrapper="okstra-codex-exec.sh",
+        supported_roles=frozenset(
+            {"lead", "analyser", "critic", "executor", "verifier", "report-writer"}
+        ),
+        lead_launch=LeadLaunchSpec(
+            executable="codex",
+            model_flag="-m",
+            # A sandboxed lead cannot reach cmux or write its worker CLI config.
+            sandbox_waiver=("-s", "danger-full-access"),
+            sandbox_waiver_note=(
+                "codex will start without its filesystem and network sandbox, "
+                "which okstra needs so the lead can reach cmux and start worker CLIs."
+            ),
+        ),
+        exec_strategy=CodexExecution(),
+    )

package/runtime/python/okstra_ctl/adapters/providers/codex/manifest.json

@@ -0,0 +1 @@
+{"schemaVersion": 1, "id": "codex", "factory": "adapter.py:create_provider"}