okstra 0.224.0 → 0.225.0

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: