okstra 0.147.0 → 0.148.0

package/README.md

@@ -20,7 +20,7 @@
 <a id="purpose"></a>
 ## 1. Purpose
 
-`okstra` is a **structured task runner that cross-verifies work inside Claude Code using a lead + worker model**. A Claude lead drives phase progression and dispatches independent analysis workers—**Claude and Codex by default**, with Antigravity added only when explicitly requested—plus a dedicated report writer for final synthesis.
+`okstra` is a **host-aware, multi-provider task runner that cross-verifies work with a lead + worker model**. The current Claude Code, Codex, or Antigravity host supplies the native lead session; every other selected provider runs through its registered CLI wrapper. Claude remains the compatibility default policy, not the owner of the lifecycle.
 
 The design rests on three principles:
 
@@ -28,6 +28,20 @@ The design rests on three principles:
 - **Persistent task identity**: a stable `<project-id>/<task-group>/<task-id>` task key carries context across phases, sessions, and model upgrades.
 - **Enforced lead/worker contract**: output schemas and validation procedures are bound to `templates/` + `validators/`, and the worker roster is fixed per phase.
 
+Role assignments are persisted separately from the host runtime, but the lead provider is always derived from that runtime:
+
+| Provider | Native host | CLI wrapper | Public roles |
+|---|---|---|---|
+| Claude | Claude Code | `okstra-claude-exec.sh` | lead, analysis, implementation, report writer |
+| Codex | Codex | `okstra-codex-exec.sh` | lead, analysis, implementation, report writer |
+| Antigravity | Antigravity CLI | `okstra-antigravity-exec.sh` | lead, analysis, and implementation |
+| Grok | none | `okstra-grok-exec.sh` | read-only analyser and critic |
+| Kimi | none | `okstra-kimi-exec.sh` | read-only analyser and critic |
+
+Grok and Kimi are intentionally read-only in this release. Their wrappers, model aliases, installation, diagnostics, and usage-pricing paths are integrated, but a real authenticated local invocation still depends on the corresponding CLI being installed and configured.
+
+The next direct-CLI candidates are Mistral Vibe and Qwen Code. DeepSeek V4, GLM-5.2, and MiniMax M2.7 remain API-adapter candidates because their current official coding-agent execution surfaces do not fit Okstra's wrapper contract as directly. Newly published provider models are exposed only after the corresponding local CLI reports them; this keeps model discovery separate from marketing availability.
+
 okstra is **not** a one-shot code review tool. It is for work that **spans multiple phases, needs input from multiple agents, and feeds each phase's output into the next phase**.
 
 <a id="structure"></a>
@@ -63,7 +77,7 @@ During `prepack`, `tools/build.mjs` rebuilds `runtime/` from `scripts/`, `skills
 ~/.okstra/                       runtime home, created by `okstra install`
 ├── version                      package version stamp
 ├── lib/python/                  okstra_project/, okstra_ctl/, okstra_token_usage/, lib/
-├── bin/                         okstra.sh, codex-exec, antigravity-exec, ...
+├── bin/                         okstra.sh and Claude/Codex/Antigravity/Grok/Kimi wrappers
 ├── templates/                   report assets and settings templates
 ├── prompts/                     lead operating contracts (prompts/lead/*) + coding-preflight resource pack
 ├── installed-runtimes.json      installed runtime adapter manifest
@@ -82,7 +96,7 @@ During `prepack`, `tools/build.mjs` rebuilds `runtime/` from `scripts/`, `skills
 └── okstra-*/SKILL.md            8 user-facing skills only (setup/brief/run/memory/inspect/schedule/container/manager)
 
 ~/.claude/agents/                automatically discovered by Claude Code (when `~/.claude` exists)
-└── {claude,codex,antigravity,report-writer}-worker.md   worker subagent definitions
+└── {claude,codex,antigravity,grok,kimi,report-writer}-worker.md   worker definitions
                                  (required for Claude Code multi-agent dispatch)
 
 <project-root>/.okstra/
@@ -195,7 +209,7 @@ To start a task outside a Claude Code session:
   --task-brief ./brief.md
 ```
 
-`feature-analysis` is intentionally omitted from the standalone shell example. Start it with `/okstra-run`: the wizard collects its required feature target and passes that value through the internal Node render boundary. Standalone `okstra.sh` accepts neither `--analysis-target` nor `--evidence-inputs`.
+`feature-analysis` is intentionally omitted from the standalone shell example. Start it with the in-host `okstra-run` skill: the wizard collects its required feature target and passes that value through the internal Node render boundary. Standalone `okstra.sh` accepts neither `--analysis-target` nor `--evidence-inputs`.
 
 This starts a new `claude` process in the lead role. For the complete argument list, see `okstra.sh --help` or [`docs/cli.md`](docs/cli.md).
 
@@ -208,10 +222,10 @@ Notable flags added in 0.7.0 / 0.8.0:
 Major workflow changes added to `main` after 0.8.0:
 
 - **Automatic isolated worktrees for every task type** — During preparation, `okstra-ctl` runs `git worktree add ~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>` once per task key to create an isolated working tree and a `<work-category-namespace>/<task-id-segment>` branch (for example, `feature/dev-9436` or `fix/dev-7311`). The user chooses the base ref with `--base-ref`, using the same choices as the release-handoff PR base picker: `main`, `dev`, `staging`, `preprod`, `prod`, or a custom value. It is required in the first phase; the okstra-run skill collects it through `AskUserQuestion`, while non-interactive callers must pass `--base-ref` explicitly. Later **non-`implementation`** phases for the same task key (`requirements-discovery` → `error-analysis` → `implementation-planning` → `final-verification` → `release-handoff`) reuse the same path and branch. `implementation` runs are **stage-isolated**: each run executes one stage in its own `.../<task>/stage-<N>/` worktree on a `<work-category-namespace>/<task>-s<N>` branch, so independent stages with `depends-on (none)` can run concurrently without sharing a tree. The registry reserves both task keys and **stage keys** with flock. Provisioning is skipped when the caller is already in another worktree or project_root is not a Git repository; stage isolation degrades to a flat path in those cases. Manual cleanup: `git worktree remove <path>` → `git branch -D <branch>` plus release/removal of the registry entry. Details: [`docs/architecture.md`](docs/architecture.md), in the *Task type* section, and [`docs/cli.md#--executor`](docs/cli.md#--executor).
-- **`release-handoff` lifecycle phase** — runs immediately after `final-verification` returns `verdict=accepted`. A Claude worker drafts candidate commit messages and a PR body, then the lead uses `AskUserQuestion` to ask, in order, for (1) an action (`commit only` / `commit + PR` / `skip`), (2) a PR base branch (`staging` / `preprod` / `prod` / `main` / `dev` / custom input), and (3) message handling (`use as-is` / `edit then proceed` / `cancel`). Only the Git/GitHub CLI commands selected through those menus are run. Force pushes, direct pushes to the base branch, hook bypasses (`--no-verify`), and release publication (`gh release`, `npm publish`, and similar commands) are prohibited. This phase does not edit source code. Profile: [`prompts/profiles/release-handoff.md`](prompts/profiles/release-handoff.md).
+- **`release-handoff` lifecycle phase** — runs immediately after `final-verification` returns `verdict=accepted`. The current Okstra lead drafts the candidate messages and PR body inline, then uses the selected host adapter's user-prompt operation for the delivery choices. Only the Git/GitHub CLI commands selected through those menus are run. Force pushes, direct pushes to the base branch, hook bypasses (`--no-verify`), and release publication (`gh release`, `npm publish`, and similar commands) are prohibited. This phase does not edit source code. Profile: [`prompts/profiles/release-handoff.md`](prompts/profiles/release-handoff.md).
 - **Configurable PR body template** (release-handoff) — PR bodies are populated from a Markdown template selected in this order: one-time override (`--pr-template-path` or the okstra-run Step 6 prompt) → `prTemplatePath` in `<project_root>/.okstra/project.json` → `prTemplatePath` in `~/.okstra/config.json` → the skill default at `~/.claude/skills/templates/prd/pr-body.template.md`. Register a template with `okstra config set pr-template-path <path> [--scope project|global]`; project scope accepts a path relative to the project root, while global scope requires an absolute path or a path beginning with `~/`. `okstra config get pr-template-path --scope all` prints every scoped value and the effective winner. The default template contains `## Summary`, `## Changes`, `## Test plan`, and `## Linked issues`, plus HTML comment guidance that the lead removes immediately before PR creation.
 - **Profile worker-roster validation** — `--workers <csv>` and the okstra-run Step 6 worker prompt accept only the worker IDs declared in the selected profile's `Required workers:` block. Requesting a worker absent from the profile—for example, `codex` or `antigravity` for `release-handoff`—fails with a clear error, and the interactive prompt shows only workers accepted by that profile.
