okstra 0.224.0 → 0.225.1

package/runtime/python/okstra_ctl/phases/implementation_planning/round_completion.py

@@ -0,0 +1,177 @@
+"""채택된 계획 검증 배치의 결정적 후처리."""
+from __future__ import annotations
+
+import hashlib
+import json
+import subprocess
+from collections.abc import Mapping
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from okstra_ctl.convergence import validated_run_authority
+from okstra_ctl.convergence_store import load_owned_json_object, write_json_atomic
+from okstra_ctl.dispatch_state import dispatch_worker_key
+from okstra_ctl.error_log_write import record_runtime_failure
+from okstra_ctl.plan_items import PlanItemContractError, analyser_key, critic_is_rostered
+from okstra_ctl.run_context import dir_flock
+from okstra_ctl.worker_prompt_policy import (
+    is_plan_verify_dispatch_kind, verification_dispatch_round,
+)
+from .authoring import finish_verification_round, validate_current_review
+
+if TYPE_CHECKING:
+    from okstra_ctl.dispatch_core import DispatchPlan
+
+
+def _verifier_key(row: Mapping[str, Any]) -> str:
+    if row.get("assignmentRef") == "critic/scope":
+        return "critic"
+    return analyser_key(dispatch_worker_key(row))
+
+
+def _round_dispatches(plan: DispatchPlan, team: Mapping[str, Any]) -> tuple[int, list[dict]] | None:
+    accepted = {row.get("dispatchId") for row in team.get("agentResultLinks", [])
+                if isinstance(row, Mapping) and not row.get("supersededBy")}
+    native = [{**row, "kind": row.get("dispatchKind", ""),
+               "status": "completed" if row.get("status") == "dispatched" and row.get("dispatchId") in accepted else row.get("status"),
+               "workerResultPath": row.get("workerResultPath") or next(
+                   (link.get("resultPath") for link in team.get("agentResultLinks", [])
+                    if link.get("dispatchId") == row.get("dispatchId") and not link.get("supersededBy")), "")}
+              for row in team.get("agentDispatches", []) if isinstance(row, dict)]
+    tails = [rows[-1] for rows in (team.get("workerDispatches", []), native) if rows]
+    if not plan.jobs and tails and all(
+        not is_plan_verify_dispatch_kind(str(row.get("kind", ""))) for row in tails
+    ):
+        return None
+    rows = [row for row in [*team.get("workerDispatches", []), *native] if isinstance(row, dict)
+            and is_plan_verify_dispatch_kind(str(row.get("kind", "")))]
+    targets = {verification_dispatch_round(job.dispatch_kind) for job in plan.jobs
+               if is_plan_verify_dispatch_kind(job.dispatch_kind)}
+    if plan.jobs and not targets:
+        return None
+    if not rows:
+        return None
+    if len(targets) > 1:
+        raise PlanItemContractError("one plan-verification batch cannot span multiple rounds")
+    number = next(iter(targets)) if targets else max(
+        verification_dispatch_round(row["kind"]) for row in rows
+    )
+    superseded = {row.get("dispatchId") for row in team.get("agentResultLinks", [])
+                  if isinstance(row, Mapping) and row.get("supersededBy")}
+    latest: dict[str, dict] = {}
+    for row in rows:
+        if verification_dispatch_round(row["kind"]) != number or row.get("dispatchId") in superseded:
+            continue
+        key = _verifier_key(row)
+        previous = latest.get(key)
+        identity = row.get("invocationRef") or row.get("invocationId")
+        if previous and (not identity or identity != (previous.get("invocationRef") or previous.get("invocationId"))):
+            raise PlanItemContractError(f"ambiguous plan-verification invocations for {key}")
+        if previous is None or row.get("attempt", 1) > previous.get("attempt", 1):
+            latest[key] = row
+    return int(number), list(latest.values())
+
+
+def _accepted_results(plan: DispatchPlan, team: Mapping[str, Any], rows: list[dict]) -> list[str]:
+    authority = validated_run_authority(plan.manifest_path)
+    execution = authority.execution_manifest
+    results = []
+    for row in rows:
+        declared_path = plan.project_root / str(row.get("workerResultPath", ""))
+        path = declared_path.resolve(strict=True)
+        if declared_path.is_symlink():
+            raise PlanItemContractError("plan-verification result must not be a symlink")
+        if not path.is_relative_to(authority.run_dir / "worker-results") or not path.is_file():
+            raise PlanItemContractError("plan-verification result must stay inside this run's worker-results")
+        links = [link for link in team.get("agentResultLinks", []) if isinstance(link, Mapping)
+                 and link.get("dispatchId") == row.get("dispatchId") and not link.get("supersededBy")]
+        if len(links) != 1 or (plan.project_root / str(links[0].get("resultPath", ""))).resolve() != path:
+            raise PlanItemContractError("plan-verification result has no unique accepted result link")
+        if execution is not None:
+            attempts = [attempt for attempt in execution.attempts
+                        if attempt.invocation_ref == row.get("invocationRef")
+                        and attempt.attempt == row.get("attempt")]
+            if len(attempts) != 1 or attempts[0].status != "ok":
+                raise PlanItemContractError("plan-verification attempt is not accepted")
+            if (plan.project_root / str(attempts[0].result_path or "")).resolve() != path:
+                raise PlanItemContractError("accepted attempt result path does not match the dispatch")
+        token = f'-plan-verify-r{verification_dispatch_round(row["kind"])}-'
+        if token not in path.name:
+            raise PlanItemContractError("plan-verification result filename has the wrong round")
+        worker = path.name.split(token, 1)[0]
+        if analyser_key(worker) != _verifier_key(row):
+            raise PlanItemContractError("plan-verification result has the wrong worker")
+        results.append(f"{worker}={path}")
+    return sorted(results)
+
+
+def _completion_receipt(plan: DispatchPlan, number: int, results: list[str]) -> dict[str, Any]:
+    review = validate_current_review(plan.manifest_path)
+    digest = hashlib.sha256()
+    for path in [review.items, review.narrative, *(Path(value.split("=", 1)[1]) for value in results)]:
+        digest.update(str(path).encode())
+        digest.update(path.read_bytes())
+    digest.update(json.dumps(results).encode())
+    fingerprint = digest.hexdigest()
+    receipt = review.state.with_name(f"plan-round-completion-r{number}-{review.state.name.removeprefix('plan-body-verification-')}")
+    state = load_owned_json_object(review.state)
+    if receipt.is_file():
+        recorded = load_owned_json_object(receipt)
+        if recorded.get("inputDigest") == fingerprint and recorded.get("stateDigest") == hashlib.sha256(review.state.read_bytes()).hexdigest():
+            return recorded
+    if any(row.get("round") == number for row in state.get("roundHistory", [])):
+        return {"status": "needs-lead", "round": number,
+                "reason": "round already closed; automatic completion will not replace its recorded inputs"}
+    prepared = load_owned_json_object(review.items)
+    if prepared.get("dispatchKind") == "reverify":
+        return {"status": "needs-lead", "round": number,
+                "reason": "self-fix re-verification needs the lead's cause groups and completion metadata"}
+    completed = finish_verification_round(review, results, number)
+    output = {**completed, "status": "completed", "round": number,
+              "inputDigest": fingerprint, "stateDigest": hashlib.sha256(review.state.read_bytes()).hexdigest(),
+              "receiptPath": str(receipt)}
+    write_json_atomic(receipt, output)
+    return output
+
+
+def complete_ready_plan_round(plan: DispatchPlan) -> dict[str, Any] | None:
+    from okstra_ctl.dispatch_core import TERMINAL_DISPATCH_STATUSES
+
+    if plan.manifest.get("taskType") != "implementation-planning":
+        return None
+    number = 0
+    try:
+        with dir_flock(plan.team_state_path.parent, ".plan-round-completion.lock"):
+            team = load_owned_json_object(plan.team_state_path)
+            batch = _round_dispatches(plan, team)
+            if batch is None:
+                return None
+            number, rows = batch
+            review = validate_current_review(plan.manifest_path)
+            prepared = load_owned_json_object(review.items)
+            workers = {analyser_key(worker) for worker in prepared.get("reviewInputs", {}).get("workers", [])}
+            actual = {_verifier_key(row) for row in rows}
+            if prepared.get("dispatchKind") == "critic-tie":
+                if not critic_is_rostered(plan.manifest):
+                    return {"status": "needs-lead", "round": number,
+                            "reason": "the run has no rostered critic to settle this tie"}
+                if actual & workers and not actual - (workers | {"critic"}):
+                    return {"status": "needs-lead", "round": number,
+                            "reason": "critic shares an analyser round; preserve its queue through manual append"}
+                workers = {"critic"}
+            if actual - workers:
+                raise PlanItemContractError("plan-verification dispatch includes an unassigned verifier")
+            if not workers or actual != workers:
+                return {"status": "pending", "round": number, "reason": "waiting for the complete prepared verifier roster"}
+            if any(row.get("status") not in TERMINAL_DISPATCH_STATUSES for row in rows):
+                return {"status": "pending", "round": number, "reason": "waiting for every verifier to settle"}
+            if any(row.get("status") != "completed" for row in rows):
+                raise PlanItemContractError("one or more plan verifiers failed; preserve their results for lead recovery")
+            return _completion_receipt(plan, number, _accepted_results(plan, team, rows))
+    except (OSError, ValueError, RuntimeError, subprocess.TimeoutExpired) as exc:
+        output = {"status": "failed", "round": number, "reason": str(exc)}
+        logged = record_runtime_failure(plan.manifest_path, command="plan-round automatic completion",
+                                        exit_code=2, detail=str(exc))
+        if not logged["ok"]:
+            output["errorLogFailure"] = logged["reason"]
+        return output

package/runtime/python/okstra_ctl/render.py

@@ -1761,6 +1761,8 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
             Path(ctx.get("PROJECT_ROOT", "")), task_manifest, {}
         ),
         "leadModel": ctx.get("LEAD_MODEL", ""),
+        # `okstra-provider-exec.py` 가 워커를 띄울 때마다 읽는다.
+        "reasoningEffort": ctx.get("REASONING_EFFORT", ""),
         # Every other path in this manifest is project-relative; this is the
         # anchor they resolve against. Convergence reads it to place run
         # artifacts, so a manifest without it cannot seed a round.

package/runtime/python/okstra_ctl/run.py

@@ -130,6 +130,7 @@ from .domain.host import (
     ProviderUnavailable,
 )
 from .domain.provider import ServedModelAttestation
+from .domain.worker_exec import REASONING_EFFORTS
 from .execution_identity import (
     ExecutionManifest,
     ParticipantAssignment,
@@ -634,6 +635,9 @@ class PrepareInputs:
     # discussion 전용: 링크·짧은 설명·이 task 의 key. brief 자리는 prepare 가
     # 이 값으로 만든 입력 문서가 채운다.
     discussion_start: str = ""
+    # 이 run 이 띄우는 모든 워커 CLI 의 추론 강도(`REASONING_EFFORTS`). 빈 값이면
+    # 각 CLI 가 자기 설정을 따른다.
+    reasoning_effort: str = ""
 
 
 @dataclass
@@ -4257,6 +4261,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "OKSTRA_PLAN_VERIFICATION": (
             "false" if not inp.plan_verification_enabled else ""
         ),
+        "REASONING_EFFORT": inp.reasoning_effort,
         "ANALYSIS_SOURCE_COMMIT": analysis_source_commit,
         "ANALYSIS_TARGET_JSON": json.dumps(resolved_target, ensure_ascii=False),
         "EVIDENCE_INPUTS_JSON": json.dumps(
@@ -4687,6 +4692,10 @@ def build_prepare_argument_parser():
         ),
     )
     p.add_argument("--render-only", action="store_true", dest="render_only")