-- **Experimental Codex lead adapter** — `okstra codex-run <render-bundle args...>` prepares a `leadRuntime=codex` task bundle without launching Claude Code. `okstra codex-dispatch --project-root <dir> --run-manifest <path>` then executes the supported Codex-side roster subset: Codex and Antigravity CLI workers by default, with a Codex report writer available through `--enable-codex-report-writer --report-writer-codex-model <model>`. A successful Codex report-writer dispatch performs token/cost substitution, HTML view rendering, follow-up stub generation, and run validation in order. It shares the Claude lead path's manifest and schema and does not clone the project into a Codex-specific fork.
+- **Host-aware lead adapters** — the same `okstra-run` skill resolves Claude Code to `leadRuntime=claude-code`, Codex to `leadRuntime=codex`, Antigravity CLI to `leadRuntime=antigravity`, and another explicit host to `external`. Claude Code keeps Claude assignments native, Codex keeps Codex assignments native, and Antigravity keeps Antigravity assignments native; every other selected provider runs through its registered CLI wrapper. The lead provider is derived from the host and cannot be replaced independently. `leadAssignment` and every `workerAssignments[]` row record provider, model, and `runner`. `okstra codex-run` and `okstra codex-dispatch` remain low-level artifact/dispatch commands.
 - **Multi-stage `implementation-planning` / `implementation`** — `implementation-planning` always produces a Stage Map and N stage sections. Each stage has no more than six steps, and stages with `depends-on (none)` can be implemented concurrently in separate `implementation` runs. Each `implementation` invocation runs a single stage, selected with `--stage <auto|N>`, and creates an evidence sidecar at `carry/stage-<N>.json` for automatic carry-in to the next stage. The `implementation-planning` run directory accumulates `consumers.jsonl` reverse links that record which run consumed each stage.
 - **AI-prepared design preparation (implementation-planning → implementation)** — `implementation-planning` detects which stages need design input (domain contract, DB/table schema, external interface, transaction/consistency, transformation mapping, lifecycle, rollout/observability, manual user test) and has the AI draft a concrete proposal first, instead of handing the user an empty design document. Each item is assessed as `ready`, `provisional`, `blocked`, or `not-applicable`; a simple task may declare `no-design-inputs`. Phase 7 materializes an Okstra-owned request under `design-prep-requests/`, and `okstra design-prep <list|show|write>` or the okstra-run wizard records the confirmed answer as an **append-only** revision under `design-prep-inputs/`—neither path ever edits the approved planning snapshot. Before creating its worktree, `implementation` resolves only the items its selected stage cites in `stageRefs`: safe `provisional` assumptions are injected into the executor prompt so work proceeds, while an unsafe open decision makes only that stage wait or replan. A markerless legacy plan continues with a `legacy-unassessed` warning. Storage authorities: [`docs/architecture/storage-model.md`](docs/architecture/storage-model.md). CLI: [`docs/cli.md#okstra-design-prep`](docs/cli.md#okstra-design-prep).
 - **Phase 6 plan-body verification (implementation-planning only)** — Immediately after the report-writer worker drafts the final report and before the user approval gate, the lead performs one post-verification round. It extracts `P-Opt-*`, `P-Step-*`, `P-Dep-*`, `P-Val-*`, and `P-Rb-*` plan items from the synthesized `## 5.5` implementation plan deliverables and asks every analyzer worker for an `AGREE`, `DISAGREE(a-e)`, or `SUPPLEMENT` verdict. The aggregate result is `passed`, `passed-with-dissent`, `blocked-by-disagreement`, or `aborted-non-result`. The frontmatter `approved` field is always published as `false`; a blocking result keeps it false and becomes a row in `## 1. Clarification Items`. For fast iteration, opt out with `--no-plan-verification`. Contract details: the "Plan-body verification mode" section of [`prompts/lead/convergence.md`](prompts/lead/convergence.md) and [`docs/cli.md#--no-plan-verification`](docs/cli.md#--no-plan-verification).
@@ -227,7 +241,7 @@ Major workflow changes added to `main` after 0.8.0:
 | Command | Purpose |
 |---|---|
 | `npx -y okstra@latest paths` | Print runtime paths (`--field <name>` or `--shell`) |
-| `npx -y okstra@latest doctor [--runtime claude-code\|codex\|all] [--phase <phase>]` | Diagnose runtime, skills, and Python imports. `codex` excludes Claude skill checks; `--phase` adds readiness checks for implementation, final-verification, release-handoff, and improvement-discovery |
+| `npx -y okstra@latest doctor [--runtime claude-code\|codex\|antigravity\|external\|all] [--phase <phase>]` | Diagnose runtime, skills, and Python imports. `codex`, `antigravity`, and `external` exclude Claude skill checks; `--phase` adds readiness checks for implementation, final-verification, release-handoff, and improvement-discovery |
 | `npx -y okstra@latest ensure-installed` | Run an idempotent check and automatically reinstall stale assets (skills call this internally) |
 | `npx -y okstra@latest setup --project-id <id>` | Register the current project in `.okstra/project.json` |
 | `npx -y okstra@latest check-project` | Verify that the current project was registered with `setup` |

package/docs/architecture/storage-model.md

@@ -11,54 +11,27 @@ Files created by `okstra` are stored in the following three areas according to t
 This is the task's primary directory.
 The task manifest, task index, instruction set, runs, and history are collected under this root.
 
-```text
-<target-project>/.okstra/tasks/<task-group>/<task-id>/
-├── task-manifest.json
-├── task-index.md
-├── instruction-set/
-│   ├── analysis-profile.md
-│   ├── analysis-packet.md       # analysis worker primary compact input
-│   ├── analysis-material.md
-│   ├── reference-expectations.md
-│   ├── task-brief.md
-│   ├── verification-target.md         # final-verification only; canonical target snapshot
-│   ├── directive.txt                  # optional (mirrors --directive)
-│   ├── final-report-schema.json
-│   ├── final-report-template.md
-│   └── claude-execution-prompt.md
-├── runs/
-│   └── <task-type>/
-│       ├── manifests/
-│       │   └── run-manifest-<task-type>-<seq>.json
-│       ├── state/
-│       │   └── team-state-<task-type>-<seq>.json
-│       ├── prompts/
-│       │   ├── claude-execution-prompt-<task-type>-<seq>.md
-│       │   ├── claude-worker-prompt-<task-type>-<seq>.md
-│       │   ├── codex-worker-prompt-<task-type>-<seq>.md
-│       │   ├── antigravity-worker-prompt-<task-type>-<seq>.md
-│       │   └── report-writer-worker-prompt-<task-type>-<seq>.md
-│       ├── reports/
-│       │   ├── final-report-<task-type>-<seq>.data.json
-│       │   ├── final-report-<task-type>-<seq>.md
-│       │   └── final-report-<task-type>-<seq>.html
-│       ├── design-prep-requests/       # implementation-planning only; deterministic Okstra-owned drafts
-│       ├── design-prep-inputs/         # implementation-planning only; append-only user/wizard responses
-│       ├── status/
-│       │   └── final-<task-type>-<seq>.status
-│       ├── sessions/
-│       │   └── claude-resume-<task-type>-<seq>.sh
-│       ├── logs/
-│       │   └── errors-<task-type>-<seq>.jsonl        # optional, lead-only writer
-│       └── worker-results/
-├── history/
-│   ├── timeline.json
-│   └── fix-cycles.jsonl          # optional, created only when entering a fix cycle (append-only)
-├── recap/
-│   └── recap-log.jsonl          # optional, append-only before/after summaries and Q&A for recap (other artifacts unchanged)
-└── notes/
-    └── <slug>-<YYYY-MM-DD>.md    # optional, agent-authored notes written by `okstra recap note` (evidence/decision-draft/analysis); inert — never auto-read by a run, fed forward only via --clarification-response
-```
+- `<target-project>/.okstra/tasks/<task-group>/<task-id>/`
+  - `task-manifest.json`
+  - `task-index.md`
+  - `instruction-set/`
+    - `analysis-profile.md`, `analysis-packet.md`, `analysis-material.md`, `reference-expectations.md`, `task-brief.md`
+    - `verification-target.md` for final verification and optional `directive.txt`
+    - `final-report-schema.json`, `final-report-template.md`
+    - canonical `lead-execution-prompt.md` plus the `claude-execution-prompt.md` compatibility alias
+  - `runs/<task-type>/`
+    - `manifests/run-manifest-<task-type>-<seq>.json`
+    - `state/team-state-<task-type>-<seq>.json`
+    - `prompts/lead-execution-prompt-<task-type>-<seq>.md` and selected `<worker>-worker-prompt-<task-type>-<seq>.md` files
+    - `reports/final-report-<task-type>-<seq>.{data.json,md,html}`
+    - implementation-planning-only `design-prep-requests/` and `design-prep-inputs/`
+    - `status/final-<task-type>-<seq>.status`
+    - Claude compatibility launcher sessions under `sessions/claude-resume-<task-type>-<seq>.sh`
+    - optional lead-written `logs/errors-<task-type>-<seq>.jsonl`
+    - `worker-results/`
+  - `history/timeline.json` and optional append-only `history/fix-cycles.jsonl`
+  - optional append-only `recap/recap-log.jsonl`
+  - optional inert agent notes under `notes/<slug>-<YYYY-MM-DD>.md`; a run reads them only when explicitly carried through `--clarification-response`
 
 Actual directory segments may be normalized into slugs to create safe paths.
 However, the logical task key always retains the original input values in the form `project-id:task-group:task-id`.
@@ -76,10 +49,10 @@ The representative files below are all relative to the resolved run directory (`
 
 - `manifests/run-manifest-<task-type>-<seq>.json`
 - `state/team-state-<task-type>-<seq>.json`
-- `prompts/claude-execution-prompt-<task-type>-<seq>.md`
+- `prompts/lead-execution-prompt-<task-type>-<seq>.md` *(canonical; the Claude-named snapshot remains a compatibility alias)*
 - `prompts/<worker>-worker-prompt-<task-type>-<seq>.md`
 
-Unless `--render-only` is used, the handed-off Claude session typically adds the following result files to the current run.
+After the host-native lead takes over, the lead and its assigned workers add the following result files to the current run.
 - `sessions/claude-resume-<task-type>-<seq>.sh`
 - `reports/final-report-<task-type>-<seq>.data.json` *(schema v2 source of truth for both audiences; schema v1 remains readable for compatibility)*
 - `reports/final-report-<task-type>-<seq>.md`
@@ -102,7 +75,7 @@ Design-preparation storage has three separate authorities:
 
 The resolver selects the highest unique revision whose assessment fingerprint still matches the approved snapshot. Duplicate revision numbers and stale fingerprints are skipped with warnings rather than granted authority. A markerless legacy plan has no sidecars to migrate: it proceeds with the `legacy-unassessed` warning. This compatibility path does not rewrite its report.
 The final result files are not created by saving worker stdout. The report writer writes `final-report-<task-type>-<seq>.data.json`; Phase 7 derives the Markdown and HTML siblings deterministically. New bundles use `schemas/final-report-v2.0.schema.json` and `templates/reports/final-report-v2.template.md`: AI handoff Markdown and task-specific human HTML are rendered independently from the same v2 data.json. Existing schema v1 data uses `schemas/final-report-v1.0.schema.json` and the legacy `templates/reports/final-report.template.md` compatibility path. Rendering never modifies the source data or a pre-existing Markdown input.
-By contrast, `sessions/claude-resume-<task-type>-<seq>.sh` is an interruption-recovery helper that `okstra` creates before launching Claude.
+For the standalone Claude launcher, `sessions/claude-resume-<task-type>-<seq>.sh` remains an interruption-recovery compatibility helper. In-host Codex runs use host task continuity plus the generic `leadSession` manifest identity.
 
 The resolved run directory collects execution history. It divides its contents into type-specific subdirectories such as `manifests/`, `state/`, `prompts/`, `reports/`, `status/`, `sessions/`, and `worker-results/`, then distinguishes each run-level artifact and result file with a `-<task-type>-<seq>` suffix (a three-digit, zero-padded per-category counter, such as `001` or `002`).
 Worker prompt history is retained not under `/tmp`, but always as a canonical artifact under `prompts/` for the current run.
@@ -168,7 +141,7 @@ Path segments are normalized into slugs. If a slug would be empty, as can happen
 
 ## Task manifest contract
 
-`task-manifest.json` is the canonical metadata file Claude uses to understand task continuity.
+`task-manifest.json` is the canonical metadata file the active Okstra lead uses to understand task continuity.
 As a general rule, this manifest records the absolute `projectRoot` path only once and expresses the remaining generated paths as project-relative fields whenever possible.
 
 Examples of key fields:
@@ -205,12 +178,13 @@ Examples of key fields:
 - `inputs`
 - `artifacts`
 - `resultContract`
-- `claudeSession`
+- `leadSession`
+- `claudeSession` *(Claude-host compatibility only)*
 - `fixCycles` *(derived summary — `{count, openCycleId, latest:{cycle, symptom, targetReport, closedAt}}`; recalculated on every prepare)*
 
 This manifest serves the following purposes.
 
-- Let Claude understand task continuity before reading the brief
+- Let the active lead understand task continuity before reading the brief
 - Establish which files should be read first
 - Establish how config files and deployment manifests should be interpreted against expected values
 - Establish the task key under which results accumulate
@@ -248,9 +222,7 @@ Each execution records the current run contract in the resolved `<run-dir>/manif
 `state/active-run-context-<task-type>-<seq>.json` is also the compact intake for lead Phase 1 starting with schemaVersion `2.0`. It stores only `identity` + `pathHints` and worker identities instead of repeated path strings, and the deterministic dispatcher hydrates it into the legacy active context shape when reading it.
 
 The path fields in `manifests/run-manifest-<task-type>-<seq>.json` are still stored as paths relative to the target project root for validator, team dispatch, and inspect compatibility.
-Immediately after `okstra` starts the Claude handoff, the current run status is usually recorded as `in-progress`.
-Claude then continues with saving the final results and updating status.
-Before launch, `okstra` also preallocates a session ID and creates, under the same run's `sessions/` directory, `claude-resume-<task-type>-<seq>.sh`.
+An in-host prepare records the run as `prepared` and the task as `ready-for-lead`; the current native host session then owns execution. The standalone Claude launcher records `in-progress` after preparing its compatibility resume script.
 
 Main contents:
 
@@ -263,7 +235,8 @@ Main contents:
 - related tasks
 - selected workers
 - worker model assignments
-- claude session id
+- lead session id and accounting mode
+- Claude session id only on the Claude compatibility path
 - resume command relative path
 - expected report relative path
 - expected status relative path
@@ -297,9 +270,9 @@ The history generally includes the following.
 - `fixCycleId` *(only when attached to a fix cycle; field omitted otherwise)*
 Reruns of the same task type reuse the same resolved run directory family. Non-stage runs use `runs/<task-type>/`, while `implementation` and single-stage `final-verification` runs use `runs/<task-type>/stage-<N>/`. Sequence-specific artifacts live beneath that resolved run directory, and each execution accumulates as a separate history entry because `run-manifest-<task-type>-<seq>.json` and related artifact paths are separated by per-category sequence suffixes (`<task-type>-<seq>`). The cross-category identifier is the manifest's `runDateTimeSegment` ISO timestamp field.
 
-## Claude operating contract
+## Lead operating contract
 
-After `okstra` runs, Claude should follow this default sequence when reading the current task.
+After `okstra` prepares a run, the host-native Okstra lead follows this default sequence when reading the current task.
 
 1. If task browsing or task-id disambiguation is required, first read `.okstra/discovery/task-catalog.json`.
 2. If the current task key or task path is not specified, read `.okstra/discovery/latest-task.json` as the current-task pointer.
@@ -310,7 +283,7 @@ After `okstra` runs, Claude should follow this default sequence when reading the
 6. Read `task-index.md` only when a quick summary is needed.
 7. Lazily read `analysis-material.md`, `reference-expectations.md`, `task-brief.md`, and `final-report-template.md` when the packet is insufficient or when source citations/report writing require them.
 8. Consult `history/timeline.json` and previous run results if necessary.
-9. As `Claude lead`, organize roles according to the current run's worker roster (`Claude worker`, `Codex worker`, and `Report writer worker` by default; `Antigravity worker` only when explicitly included).
+9. As `Okstra lead`, organize roles from `workerAssignments[]`. The host provider stays native; Claude, Codex, Antigravity, Grok, and Kimi assignments use their persisted `native-session` or `cli-wrapper` runner.
 10. Save each selected worker prompt under the current run's `prompts/` directory at the assigned worker prompt history path before dispatching the worker.
     Every selected initial analyser receives the same full-core semantic body for its task, including final-verification. Dispatch and Phase 7 validate the same normalized equality policy; implementation executor, report-writer, and `-reverify-r<N>-` prompts are separate audiences.
 11. In convergence Round 0, the lead groups findings by semantic meaning and ticket set, then writes `state/convergence-groups-<task-type>-<seq>.json`. The deterministic engine seeds the working queue and generates each roster-aware reverify plan; lightweight reverify reads only that persisted batch and its embedded evidence.

package/docs/architecture.md

@@ -8,7 +8,7 @@
 
 ## At a glance
 
-`okstra` is a **task bundle preparation tool** for Claude Code's cross-verification workflow. It is not a single-file review tool. Instead, it organizes task briefs, profiles, prompts, run history, and project-level discovery metadata around a stable task key so Claude can reliably orchestrate lead and worker agents.
+`okstra` is a **host-aware task bundle preparation tool** for multi-provider cross-verification. It is not a single-file review tool. Instead, it organizes task briefs, profiles, prompts, run history, and project-level discovery metadata around a stable task key so the current host-native lead can orchestrate provider workers consistently.
 
 Its core capabilities at a glance are:
 
@@ -16,13 +16,13 @@ Its core capabilities at a glance are:
 - **Profiles by task type**: Loads standard task-type profiles such as `requirements-discovery`, `error-analysis`, `implementation-planning`, `implementation`, `final-verification`, and `release-handoff` to render the instruction set.
 - **Run lifecycle**: Non-stage runs use `runs/<task-type>/` as the run directory, while `implementation` and single-stage `final-verification` use `runs/<task-type>/stage-<N>/`. Manifests, prompts, state, reports, sessions, worker results, and logs accumulate beneath the resolved run directory, and the filename suffix `-<task-type>-<seq>` separates reruns of the same phase.
 - **Single python authority**: All prepare wiring—resolving profiles/workers/models, computing paths, rendering, and central record_start—is concentrated in a single function, [`okstra_ctl.run.prepare_task_bundle()`](../scripts/okstra_ctl/run.py). `okstra.sh` and the `okstra-run` skill are thin callers of that same function and do not pass state through environment variables. Task identity, paths, and workflow state are recalculated from authoritative on-disk files every time.
-- **Claude handoff (two modes)**: (a) the traditional mode, where `okstra.sh` launches a new `claude` process; and (b) in-session mode, where the `okstra-run` skill prepares the task in the current Claude session and hands the lead role to that session. Both use the outputs of `prepare_task_bundle`, including the instruction set, unchanged.
-- **Required team contract**: The `Required workers:` block in each phase profile is authoritative for the roster. General analysis phases use Claude/Codex analyzers plus a report writer by default, while Antigravity is included only when allowed by both the profile and `--workers`. Lead-oriented phases such as `release-handoff` have separate rosters.
-- **User-home install + project-local task bundles**: One `npx okstra@latest install` command installs the runtime (`~/.okstra/{lib/python, bin, templates, prompts}`) and installs public skills to `~/.agents/skills/` by default. If `~/.claude` exists, it also installs Claude skills and four worker agent definitions (`~/.claude/agents/*-worker.md`). Only user entry-point skills are exposed in the skill list; lead/support operating contracts are installed as runtime resources under `~/.okstra/prompts/` and are not discoverable as skills. Global conversation memory is stored separately from projects under `~/.okstra/memory-book/`. Task bundles and discovery metadata are stored under `.okstra/` in the target project. **In addition, `<PROJECT_ROOT>/.claude/settings.local.json` is provisioned as a symlink to `~/.okstra/templates/settings.local.json`** (`okstra setup` or `okstra-ctl` prepare manages it idempotently; if a regular file already existed, it is preserved as `.bak.<timestamp>` before replacement).
+- **Host-aware handoff**: Claude Code, Codex, and Antigravity keep their current native session as the lead. The standalone compatibility launcher still starts a new `claude` process by default, while the external adapter uses registered CLI wrappers. Every path consumes the same `prepare_task_bundle` outputs.
+- **Required team contract**: The `Required workers:` block in each phase profile is authoritative for the roster. General analysis phases use Claude/Codex analysers plus a report writer by default, while Antigravity, Grok, and Kimi are included only when allowed by both the profile and `--workers`. Lead-oriented phases such as `release-handoff` have separate rosters.
+- **User-home install + project-local task bundles**: One `npx okstra@latest install` command installs the runtime (`~/.okstra/{lib/python, bin, templates, prompts}`) and installs public skills to `~/.agents/skills/` by default. If `~/.claude` exists, it also installs Claude skills and six worker agent definitions (`~/.claude/agents/*-worker.md`). Only user entry-point skills are exposed in the skill list; lead/support operating contracts are installed as runtime resources under `~/.okstra/prompts/` and are not discoverable as skills. Global conversation memory is stored separately from projects under `~/.okstra/memory-book/`. Task bundles and discovery metadata are stored under `.okstra/` in the target project. **In addition, `<PROJECT_ROOT>/.claude/settings.local.json` is provisioned as a symlink to `~/.okstra/templates/settings.local.json`** (`okstra setup` or `okstra-ctl` prepare manages it idempotently; if a regular file already existed, it is preserved as `.bak.<timestamp>` before replacement).
 - **Resume and clarification**: Supports resuming the same task and responding to follow-up questions from the lead through `--task-key`, `--resume-clarification`, and `--clarification-response`.
 - **Dual-audience derived views and telemetry**: For schema v2, derives AI handoff Markdown and task-specific human-facing HTML independently from the same v2 data.json. Schema v1 and quick Markdown reports keep their compatibility renderer. Worker error sidecars, wrapper log sidecars, and token-usage/cost accounting remain separate audit inputs.
 
-Claude lead owns judgment policy and worker orchestration. `okstra` focuses on preparing the structured input bundle and output skeleton Claude needs to work reliably.
+The host-native Okstra lead owns judgment policy and worker orchestration. `okstra` prepares one runtime-neutral task bundle and resolves every provider assignment to either the current native session or a registered CLI wrapper.
 
 ## Table of contents
 
@@ -30,8 +30,8 @@ Claude lead owns judgment policy and worker orchestration. `okstra` focuses on p
 - [What okstra does](#what-okstra-does)
 - [Runtime assets vs support assets](#runtime-assets-vs-support-assets)
 - [Architecture: python authority + thin callers](#architecture-python-authority--thin-callers)
-- [Claude execution behavior](#claude-execution-behavior)
-- [Claude prompt contract](#claude-prompt-contract)
+- [Host runtime execution behavior](#host-runtime-execution-behavior)
+- [Lead prompt contract](#lead-prompt-contract)
 - [Required team contract](#required-team-contract)
 - [Stable task identity](#stable-task-identity)
 - [Project self-registration](#project-self-registration)
@@ -42,7 +42,7 @@ Claude lead owns judgment policy and worker orchestration. `okstra` focuses on p
 - (See [cli.md](cli.md) for CLI arguments, options, and interactive input)
 - [Storage model & contracts](#storage-model--contracts) → [`architecture/storage-model.md`](architecture/storage-model.md)
   - Stable task root / per-run artifacts / `~/.okstra` indexes
-  - Task manifest · task index · run manifest · timeline · Claude operating contract
+  - Task manifest · task index · run manifest · timeline · runtime-neutral operating contract
 - [Task brief usage](#task-brief-usage)
 - [Recommended workflow](#recommended-workflow)
   - [1. Write a draft](#1-write-a-draft)
@@ -68,10 +68,10 @@ Claude lead owns judgment policy and worker orchestration. `okstra` focuses on p
 ## Purpose
 
 This document is a task-key-oriented operations guide to using `okstra` in `Okstra`.
-Where `README.md` is the quick entry point, this document is the detailed reference for `okstra`'s execution contract, storage model, lifecycle, and Claude handoff rules.
+Where `README.md` is the quick entry point, this document is the detailed reference for `okstra`'s execution contract, storage model, lifecycle, and host handoff rules.
 
 `okstra` is not a single-file review tool.
-`okstra` is a supporting tool that prepares stable task bundles, run history, and project-level discovery metadata so Claude Code can perform cross-verification.
+`okstra` is a supporting tool that prepares stable task bundles, run history, and project-level discovery metadata so a supported host can perform cross-verification.
 
 ## What okstra does
 
@@ -80,11 +80,11 @@ okstra's prepare responsibilities are consolidated in a single Python entry poin
 - Verifies that okstra installation assets exist (`~/.agents/skills/okstra-*`, optional `~/.claude/skills/okstra-*` / `~/.claude/agents/*-worker.md`, `~/.okstra/bin/...`)
 - Self-registers `<PROJECT_ROOT>/.okstra/project.json` (or verifies that the projectId matches)
 - Loads task type → `prompts/profiles/<task-type>.md` and extracts recommended workers
-- Normalizes user worker/model overrides (display ↔ execution-value mapping for Claude/Codex/Antigravity/Report-writer)
+- Normalizes user worker/model overrides through the provider registry (Claude, Codex, Antigravity, Grok, Kimi, and report-writer-capable providers)
 - Resolves task-brief / clarification-response paths (cwd first → PROJECT_ROOT fallback)
 - Computes the stable task root and all paths/sequences inside a per-task mutex (`~/.okstra/.locks/<task-key>.lock`), then persists them to `<run-dir>/manifests/run-context-<seq>.json`
 - Persists user input to `<run-dir>/manifests/run-inputs-<seq>.json`
-- Renders the instruction set (`analysis-profile.md`, `analysis-packet.md`, `analysis-material.md`, `task-brief.md`, `reference-expectations.md`, `final-report-template.md`, `final-report-schema.json`, optional `clarification-response.md`, optional `directive.txt`, final-verification-only `verification-target.md`, `claude-execution-prompt.md`) and writes a run prompt snapshot
+- Renders the instruction set (`analysis-profile.md`, `analysis-packet.md`, `analysis-material.md`, `task-brief.md`, `reference-expectations.md`, `final-report-template.md`, `final-report-schema.json`, optional `clarification-response.md`, optional `directive.txt`, final-verification-only `verification-target.md`, canonical `lead-execution-prompt.md`, and its Claude-named compatibility alias) and writes a run prompt snapshot
 - Updates `task-manifest.json`, `task-index.md`, `run-manifest-*.json`, `history/timeline.json`, and `discovery/{latest-task,task-catalog}.json`
 - Writes a preassigned Claude session ID and `sessions/claude-resume-*.sh` (unless `--render-only` is used)
 - Records record_start in the central indexes (`~/.okstra/{active,recent}.jsonl`, `projects/<id>/{index.jsonl, meta.json}`)
@@ -92,9 +92,9 @@ okstra's prepare responsibilities are consolidated in a single Python entry poin
 The two callers of `prepare_task_bundle` are:
 
 1. **`scripts/okstra.sh`**: Parses and confirms CLI arguments → calls `prepare_task_bundle` → unless `--render-only` is used, launches `claude --model ... --session-id ... "$PROMPT"` via `exec`. It is a thin wrapper of about 160 lines.
-2. **`okstra-run` skill**: Runs the [`okstra_ctl.wizard`](../scripts/okstra_ctl/wizard.py) state machine (`okstra wizard init|step|...` CLI) in the same Claude session to collect user input → calls `okstra render-bundle` (that is, `prepare_task_bundle(render_only=True)`) → the current session reads the rendered lead prompt and assumes the lead role. It does not launch a new Claude process. The wizard decides all branching, validation, and ordering, so the skill body is a roughly 30-line loop that displays either `AskUserQuestion` (`pick`) or a plain-text message (`text`) according to `Prompt.kind`.
+2. **`okstra-run` skill**: Runs the [`okstra_ctl.wizard`](../scripts/okstra_ctl/wizard.py) state machine (`okstra wizard init|step|...` CLI) in the current supported host to collect user input → calls `okstra render-bundle` (that is, `prepare_task_bundle(render_only=True)`) → the current session reads the rendered lead prompt and assumes the lead role. It does not launch a new provider process for the native lead. The wizard decides all branching, validation, and ordering, so the skill body displays either the host's picker (`pick`) or a plain-text message (`text`) according to `Prompt.kind`.
 
-The lead Claude owns judgment policy and worker orchestration. okstra's prepare stage only creates structured assets so that the lead starts with the correct input bundle and output skeleton.
+The host-native Okstra lead owns judgment policy and worker orchestration. okstra's prepare stage only creates structured assets so that the lead starts with the correct input bundle and output skeleton.
 
 ## Runtime assets vs support assets
 
@@ -127,7 +127,7 @@ Runtime entry points are consolidated in Python packages. Bash and skills only c
 
 ### Bash entry points (thin)
 
-- [`scripts/okstra.sh`](../scripts/okstra.sh) — CLI parsing / interactive prompt / confirm-execution-plan / `prepare_task_bundle` invocation / `exec claude`.
+- [`scripts/okstra.sh`](../scripts/okstra.sh) — standalone compatibility launcher: CLI parsing / interactive prompt / `prepare_task_bundle` invocation / default `exec claude`. In-host Claude Code, Codex, and Antigravity runs use `okstra-run` and keep their current native session.
 - [`scripts/lib/okstra/{cli,globals,interactive,project-resolver,usage}.sh`](../scripts/lib/okstra/) — CLI/interactive support only; contains no artifact-generation logic.
 - [`scripts/okstra-ctl.sh`](../scripts/okstra-ctl.sh) + [`scripts/lib/okstra-ctl/`](../scripts/lib/okstra-ctl/) — central control-center CLI (list / show / open / rerun / reconcile / etc.).
 
@@ -146,10 +146,11 @@ Runtime entry points are consolidated in Python packages. Bash and skills only c
 ### Skills (`skills/`) and lead resources (`prompts/`)
 
 - [`prompts/lead/okstra-lead-contract.md`](../prompts/lead/okstra-lead-contract.md) is the runtime-neutral lifecycle core: phase boundaries, artifacts, convergence, report ownership, and persistence semantics.
-- `prompts/lead/adapters/claude-code.md`, `prompts/lead/adapters/codex.md`, and `prompts/lead/adapters/external.md` map the same semantic operations to one selected host runtime. The generated launch prompt exposes the core path plus exactly one adapter path.
-- Runtime selection and worker-provider assignment remain independent. Milestone 1 keeps `claude-execution-prompt.md`, existing manifest role labels, model defaults, and worker rosters for compatibility; provider registry and front-door separation are later milestones.
+- `prompts/lead/adapters/claude-code.md`, `prompts/lead/adapters/codex.md`, `prompts/lead/adapters/antigravity.md`, and `prompts/lead/adapters/external.md` map the same semantic operations to one selected host runtime. The generated launch prompt exposes the core path plus exactly one adapter path.
+- Runtime metadata and role assignments are persisted separately, but the lead provider is derived from the host: Claude Code maps to Claude, Codex maps to Codex, and Antigravity CLI maps to Antigravity. New runs persist `hostRuntime`, `leadAssignment`, and `workerAssignments[]`; each assignment records its provider, model, execution value, and resolved `native-session` or `cli-wrapper` runner. `lead-execution-prompt.md` is canonical, while `claude-execution-prompt.md` is a byte-identical compatibility alias for historical consumers.
+- Provider registry and front-door separation are implemented: the active Claude Code, Codex, or Antigravity host owns the native lead session, while non-host providers run through their registered CLI wrappers.
 - [`skills/okstra-setup/SKILL.md`](../skills/okstra-setup/SKILL.md) — **first-run bootstrap**. Runs `okstra install` and creates `project.json`.
-- [`skills/okstra-run/SKILL.md`](../skills/okstra-run/SKILL.md) — in-session entry point that **starts an okstra task in the current Claude session**. Calls `prepare_task_bundle` directly.
+- [`skills/okstra-run/SKILL.md`](../skills/okstra-run/SKILL.md) — host-aware in-session entry point that starts an okstra task in the current Claude Code, Codex, or Antigravity session and calls `prepare_task_bundle` directly.
 - Thirteen skills are user-invocable: `skills/okstra-setup/SKILL.md`, `skills/okstra-brief-gen/SKILL.md`, `skills/okstra-run/SKILL.md`, `skills/okstra-manager/SKILL.md`, `skills/okstra-memory/SKILL.md`, `skills/okstra-inspect/SKILL.md`, `skills/okstra-rollup/SKILL.md`, `skills/okstra-usage/SKILL.md`, `skills/okstra-schedule-gen/SKILL.md`, `skills/okstra-container-build/SKILL.md`, `skills/okstra-pr-gen/SKILL.md`, `skills/okstra-user-response/SKILL.md`, and `skills/okstra-code-review/SKILL.md`. Only these are copied into the agent skill home. They cover brief authoring, phase execution, cross-project manager task coordination, global Memory Book storage/search, read-side status/history/report/time/logs/cost/errors/recap, task-group-level aggregation of run results (rollup), project-wide historical resource usage, schedule support, local container deployment, PR description generation, clarification-response submission, and census-based code review of a stage or branch diff. `okstra-manager` uses `okstra manager` CLI JSON/launch packets as the source of truth, and stores manager-owned plans, assignments, directives, snapshots, and events under `~/.okstra/managers/<manager-id>/`. `okstra-rollup` is a read-side layer that fans the single-task aggregators from `okstra-inspect` (time/errors/recap) out to a task group or the whole project catalog. The `okstra rollup` CLI owns deterministic aggregation, while the skill (LLM) writes only the synthesized report summary. `okstra-usage` is a separate read-only resource snapshot grouped by lifecycle task type; it does not replace single-task `okstra-inspect` detail or the status/report digest from `okstra-rollup`. The canonical definition of `okstra-inspect` read-side facets is the subcommand table in `skills/okstra-inspect/SKILL.md`. `okstra-inspect logs` provides a read-only inventory and cleanup guidance for the live-log sidecars that the Codex/Antigravity wrappers write on every dispatch at the resolved `<run-dir>/prompts/<worker>-prompt-<phase>-<seq>.log`; for stage executions, the stage-qualified `run_dir` includes `stage-<N>/`. `okstra-inspect cost` summarizes `okstra context-cost`; `okstra-inspect errors` collects a task's okstra-run error logs into a timestamped Markdown error report and prints a summary; and `okstra-inspect recap` answers free-form questions about `.okstra` artifacts in addition to summarizing phases before and after each task run.
 - Internal operating contracts—`context-loader` / `team-contract` / `convergence` / `report-writer` and the lead contract—have moved to `prompts/lead/*.md`. Language-specific coding preflight for implementation/verification workers has moved to `prompts/coding-preflight/*` (overview router + clean-code + three-stage language/framework/architecture selection). All are runtime resources installed under `~/.okstra/prompts/` and are not discoverable as skills. The generated launch prompt provides the lead with absolute paths, and reinstalling prunes the legacy exact-name skill directories `okstra-context-loader` / `okstra-team-contract` / `okstra-convergence` / `okstra-report-writer` / `okstra-coding-preflight` / `okstra`.
 - Plugin manifest: [`../../.claude-plugin/plugin.json`](../.claude-plugin/plugin.json) — referenced by the supplementary `npx skills@latest add Devonshin/okstra` channel. Use `npx okstra@latest install` for normal setup. The plugin manifest exposes only the thirteen user entry points (`okstra-setup`, `okstra-brief-gen`, `okstra-run`, `okstra-manager`, `okstra-memory`, `okstra-inspect`, `okstra-rollup`, `okstra-usage`, `okstra-schedule-gen`, `okstra-container-build`, `okstra-pr-gen`, `okstra-user-response`, `okstra-code-review`).
@@ -259,47 +260,48 @@ The following environment variables are read only as user settings, not for stat
 
 Other variables such as `PROJECT_ID`, `TASK_GROUP`, `RUN_*`, `FINAL_*`, and `CLAUDE_*` are not exported and do not leak into child processes.
 
-## Claude execution behavior
+## Host runtime execution behavior
 
-In the current implementation, `okstra` executes Claude as follows.
+The front door declares its host from harness context, never by looking for installed provider binaries. Claude Code selects the Claude native session; Codex selects the Codex native session. Other selected providers resolve to CLI wrappers. A lead provider that disagrees with an in-session host is rejected before dispatch so the manifest cannot claim a model that never ran.
+
+The legacy standalone shell path remains Claude-specific:
 
 **Mode A — `okstra.sh` launches a new Claude process**
 - With `--render-only`, it exits after creating the instruction set without running Claude.
 - Without `--render-only`, the prepare stage preassigns a Claude session ID and creates `claude-resume-<task-type>-<seq>.sh` under the current run's `sessions/` directory.
-- It then runs `claude --model <lead> --session-id "$CLAUDE_SESSION_ID" "$PROMPT"` via `exec` from the target project root using the resolved `Claude lead` model execution value. (The former `--settings <runtime-settings>` argument was removed in 0.14.0; permissions are now provided by the `<PROJECT_ROOT>/.claude/settings.local.json` symlink.)
-- `okstra.sh` performs only the handoff; the Claude lead continues by saving the final report and updating run/task state.
+- It then runs `claude --model <lead> --session-id "$CLAUDE_SESSION_ID" "$PROMPT"` via `exec` from the target project root using the standalone launcher's resolved Claude lead model. (The former `--settings <runtime-settings>` argument was removed in 0.14.0; permissions are now provided by the `<PROJECT_ROOT>/.claude/settings.local.json` symlink.)
+- `okstra.sh` performs only this compatibility handoff; the launched session continues under the same Okstra lead contract. Codex-hosted runs do not pass through this shell path.
 
-**Mode B — the `okstra-run` skill hands off within the current Claude session**
-- Use this when the user is already in a Claude session and wants to start a new okstra task there.
-- The skill collects task candidates, task type, brief, and other input through `AskUserQuestion`, then calls `prepare_task_bundle(render_only=True)` to create the same instruction set on disk.
-- It does not launch a new Claude process. The current session reads the rendered lead prompt and immediately assumes the lead role.
+**Mode B — the `okstra-run` skill hands off within the current host session**
+- Use this when the user is already in Claude Code, Codex, or Antigravity and wants to start a new okstra task there.
+- The skill relays the wizard through the host question/text interface and calls `prepare_task_bundle(render_only=True)` with the explicit host runtime.
+- It does not launch another lead process. The current host-native session reads `lead-execution-prompt.md` and assumes the Okstra lead role.
 
 Both modes create identical artifacts (task-manifest, run-manifest, timeline, instruction set, and central-index registration), so subsequent `okstra-ctl` commands (list / show / rerun / reconcile) operate consistently without distinguishing between them.
-- The handed-off main Claude acts as the `Claude lead`, responsible for orchestration and final synthesis.
-- The default worker roles for the standard workflow are `Claude worker`, `Codex worker`, and `Report writer worker`; `Antigravity worker` is optional and is included only when explicitly requested through `--workers` or the profile.
-- Claude assigns worker responsibilities and makes the final judgment after reading the task bundle.
+- The handed-off native host acts as the Okstra lead, responsible for orchestration and final synthesis.
+- The default worker policy remains Claude + Codex analysis and a Claude report writer. Antigravity, Grok, and Kimi are profile-gated optional assignments; Grok and Kimi are read-only analyser/critic providers.
+- The lead assigns worker responsibilities and makes the final judgment after reading the task bundle.
 - okstra Claude assets installed in the user home (`~/.claude/skills`, `~/.claude/agents`) instruct Claude to dispatch workers through `Agent(name: ...)`; workers automatically join the session's implicit team.
 - **Team lifecycle (Claude Code v2.1.178+)**: v2.1.178 removed the `TeamCreate` / `TeamDelete` tools and the `team_name` parameter from `Agent(...)`. When `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` (seeded into `settings.json` by `okstra install`), one implicit team per session is created automatically at startup. In Phase 3, the lead does not call a team-creation tool. It records only the `teamName` audit label and `teamCreate: { attempted: false, status: "implicit", splitPane: <true-if-TMUX-is-set> }`, then dispatches workers through `Agent(name: "<role>-worker", run_in_background: true)` (without team_name). Split-pane teammates appear when `$TMUX` is set and `teammateMode: auto`; outside tmux they run in-process, and both modes are valid. At run end, after Phase 7 token accounting, the lead checks for remaining tmux panes and asks whether to clean up worker teammates only for split-pane runs. If approved, `okstra-team-reconcile.sh` marks dead-pane stale-active members inactive and sends each completed teammate a `SendMessage` shutdown_request. There is no tool for deleting the implicit team; it disappears when the session ends. If the user keeps the teammates, they remain in the FleetView roster and the lead tells the user to remove them through Teams/FleetView (see *Run-end teammate teardown* in `prompts/profiles/_common-contract.md`). Phase 7 token accounting locates worker sessions by top-level `agentName` or nested `subagents/agent-a<name>-<hash>.jsonl` filenames when `teamCreate.status` is `implicit`/`skipped`/`error`.
 
-## Claude prompt contract
+## Lead prompt contract
 
-The Claude launch prompt body is always rendered only from the `prompts/launch.template.md` template.
+The canonical lead prompt body is rendered from `prompts/launch.template.md` to `lead-execution-prompt.md`. A selected runtime adapter maps its neutral operations to host primitives.
 
 - Prompt substitution is limited to scalar placeholder values such as the task key, session ID, and absolute/relative paths.
 - The selected profile body is rendered to `instruction-set/analysis-profile.md`.
 - The analysis material body is rendered to `instruction-set/analysis-material.md`.
 - The expected state for config/deployment is rendered to `instruction-set/reference-expectations.md`.
-- Claude must read these artifact files directly; long task-specific bodies must not be duplicated inline in the launch prompt.
+- The lead must read these artifact files directly; long task-specific bodies must not be duplicated inline in the launch prompt.
 
 ## Required team contract
 
 The standard `okstra` workflow applies the following team contract consistently across runtime prompts, profiles, manifests, and skill documentation.
 
-- The main Claude is always the `Claude lead` and operates in synthesis-only mode.
-- The default required worker roles are `Claude worker`, `Codex worker`, and `Report writer worker`. `Antigravity worker` is optional and is included as required only when explicitly named by `--workers` or the profile's `- Workers:` section.
-- `Report writer worker` focuses on report structure and evidence organization, but `Claude lead` remains the final synthesis owner.
-- The default model contract is computed from central defaults. Fallbacks are `Claude lead`=`opus`, `Claude worker`=`opus`, `Codex worker`=`gpt-5.6-sol`, `Report writer worker`=`sonnet`, and `Antigravity worker`=`gemini-3.1-pro` (when opted in). `Report writer worker` no longer inherits the `Claude lead` model — it resolves from its own catalog `ROLE_DEFAULTS` entry because it does not vote in convergence; `--report-writer-model opus` or `OKSTRA_DEFAULT_REPORT_WRITER_MODEL` restores the previous behavior.
-- Because `Antigravity worker` is optional, it is attempted only in runs where it is explicitly included.
+- The current host-native provider owns the synthesis-only lead session: Claude on Claude Code, Codex on Codex.
+- Every selected worker comes from the profile roster and provider capability registry. The default analysis policy remains Claude + Codex + a report writer; Antigravity, Grok, and Kimi are attempted only when the profile and resolved roster include them.
+- `Report writer worker` focuses on report structure and evidence organization, while the host-native lead remains the final synthesis owner. Claude is the default report-writer provider; Codex may be selected explicitly.
+- Model defaults are provider and functional-role policy. Fallbacks include Claude lead/analyser=`opus`, Codex lead/analyser=`gpt-5.6-sol`, Claude report writer=`sonnet`, Antigravity=`gemini-3.1-pro`, Grok analyser=`grok-build-0.1`, and Kimi analyser=`kimi-k2.7-code`.
 - Before the final judgment, each required role in the current run's worker roster must have either a result or an explicit terminal status (`completed`, `timeout`, `error`, `not-run`).
 - Every attempted worker (`completed`, `timeout`, `error`) must have an assigned worker prompt history file under the current run's `prompts/` directory.
 - Worker timing begins at the atomic transition to `in-progress`, which records `workers[].startedAt` in `team-state.json`; prompt creation time is not a dispatch proxy. `okstra worker-state transition` and both dispatch adapters share `dispatch_state.transition_worker_status`, while `okstra worker-liveness --team-state ... --worker ...` reads that timestamp as the launch-grace authority.
@@ -595,17 +597,17 @@ There are two entry methods, and they produce identical artifacts.
 scripts/okstra.sh --task-type error-analysis --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path>
 ```
 
-On this path, `okstra.sh` finishes the prepare stage and then runs a new interactive Claude session via `exec` from the target project root. It performs only the handoff; the Claude lead continues by saving the final report. Because `sessions/claude-resume-<task-type>-<seq>.sh` is written immediately before execution, the same run can be resumed if the session is interrupted.
+On this standalone compatibility path, `okstra.sh` finishes the prepare stage and then runs a new interactive Claude session via `exec` from the target project root. It performs only the handoff; the session continues under the Okstra lead contract. Because `sessions/claude-resume-<task-type>-<seq>.sh` is written immediately before execution, the same run can be resumed if interrupted. In-host Claude Code, Codex, and Antigravity paths retain the current native session instead.
 
-**Option B — hand off within the current Claude session (`okstra-run` skill)**
+**Option B — hand off within the current host session (`okstra-run` skill)**
 
-If you are already using a Claude Code session, the current session can assume the Claude lead role without launching a new process. Example triggers: `"run okstra here"`, `"start error-analysis on this project"`.
+If you are using Claude Code, Codex, or Antigravity, the current native session assumes the Okstra lead role without launching a replacement lead process. Example triggers: `"run okstra here"`, `"start error-analysis on this project"`.
 
 Skill flow:
 
-1. The `okstra-run` skill activates and collects task candidates / task type / brief path with `AskUserQuestion`.
+1. The `okstra-run` skill activates and relays task candidates, task type, and brief path through the current host's question or text interface.
 2. It calls `okstra_ctl.run.prepare_task_bundle(render_only=True)` with the user's input—directly invoking the same Python function without passing through `okstra.sh`.
-3. After the same instruction-set artifacts are written to disk, the current Claude reads the prompt and assumes the lead role.
+3. After the same instruction-set artifacts are written to disk, the current host reads the canonical lead prompt and assumes the lead role.
 
 See [`skills/okstra-run/SKILL.md`](../skills/okstra-run/SKILL.md) for the detailed procedure.
 
@@ -779,11 +781,11 @@ Generating a view never modifies the original final-report MD.
 
 ## Worker error collection (optional sidecar)
 
-Errors that occur while workers (Claude/Codex/Antigravity worker, Report writer, Claude lead) run can be collected into a single chronological log for later retrospectives.
+Errors that occur while provider workers, the report writer, or the Okstra lead run can be collected into a single chronological log for later retrospectives.
 
 - Storage location: resolved `<run-dir>/logs/errors-<task-type>-<seq>.jsonl` (`<run-dir>` includes `stage-<N>/` for a stage-isolated run)
 - Append-only JSON Lines, isolated per run, so there is no separate rotation policy.
-- **Single writer**: To avoid concurrent-append collisions, only the `Claude lead` writes this file directly. `<seq>` is an independent three-digit zero-padded counter (`001`, `002`, …) scanned per category directory (`logs/`, `manifests/`, `state/`, and so on), so category values may differ within one run when a prior run recorded only some categories. The cross-category identifier for one run is the manifest's `runDateTimeSegment` ISO timestamp field.
+- **Single writer**: To avoid concurrent-append collisions, only the active Okstra lead writes this file directly. `<seq>` is an independent three-digit zero-padded counter (`001`, `002`, …) scanned per category directory (`logs/`, `manifests/`, `state/`, and so on), so category values may differ within one run when a prior run recorded only some categories. The cross-category identifier for one run is the manifest's `runDateTimeSegment` ISO timestamp field.
   - Internal worker tool failures are reported in the worker-result manifest's `errors[]`, then dumped by the lead immediately after merge
   - Codex/Antigravity CLI failures, timeouts, and rate limits are observed directly by the lead through the wrapper
   - resultContract violations, schema mismatches, and missing required fields are observed directly during lead validation
@@ -852,16 +854,16 @@ Each validator blocks the phase with a `contract-violated` exit code when a cont
 - The task bundle's `instruction-set/reference-expectations.md` is generated alongside it as the config/deployment expected-state reference.
 - The current run session's resume helper is created at the resolved `<run-dir>/sessions/claude-resume-<task-type>-<seq>.sh`.
 - The run directory is organized into typed subdirectories such as `manifests/`, `state/`, `prompts/`, `reports/`, `status/`, `sessions/`, and `worker-results/`; prompt snapshots are prepared under `prompts/` first.
-- Claude creates workers and collects results.
-- The standard workflow uses a `Claude lead` with default workers `Claude worker`, `Codex worker`, and `Report writer worker`; `Antigravity worker` is optional and included only when explicitly requested.
-- Worker models can be overridden with `--lead-model`, `--claude-model`, `--codex-model`, `--antigravity-model`, and `--report-writer-model`; defaults are centrally managed through `OKSTRA_DEFAULT_*` environment variables. Fallback defaults are `Claude lead`=`opus`, `Claude worker`=`opus`, `Codex worker`=`gpt-5.6-sol`, `Report writer worker`=`sonnet`, and `Antigravity worker`=`gemini-3.1-pro`.
+- The host adapter creates workers and collects results according to persisted runner assignments.
+- The standard policy uses Claude and Codex analysers plus a report writer. Antigravity, Grok, and Kimi are optional and included only when the selected profile allows them.
+- Worker models can be overridden through the legacy provider flags or generic `--worker-model provider=model`; lead and report-writer provider choices are explicit. Defaults are centrally managed through the provider registry and `OKSTRA_DEFAULT_*` environment variables.
 - For `--task-type implementation`, select the provider that takes the Executor role with `--executor <claude|codex|antigravity>` (or `OKSTRA_DEFAULT_EXECUTOR`, fallback `claude`). Only the Executor may mutate project files. The other two providers and the Executor's own provider are each dispatched as verifiers in separate CLI sessions (session isolation preserves the self-review safeguard). The Executor's model reuses the selected provider's worker-model flag (`--claude-model` / `--codex-model` / `--antigravity-model`). Provider / displayName / workerAgent / model are recorded in the run-manifest `teamContract.executor` block.
-- Worktree cwd injection by Executor: Codex / Antigravity executors pin cwd to the worktree at the CLI layer through wrappers (`okstra-codex-exec.sh -C` / `okstra-antigravity-exec.sh --include-directories`). Because the Bash tool has no per-call cwd argument, the Claude executor prefixes cwd-sensitive toolchain invocations (`cargo`/`npm`/`pnpm`/`bun`/`pytest`/`make`/`go`) with `cd {{EXECUTOR_WORKTREE_PATH}} && <cmd>` in the same Bash invocation. Wrapping in `bash -lc`/`bash -c` is prohibited because it hides the leading `cd` token and defeats permission auto-allow. Prefer working-directory flags such as `git -C` or `cargo --manifest-path` when available. See the *Executor Worktree* block in `prompts/profiles/implementation.md` and the Executor exception in `agents/workers/claude-worker.md` for details.
+- Worktree targeting is runner-based. A native-session executor uses its host adapter's edit and command primitives against `EXECUTOR_WORKTREE_PATH`; a CLI-wrapper executor receives the worktree through its provider wrapper. Prefer explicit working-directory flags such as `git -C` or `cargo --manifest-path` when available.
 - The project-level current-task convenience pointer is `.okstra/discovery/latest-task.json`.
 - The project-level canonical task inventory is `.okstra/discovery/task-catalog.json`.
 - At `okstra install` time, okstra skill assets are seeded to `~/.agents/skills/` by default. If `~/.claude` exists, `~/.claude/skills/` + `~/.claude/agents/` are seeded as well (per-project seeding is no longer performed).
 - Seeded okstra Claude assets instruct Claude to dispatch workers into the session's implicit team with `Agent(name: ...)` (v2.1.178 removed `TeamCreate`/`TeamDelete`). Agent targets receive only skill Markdown.
-- Claude, not scripts, makes the final judgment.
+- The host-native Okstra lead, not preparation scripts or a report writer, makes the final judgment.
 - A stable task key must be maintained to enable later bug tracking, corrections, and reverification.
 - Worker errors are collected in the optional sidecar at the resolved `<run-dir>/logs/errors-<task-type>-<seq>.jsonl`, with the lead as the sole writer. For a stage-isolated run, `<run-dir>` includes `stage-<N>/`. The entry-point helper is `scripts/okstra-error-log.py`.
 - Token-usage and cost accounting are handled by `scripts/okstra-token-usage.py` and the Node wrapper `okstra token-usage`.