+    p.add_argument(
+        "--summary-only", action="store_true",
+        help="Omit the lead prompt body from render-only output; still prepare all artifacts.",
+    )
     p.add_argument(
         "--terminal-backend",
         dest="terminal_backend",
@@ -4698,6 +4707,16 @@ def build_prepare_argument_parser():
             "않고 멈춘다."
         ),
     )
+    p.add_argument(
+        "--reasoning-effort",
+        default="",
+        choices=["", *REASONING_EFFORTS],
+        dest="reasoning_effort",
+        help=(
+            "Reasoning effort every worker CLI in this run is started with. "
+            "Empty leaves each CLI on its own configuration."
+        ),
+    )
     p.add_argument(
         "--no-plan-verification",
         action="store_false",
@@ -4897,6 +4916,7 @@ def main(argv: list[str]) -> int:
         plan_verification_enabled=args.plan_verification_enabled,
         fix_cycle=args.fix_cycle,
         discussion_start=args.discussion_start,
+        reasoning_effort=args.reasoning_effort,
     )
     try:
         out = prepare_task_bundle(inputs)
@@ -4919,8 +4939,9 @@ def main(argv: list[str]) -> int:
         stages_csv = ",".join(str(s) for s in cr["active_stages"])
         print(f"okstra concurrent-run stages: {stages_csv}")
     if inputs.render_only:
-        print()
-        print(out.prompt_text, end="")
+        if not args.summary_only:
+            print()
+            print(out.prompt_text, end="")
     else:
         print(f"okstra current run dir: {ctx['RUN_DIR']}")
         print(f"final report path: {ctx['FINAL_REPORT_PATH']}")

package/runtime/python/okstra_ctl/team.py

@@ -35,6 +35,7 @@ from .dispatch_core import (
     DispatchPlan,
     await_dispatches,
     dispatch_plan,
+    existing_dispatch_plan as _plan_for_existing,
 )
 from .dispatch_checkpoints import (
     record_collect_checkpoints,
@@ -257,6 +258,11 @@ def _await(args) -> int:
         timeout_seconds=args.timeout_seconds,
         heartbeat_seconds=0 if args.json else args.heartbeat_seconds,
     )
+    from .phases.implementation_planning.round_completion import complete_ready_plan_round
+
+    completion = complete_ready_plan_round(plan) if code == 0 else None
+    if completion and completion["status"] == "failed":
+        code = 2
     if should_record:
         exit_state = _load_json(plan.team_state_path, "team-state")
         lines.extend(record_collect_checkpoints(
@@ -272,11 +278,16 @@ def _await(args) -> int:
     if args.json:
         payload = _await_payload(plan, code == 0)
         payload["progressLines"] = lines
+        if completion:
+            payload["planVerification"] = completion
         _print_json(payload)
     else:
         for line in lines:
             print(line)
-        print("ALL_WORKERS_DONE" if code == 0 else "POLL_TIMEOUT")
+        if completion:
+            print(json.dumps({"planVerification": completion}, ensure_ascii=False))
+        print("PLAN_VERIFICATION_FAILED" if completion and completion["status"] == "failed"
+              else "ALL_WORKERS_DONE" if code == 0 else "POLL_TIMEOUT")
     return code
 
 
@@ -402,23 +413,6 @@ def _observe_lead_session_from_manifest(
     observe_lead_session(project_root, team_state_path)
 
 
-def _plan_for_existing(
-    project_root: Path, workspace_root: Path, run_manifest_path: Path, manifest: Mapping[str, Any]
-) -> DispatchPlan:
-    root = project_root.resolve()
-    manifest_path = _resolve_project_path(root, str(run_manifest_path))
-    return DispatchPlan(
-        project_root=root,
-        workspace_root=workspace_root.resolve(),
-        manifest_path=manifest_path,
-        team_state_path=_resolve_project_path(root, _require_string(manifest, "teamStatePath")),
-        lead_events_path=_resolve_project_path(root, _require_string(manifest, "leadEventsPath")),
-        manifest=manifest,
-        jobs=(),
-        default_backend=_manifest_backend(manifest),
-    )
-
-
 def _await_payload(plan: DispatchPlan, completed: bool) -> dict[str, Any]:
     team_state = _load_json(plan.team_state_path, "team-state")
     dispatches = [d for d in team_state.get("workerDispatches", []) if isinstance(d, dict)]

package/runtime/python/okstra_ctl/wizard/__init__.py

@@ -68,6 +68,7 @@ from .ids import (
     S_HANDOFF_STAGE_PICK,
     S_PROJECT_EVIDENCE,
     S_PROJECT_EVIDENCE_PICK,
+    S_REASONING_EFFORT,
     S_PR_TEMPLATE,
     S_PR_TEMPLATE_PICK,
     S_PR_TEMPLATE_SCOPE,

package/runtime/python/okstra_ctl/wizard/confirmation.py

@@ -333,6 +333,8 @@ def confirmation_block(state: WizardState) -> str:
         lines.append(f"  pr-template   : {state.pr_template_path} ({state.pr_template_scope or 'once'})")
     if state.fix_cycle:
         lines.append(f"  fix-cycle     : {state.fix_cycle}")
+    if state.reasoning_effort:
+        lines.append(f"  reasoning     : {state.reasoning_effort}")
     lines.append(_msg(
         state.workspace_root, "confirmation", "provider_data_scope",
         project_root=state.project_root,

package/runtime/python/okstra_ctl/wizard/ids.py

@@ -238,6 +238,9 @@ S_PR_TEMPLATE_SCOPE = "pr_template_scope"
 S_FIX_CYCLE_CONFIRM = "fix_cycle_confirm"
 
 
+S_REASONING_EFFORT = "reasoning_effort"
+
+
 S_CONFIRM = "confirm"
 
 

package/runtime/python/okstra_ctl/wizard/registry.py

@@ -58,6 +58,7 @@ from .ids import (
     S_PROJECT_EVIDENCE_PICK,
     S_PR_TEMPLATE,
     S_PR_TEMPLATE_PICK,
+    S_REASONING_EFFORT,
     S_PR_TEMPLATE_SCOPE,
     S_RELATED_TASKS,
     S_RELATED_TASKS_PICK,
@@ -169,6 +170,9 @@ from .steps_plan import (
     _submit_stage_pick,
 )
 from .steps_options import (
+    _build_reasoning_effort,
+    _reasoning_effort_required,
+    _submit_reasoning_effort,
     _report_language_required,
     _build_report_language,
     _submit_report_language,
@@ -516,6 +520,13 @@ STEPS: list[Step] = [
                             and S_DIRECTIVE not in s.answered),
          build=_build_directive, submit=_submit_directive,
          owns=("directive", "directive_pending_text")),
+    # 역할 화면과 directive 뒤 — 이 run 이 띄울 워커가 정해진 다음에 묻는다.
+    Step(S_REASONING_EFFORT,
+         applies=lambda s: (S_REASONING_EFFORT not in s.answered
+                            and not s.directive_pending_text
+                            and _reasoning_effort_required(s)),
+         build=_build_reasoning_effort, submit=_submit_reasoning_effort,
+         owns=("reasoning_effort",)),
     Step(S_RELATED_TASKS_PICK,
          applies=lambda s: (_identity_ready(s)
                             and S_RELATED_TASKS_PICK not in s.answered),

package/runtime/python/okstra_ctl/wizard/render.py

@@ -118,6 +118,7 @@ def render_args(state: WizardState) -> dict[str, Any]:
         ),
         "pr-template-path": pr_template,
         "fix-cycle": state.fix_cycle,
+        "reasoning-effort": state.reasoning_effort,
         "host-session-context-json": serialize_host_session_context(
             _host_session_context(state)
         ),

package/runtime/python/okstra_ctl/wizard/state.py

@@ -132,6 +132,8 @@ class WizardState:
     # confirm / edit
     # "" | "yes" | "no" — done(release-handoff) task 재진입의 fix-cycle 기록 여부
     fix_cycle: str = ""
+    # `REASONING_EFFORTS` 중 하나. 워커가 정해지기 전에는 비어 있다.
+    reasoning_effort: str = ""
     confirmed: Optional[bool] = None
     confirmation_stages: str = ""
     confirmation_prompt: str = ""
@@ -627,6 +629,7 @@ _FIELD_DEFAULTS: dict[str, Any] = {
     "pr_template_path": "", "pr_template_pending_text": False,
     "pr_template_scope": "",
     "fix_cycle": "",
+    "reasoning_effort": "",
     "confirmed": None, "edit_target": "", "confirmation_prompt": "", "confirmation_stages": "",
     "confirmation_scope": {}, "user_authorization": {},
 }

package/runtime/python/okstra_ctl/wizard/steps_options.py

@@ -7,6 +7,7 @@ from pathlib import Path
 from typing import Callable, Optional
 
 from okstra_ctl.clarification_items import user_response_sidecars
+from okstra_ctl.domain.worker_exec import REASONING_EFFORTS
 from okstra_ctl.manager_paths import MANAGER_CONTEXT_DIRECTIVE_PREFIX
 from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
 from okstra_ctl.report_language import is_language_tag
@@ -25,6 +26,7 @@ from .ids import (
     S_PR_TEMPLATE,
     S_PR_TEMPLATE_PICK,
     S_PR_TEMPLATE_SCOPE,
+    S_REASONING_EFFORT,
     S_RELATED_TASKS,
     S_RELATED_TASKS_PICK,
     S_REPORT_LANGUAGE,
@@ -33,7 +35,14 @@ from .ids import (
     _REUSE_LAST_TOKEN,
     _SIBLINGS_TOKEN,
 )
-from .state import Option, Prompt, WizardError, WizardState
+from .state import (
+    Option,
+    Prompt,
+    WizardError,
+    WizardState,
+    _identity_ready,
+    _load_role_profile_for_state,
+)
 from .prompts import _opt, _p, _pick_snippet
 from .sources import _latest_run_inputs, _require_file, _suggest_latest_final_report
 
@@ -428,3 +437,34 @@ def _submit_pr_template_scope(state: WizardState, value: str) -> Optional[str]:
         )
     state.pr_template_scope = value
     return f"pr-template-scope: {value}"
+
+
+_RECOMMENDED_REASONING_EFFORT = "high"
+
+
+def _reasoning_effort_required(state: WizardState) -> bool:
+    """워커를 띄우지 않는 프로필(release-handoff)에는 강도를 넘길 CLI 가 없다."""
+    return _identity_ready(state) and bool(_load_role_profile_for_state(state).roles)
+
+
+def _build_reasoning_effort(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "reasoning_effort")
+    others = [level for level in REASONING_EFFORTS if level != _RECOMMENDED_REASONING_EFFORT]
+    return Prompt(
+        step=S_REASONING_EFFORT, kind="pick", label=t["label"],
+        options=[
+            _opt(_RECOMMENDED_REASONING_EFFORT,
+                 t["options"][_RECOMMENDED_REASONING_EFFORT], recommended=True),
+            *(_opt(level, t["options"][level]) for level in others),
+        ],
+        echo_template=t["echo_template"])
+
+
+def _submit_reasoning_effort(state: WizardState, value: str) -> Optional[str]:
+    level = value.strip().lower()
+    if level not in REASONING_EFFORTS:
+        raise WizardError(
+            f"expected one of {', '.join(REASONING_EFFORTS)}, got: {value!r}"
+        )
+    state.reasoning_effort = level
+    return f"reasoning-effort: {level}"

package/runtime/python/okstra_ctl/worker_dispatch.py

@@ -45,10 +45,19 @@ def main(argv: Sequence[str] | None = None) -> int:
             _print_json(_backend_payload(backend_plan, dry_run=True))
             return 0
         code, lines = _dispatch_recording_checkpoints(backend_plan)
+        from .phases.implementation_planning.round_completion import complete_ready_plan_round
+        from .worker_prompt_policy import is_plan_verify_dispatch_kind
+
+        completion = complete_ready_plan_round(backend_plan) if code == 0 and any(
+            is_plan_verify_dispatch_kind(job.dispatch_kind) for job in backend_plan.jobs
+        ) else None
+        if completion and completion["status"] == "failed":
+            code = 2
         _print_json({
             **_backend_payload(backend_plan, dry_run=False),
             "exitCode": code,
             "progressLines": lines,
+            **({"planVerification": completion} if completion else {}),
         })
         return code
     except DispatchError as exc:

package/runtime/python/okstra_ctl/worker_request.py

@@ -12,7 +12,11 @@ import os
 import subprocess
 from pathlib import Path
 
-from .domain.worker_exec import ExecutionPolicy, WorkerExecRequest
+from .domain.worker_exec import (
+    REASONING_EFFORTS,
+    ExecutionPolicy,
+    WorkerExecRequest,
+)
 from .domain.worker_role import role_spec
 from .write_policy import WriteEnforcement, WritePolicy
 
@@ -39,6 +43,7 @@ def build_request(
     session_id: str = "",
     write_policy: WritePolicy | None = None,
     write_enforcement: WriteEnforcement | None = None,
+    reasoning_effort: str = "",
 ) -> WorkerExecRequest:
     """One dispatch, with every value the strategies will not re-derive.
 
@@ -46,6 +51,11 @@ def build_request(
     strategies hand what they are given straight to a CLI, so an unresolved
     `..` or symlink would survive into the sandbox boundary itself.
     """
+    if reasoning_effort and reasoning_effort not in REASONING_EFFORTS:
+        raise ValueError(
+            f"reasoning effort must be one of {', '.join(REASONING_EFFORTS)}: "
+            f"{reasoning_effort!r}"
+        )
     root = project_root.resolve()
     worktree = worktree_path.resolve() if worktree_path is not None else None
     return WorkerExecRequest(
@@ -64,6 +74,7 @@ def build_request(
         ),
         idle_timeout_seconds=idle_timeout_seconds,
         session_id=session_id,
+        reasoning_effort=reasoning_effort,
     )
 
 

package/runtime/schemas/execution-manifest-v2.schema.json

@@ -18,6 +18,7 @@
     "schemaVersion": {"const": "2.0"},
     "executionIdentityVersion": {"const": 2},
     "entryMode": {"enum": ["current-session", "new-session"]},
+    "reasoningEffort": {"enum": ["", "low", "medium", "high", "xhigh"]},
     "participantAssignments": {
       "type": "array",
       "items": {"$ref": "#/$defs/ParticipantAssignment"}

package/runtime/skills/_fragments/bash-invocation-rule.md

@@ -1 +1 @@
-Run one Bash tool call, starting with the literal token `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — a non-literal leading token defeats the `Bash(okstra:*)` permission match):
+Run one shell-command tool call, starting with the literal token `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — literal command tokens keep execution permissions reviewable):

package/runtime/skills/_fragments/host-question-interface.md

@@ -0,0 +1 @@
+For authored questions, `prompt_user` means the current host's available question interface, not a literal tool name. Use the selected host relay when one is provided. Preserve every question, option, description, and answer; use native controls only when the live session permits them and the complete interaction fits its limits. Otherwise show complete numbered choices and accept the user's reply; collect free text through normal conversation. If a native control is refused, follow the relay's recovery mapping, or use text when no relay is provided. A delivery acknowledgement or preselected option is not an answer; wait for the user's actual response.

package/runtime/skills/_fragments/host-runtime-selection.md

@@ -0,0 +1 @@
+Resolve `<host-runtime>` from the launcher's `OKSTRA_RUNTIME_HOST` when present; otherwise use the registered host ID declared by the current harness. Do not infer the host from worker models, installed executables, or `PATH`. If neither source identifies the host, report that it is unknown instead of substituting another host. Keep the same resolved host when retrying against another project directory.

package/runtime/skills/_fragments/wizard-bash-invocation-rule.md

@@ -1 +1 @@
-**Bash invocation rule (permission-friendly)**: every Bash command in this skill begins with the literal token `okstra` (or another already-allowed binary) and passes literal argument values. Do not introduce shell variables (`$STATE_FILE`, `$ANSWER`, `$projectRoot`, ...), `$(...)` command substitution, or leading `VAR=...` assignments — any of those make the leading token non-literal, defeat the `Bash(okstra:*)` permission match, and force a confirmation prompt on every wizard call. When a prior tool call emitted a path or value, read it from the tool output and paste the literal string into the next command.
+**Shell invocation rule (permission-friendly)**: every shell command in this skill begins with the literal token `okstra` (or another already-allowed binary) and passes literal argument values. Do not introduce shell variables (`$STATE_FILE`, `$ANSWER`, `$projectRoot`, ...), `$(...)` command substitution, or leading `VAR=...` assignments — any of those make the command harder to audit; apply the selected host adapter's execution-permission guidance. When a prior tool call emitted a path or value, read it from the tool output and paste the literal string into the next command.

package/runtime/skills/_fragments/wizard-preflight.md

@@ -6,7 +6,7 @@ Record the semantic functions that the live harness can actually perform. Always
 
 The host-native provider runs as the current lead session when its role is supported. Other selected providers run through their registered CLI wrappers. Claude remains only the model-policy default; it is not the process owner.
 
-Run one Bash tool call (Bash invocation rule from the top of this file applies):
+Run one shell-command tool call (Shell invocation rule from the top of this file applies):
 
 ```bash
 okstra preflight --runtime <host-runtime>

package/runtime/skills/_fragments/wizard-render-bundle.md

@@ -29,9 +29,9 @@ okstra config set pr-template-path "<value>" --scope global
 
 If an action has an unknown `command`, `key`, or `scope`, stop and report the wizard output instead of inventing a command.
 
-Before rendering the next phase's bundle — and between worker rounds within a phase (reverify/critic/gapverify batches), after you have collected that round's results and token usage and before you dispatch the next round — close the panes of the dispatches that finished in the prior round so they do not accumulate: `okstra team reclaim --project-root <projectRoot> --run-manifest <RUN_MANIFEST_PATH>` closes them, records `phase-batch-cleanup panes=<n>` with the number it closed, and prints that `PROGRESS:` line last — emit it as printed and do not call `okstra lead-progress append` for it. The command reads each dispatch's recorded status, so an in-progress worker keeps its pane whichever moment you call it. It closes only the panes okstra opened and recorded — a pane the harness opened for its own teammate carries no recorded id and is not okstra's to close. `shutdown_request` alone only idles the agent and frees no pane, so it stays part of the run-end sequence for roster/token hygiene. A `cli-wrapper` run holds no pane at all and `team reclaim` refuses it, so record the checkpoint there with `okstra lead-progress append … --phase phase-batch-cleanup --field panes=0`.
+Before rendering the next phase's bundle — and between worker rounds within a phase (reverify/critic/gapverify batches), after you have collected that round's results and token usage and before you dispatch the next round — close the panes of the dispatches that finished in the prior round so they do not accumulate: `okstra team reclaim --project-root <projectRoot> --run-manifest <RUN_MANIFEST_PATH>` closes them, records `phase-batch-cleanup panes=<n>` with the number it closed, and prints that `PROGRESS:` line last — emit it as printed and do not call `okstra lead-progress append` for it. The command reads each dispatch's recorded status, so an in-progress worker keeps its pane whichever moment you call it. It closes only the panes okstra opened and recorded — a pane the harness opened for its own teammate carries no recorded id and is not okstra's to close. After collecting results and token usage, apply the selected adapter's `shutdown_workers` operation only to confirmed-complete workers; preserve in-flight workers and the lead. A `cli-wrapper` run holds no pane at all and `team reclaim` refuses it, so record the checkpoint there with `okstra lead-progress append … --phase phase-batch-cleanup --field panes=0`.
 
-Before you ask the user for any approval, clarification, or decision after workers have been dispatched, run `okstra team reclaim … --gate` first: it closes the finished panes and prints `PROGRESS: phase-gate-cleanup panes=<n>` for you to emit, without recording a batch cleanup. Then `TaskStop` each completed worker. A `TaskStop` by itself idles the task but leaves the pane open — the `team reclaim` call is what closes it. This keeps a user gate from being shown while finished worker panes remain; in-progress dispatches keep their panes. Then follow `prompts/lead/okstra-lead-contract.md` "User confirmation before an approval blocker": read cited plan items, worker findings, and files before asking, and ask in the user's language with each option's outcome.
+Before you ask the user for any approval, clarification, or decision after workers have been dispatched, run `okstra team reclaim … --gate` first: it closes the finished panes and prints `PROGRESS: phase-gate-cleanup panes=<n>` for you to emit, without recording a batch cleanup. Then apply the selected adapter's `shutdown_workers` operation to confirmed-complete workers after collecting their results and token usage; preserve in-flight workers and the lead. This keeps a user gate from being shown while finished worker panes remain; in-progress dispatches keep their panes. Then follow `prompts/lead/okstra-lead-contract.md` "User confirmation before an approval blocker": read cited plan items, worker findings, and files before asking, and ask in the user's language with each option's outcome.
 
 Build the `okstra render-bundle` invocation from `outcome.renderArgv`, passing every token verbatim and in order (including empty strings — they are intentional `use phase default` markers).
 
@@ -44,13 +44,13 @@ Step 3's empty-answer and escaping rules apply verbatim: every flag in `renderAr
 `renderArgv` already contains exactly one `--lead-runtime <host-runtime>` pair. Do not add or replace it. Do not enumerate a fixed provider list in this skill because the wizard and role model pool own the ordered tokens.
 
 ```bash
-okstra render-bundle \
+okstra render-bundle --summary-only \
   <outcome.renderArgv token 1> \
   <outcome.renderArgv token 2> \
   <each remaining outcome.renderArgv token in order>
 ```
 
-`render-bundle` auto-supplies `--workspace-root` and forces `--render-only`. Stdout prints `okstra task root:`, `okstra instruction-set:`, `okstra run manifest:`, and the full rendered lead prompt. Parse the labelled lines for `TASK_ROOT`, `INSTRUCTION_SET_PATH`, and `RUN_MANIFEST_PATH`. Also watch for an optional `okstra concurrent-run stages:` label line — present only when a concurrent run is detected (see "Concurrent-run detection branch" below).
+`render-bundle` auto-supplies `--workspace-root` and forces `--render-only`. Stdout prints `okstra task root:`, `okstra instruction-set:`, `okstra run manifest:`, and other preparation status. `--summary-only` omits the lead prompt body from stdout; Step 6 reads the verified saved prompt from the manifest path. Parse the labelled lines for `TASK_ROOT`, `INSTRUCTION_SET_PATH`, and `RUN_MANIFEST_PATH`. Also watch for an optional `okstra concurrent-run stages:` label line — present only when a concurrent run is detected (see "Concurrent-run detection branch" below).
 
 Before acting as the lead, read `resources.leadPromptMetadataPath` from the run
 manifest and execute the host-native specification-link gate: