okstra 0.202.0 → 0.204.0

package/runtime/python/okstra_ctl/model_discovery.py

@@ -73,6 +73,25 @@ def _codex_home() -> Path:
     return Path.home() / ".codex"
 
 
+@lru_cache(maxsize=1)
+def codex_cli_version(codex_bin: str = "codex") -> str:
+    """디스패치에 쓸 codex CLI 의 버전, 알 수 없으면 "".
+
+    `codex --version` 은 `codex-cli 0.155.1` 처럼 마지막 마디에 버전을 싣는다.
+    """
+    try:
+        proc = subprocess.run(
+            [codex_bin, "--version"],
+            capture_output=True, text=True, timeout=20,
+        )
+    except (FileNotFoundError, OSError, subprocess.SubprocessError):
+        return ""
+    if proc.returncode != 0:
+        return ""
+    parts = proc.stdout.split()
+    return parts[-1].strip() if parts else ""
+
+
 def codex_availability(codex_home: Path | None = None) -> tuple[str, ...]:
     """Model slugs the codex CLI last fetched from the provider, or ().
 
@@ -100,6 +119,17 @@ def codex_availability(codex_home: Path | None = None) -> tuple[str, ...]:
     models = payload.get("models") if isinstance(payload, dict) else None
     if not isinstance(models, list):
         return ()
+    # 이 캐시는 codex 홈 하나를 쓰는 모든 클라이언트가 공유한다 — CLI 뿐 아니라
+    # ChatGPT 데스크톱 앱과 VS Code 확장도 자기 번들 버전으로 덮어쓴다. 그런데
+    # 카탈로그는 클라이언트 버전마다 다르다: 실측 2026-09-23, 같은 계정에서
+    # 0.155.1 은 gpt-6-sol·gpt-6-luna 를 내놓고 0.154.0·0.153.4 는 내놓지 않으며,
+    # 세 버전이 10분 사이 번갈아 이 파일을 썼다. 다른 클라이언트가 쓴 목록은
+    # okstra 가 실행할 CLI 의 카탈로그에 대한 근거가 아니므로 판정을 끈다 —
+    # 탐색 실패와 같은 처리이고, 정말 없는 모델이면 CLI 자신이 거절한다.
+    writer = payload.get("client_version")
+    running = codex_cli_version()
+    if running and isinstance(writer, str) and writer.strip() and writer.strip() != running:
+        return ()
     out: list[str] = []
     for entry in models:
         slug = entry.get("slug") if isinstance(entry, dict) else None

package/runtime/python/okstra_ctl/model_io/lines.py

@@ -10,6 +10,8 @@ from __future__ import annotations
 from pathlib import Path
 from typing import Any, Mapping
 
+from okstra_project.phase_pointer import promote
+
 from ..fixed_text import line as _line, scalar as _value
 from ..json_boundary import JsonBoundaryError
 
@@ -19,6 +21,17 @@ def _mapping(payload: Mapping[str, Any], key: str) -> Mapping[str, Any]:
     return value if isinstance(value, Mapping) else {}
 
 
+def next_phase_pointer(payload: Mapping[str, Any]) -> Mapping[str, Any]:
+    """`nextRecommendedPhase` 를 포인터로 읽는다. 구형 문자열도 승격한다.
+
+    `_mapping` 으로 읽으면 구형 문자열 포인터가 빈 매핑이 되어 `Next phase: -`
+    로 사라진다(ADR-0004 의 승격 예외가 이 읽기 경로에는 없었다). 값이 아예
+    없으면 빈 매핑 그대로 둔다 — 없는 포인터를 `pending` 으로 지어내지 않는다.
+    """
+    value = payload.get("nextRecommendedPhase")
+    return {} if value is None else promote(value)
+
+
 def _project_policy_lines(project: Mapping[str, Any]) -> str:
     packs = project.get("reviewRulePacks")
     pack_lines = (
@@ -84,7 +97,7 @@ def _worker_prompt_lines(run: Mapping[str, Any]) -> str:
 
 
 def _next_phase_lines(workflow: Mapping[str, Any]) -> str:
-    pointer = _mapping(workflow, "nextRecommendedPhase")
+    pointer = next_phase_pointer(workflow)
     return (
         _line("Next phase", pointer.get("phase"))
         + _line("Next phase status", pointer.get("status"))

package/runtime/python/okstra_ctl/model_io/renderers.py

@@ -29,6 +29,7 @@ from .lines import (
     _mapping,
     _next_phase_lines,
     _project_policy_lines,
+    next_phase_pointer,
     _provider_models,
     _status_overview_text,
     _worker_assignment_lines,
@@ -84,7 +85,7 @@ def _overview_rows(
         latest_run = _latest_timeline_run(project_root, manifest_path)
         _, group, _ = parse_task_key(task_key)
         workflow = _mapping(manifest, "workflow")
-        next_phase = _mapping(workflow, "nextRecommendedPhase")
+        next_phase = next_phase_pointer(workflow)
         # task 단위 현재 사실은 task-manifest 가 권위다(validate-run 이 run 종료
         # 시 거기에 쓴다). timeline 의 마지막 run 은 task-manifest 에 그 필드가
         # 없을 때의 폴백이고, 그 값도 run-manifest 로 덮어쓴 현재 사실이다.
@@ -372,7 +373,7 @@ def render_recap_input(project_root: Path, task_ref: str) -> str:
     for transition in transitions if isinstance(transitions, list) else []:
         if not isinstance(transition, Mapping):
             continue
-        pointer = _mapping(transition, "nextRecommendedPhase")
+        pointer = next_phase_pointer(transition)
         blocks.extend((
             "\n## Transition\n\n",
             _line("Run timestamp", transition.get("runTimestamp")),
@@ -420,7 +421,7 @@ def render_group_recap_input(project_root: Path, task_group: str) -> str:
     for task in tasks if isinstance(tasks, list) else []:
         if not isinstance(task, Mapping):
             continue
-        pointer = _mapping(task, "nextRecommendedPhase")
+        pointer = next_phase_pointer(task)
         memory = _mapping(task, "memory")
         blocks.extend((
             "\n## Task\n\n",

package/runtime/python/okstra_ctl/models.py

@@ -35,7 +35,7 @@ IMPLEMENTATION_ROLES = frozenset({"executor", "verifier"})
 # Legacy role-keyed compatibility defaults. Canonical assignments resolve a
 # provider first and then use ProviderSpec.default_models for that role.
 ROLE_DEFAULTS = {
-    "lead": "opus", "claude": "opus", "codex": "gpt-5.6-sol",
+    "lead": "opus", "claude": "opus", "codex": "gpt-6-sol",
     "antigravity": "gemini-3.1-pro", "report-writer": "sonnet",
 }
 

package/runtime/python/okstra_ctl/next_phase.py

@@ -235,8 +235,9 @@ def _from_option_selection(report_data: Mapping[str, Any]) -> dict[str, str]:
         # release-handoff 는 `routingRecommendation`.
         return make(status=STATUS_BLOCKED, rationale=_selection_guidance(selection))
     if routing == "pending-direction-selection":
-        # 이 상태는 **성공**이다 — 비교가 끝났고, 방향은 계획 단계의 위저드가
-        # 고르게 한다(`selected_direction_pick`). 그러니 다음 phase 는 지금 바로
+        # 이 상태는 **성공**이다 — 비교가 끝났고, 방향은 HTML 열람본의
+        # `DIRECTION SELECTION` Export 가 고르며 계획 위저드의
+        # `selected_direction_pick` 은 그 답이 딸린 리포트를 고른다. 그러니 다음 phase 는 지금 바로
         # 시작할 수 있는 `implementation-planning` 이고 status 는 `ready` 다.
         # 종전에는 phase 없는 `pending` 이었다: task 선택 화면이 `next: --
         # (pending)` 을 찍어 목적지를 지웠고, task-type 화면은 추천 없이 방금
@@ -276,11 +277,20 @@ def _direction_selection_reason(selection: Mapping[str, Any]) -> str:
     recommended = _text(selection.get("recommendedOptionId"))
     head = f"비교가 끝났습니다. 후보 {listed} 중 하나를 방향으로 고르세요"
     head += f" (권장 `{recommended}`)." if recommended else "."
+    # 위저드의 `selected_direction_pick` 은 후보가 아니라 **리포트**를 고른다
+    # (`wizard/steps_plan.py` `_build_selected_direction_pick`). 방향은 그 리포트
+    # 옆 `user-responses/` 의 `DIRECTION SELECTION` 사이드카가 정한다
+    # (`implementation_direction.py` `_comparison_selection`). 종전 문장은
+    # "위저드에 후보가 선택지로 나온다" 고 해서 사이드카 없이 계획을 열게 했다.
     return (
-        f"{head} 고르는 자리는 계획 단계의 위저드입니다 — `/okstra-run` 으로 "
-        "`implementation-planning` 을 시작하면 이 후보들이 선택지로 나옵니다. "
-        "이 phase 를 다시 돌리지 마세요: 비교는 이미 끝났고, 재실행은 같은 "
-        "비교를 처음부터 다시 합니다."
+        f"{head} 고르는 자리는 이 리포트의 HTML 열람본입니다 — 방향 선택 칸에서 "
+        "후보를 고르고 Export 한 파일을 "
+        "`runs/implementation-option-selection/user-responses/"
+        "user-response-implementation-option-selection-<이 리포트 번호>.md` 로 "
+        "저장하세요. 그다음 `/okstra-run` 으로 `implementation-planning` 을 "
+        "시작하고 위저드의 방향 보고서 단계에서 이 리포트를 고르면 저장한 방향이 "
+        "계획에 전달됩니다. 이 phase 를 다시 돌리지 마세요: 비교는 이미 끝났고, "
+        "재실행은 같은 비교를 처음부터 다시 합니다."
     )
 
 

package/runtime/python/okstra_ctl/operation_invocation.py

@@ -0,0 +1,86 @@
+"""okstra-run 밖에서 도는 Okstra 소유 LLM 작업의 준비.
+
+작업 계약(`agents/operations/<id>.json`)이 직무와 워커 수를 소유하고, 역할은 그
+직무의 `roleId` 에서 파생된다. 기술 문서는 작업 이름만 전달한다 — 역할·공급자·
+모델을 기술이 조립하면 같은 역할이 호출 표면마다 다른 규칙으로 배정된다
+(ADR-0017).
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from .contract_graph import (
+    ContractGraphError,
+    ContractGraphRoot,
+    ContractGraphValidator,
+    ContractSelection,
+)
+from .model_pool import ModelPool
+
+
+class OperationPreparationError(ValueError):
+    """작업을 디스패치 전에 준비할 수 없다. 메시지가 그 자리를 이름한다."""
+
+
+@dataclass(frozen=True)
+class OperationSlot:
+    """이 작업이 열 워커 한 칸. 모델은 칸마다 다르다."""
+
+    operation_id: str
+    duty_id: str
+    role_id: str
+    ordinal: int
+    model_ref: str
+    provider_id: str
+    display_name: str
+
+
+def resolve_operation_slots(
+    operation_id: str,
+    *,
+    contract_root: Path,
+    pool: ModelPool,
+) -> Sequence[OperationSlot]:
+    """작업 계약이 요구하는 칸과 각 칸의 모델.
+
+    모델은 런과 같은 기본값 사슬에서 고른다. 서로 다른 모델 참조를 요구한
+    수만큼 채우지 못하면 여기서 멈춘다 — 같은 모델을 반복하거나 워커 수를
+    줄이면 그 작업이 요구한 교차검증이 조용히 사라진다.
+    """
+    graph_root = ContractGraphRoot.from_base(contract_root)
+    try:
+        graph = ContractGraphValidator().validate(
+            graph_root, selected=ContractSelection(operation_id=operation_id)
+        )
+    except ContractGraphError as exc:
+        raise OperationPreparationError(str(exc)) from exc
+    operation = graph.operations.get(operation_id)
+    if operation is None:
+        known = ", ".join(sorted(graph.operations)) or "(none)"
+        raise OperationPreparationError(
+            f"unknown operation: {operation_id} (known: {known})"
+        )
+    duty_id = str(operation.payload["dutyId"])
+    count = int(operation.payload["count"])
+    role_id = graph.duties[duty_id].role_id
+
+    candidates = pool.default_candidates(role_id)
+    if len(candidates) < count:
+        raise OperationPreparationError(
+            f"operation {operation_id!r} requires {count} distinct models for role "
+            f"{role_id!r}, available {len(candidates)}"
+        )
+    slots = []
+    for ordinal, model in enumerate(candidates[:count], start=1):
+        slots.append(OperationSlot(
+            operation_id=operation_id,
+            duty_id=duty_id,
+            role_id=role_id,
+            ordinal=ordinal,
+            model_ref=str(model.model_ref),
+            provider_id=model.provider_id,
+            display_name=model.display_name,
+        ))
+    return tuple(slots)

package/runtime/python/okstra_ctl/option_comparison.py

@@ -0,0 +1,168 @@
+"""구현 방향 비교 자료 — 선택 리포트 기록 하나를 채팅용 사실 묶음으로 투영한다.
+
+사용자가 방향을 고르기 전에 비교 자료를 청하면 리드는 점수표·투표표·충족
+요약을 보여 준다. 그 숫자는 전부 `implementationOptionSelection` 기록에 있고
+`weightedScore` 는 발행 시점에 재계산 값과 대조된다
+(`implementation_options.py` `_validate_option_scores`). 리드가 JSON 을 손으로
+읽고 가중 점수를 다시 계산하던 자리를 이 명령이 대신한다. 서술(도입 문장,
+방향별 요지)은 리드가 `narrative` 와 각 방향의 근거 필드로 쓴다.
+
+읽기 전용이다. 어떤 파일도 쓰지 않는다.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from okstra_ctl import next_phase
+from okstra_ctl.final_report_paths import final_report_data_path
+from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
+
+
+class OptionComparisonError(ValueError):
+    """비교 자료를 만들 수 없는 기록."""
+
+
+def _rows(value: object) -> list[Mapping[str, Any]]:
+    if not isinstance(value, Sequence) or isinstance(value, (str, bytes)):
+        return []
+    return [row for row in value if isinstance(row, Mapping)]
+
+
+def _text(value: object) -> str:
+    return value.strip() if isinstance(value, str) else ""
+
+
+def _count(value: object) -> int:
+    return len(value) if isinstance(value, Sequence) and not isinstance(value, str) else 0
+
+
+def _option(
+    option: Mapping[str, Any], recommended_id: str
+) -> dict[str, Any]:
+    coverage = option.get("coverageSummary")
+    coverage = coverage if isinstance(coverage, Mapping) else {}
+    scores = _rows(option.get("criterionScores"))
+    return {
+        "id": _text(option.get("id")),
+        "name": _text(option.get("name")),
+        "recommended": _text(option.get("id")) == recommended_id,
+        "goal": _text(option.get("goal")),
+        "coreMechanism": _text(option.get("coreMechanism")),
+        # 발행 검증이 재계산 값과 같음을 보장한 기록값이다. 다시 계산하지 않는다.
+        "weightedScore": option.get("weightedScore"),
+        "scores": {_text(row.get("criterion")): row.get("score") for row in scores},
+        "scoreRationales": {
+            _text(row.get("criterion")): _text(row.get("rationale")) for row in scores
+        },
+        "coverage": {
+            "verdict": _text(coverage.get("coverageVerdict")),
+            "coveredCount": coverage.get("coveredCount"),
+            "totalCount": coverage.get("totalCount"),
+            "requirementIds": [
+                _text(row.get("requirementId"))
+                for row in _rows(option.get("requirementCoverage"))
+                if _text(row.get("requirementId"))
+            ],
+        },
+        "safetyBlockers": _count(option.get("safetyBlockers")),
+        "unresolvedFeasibilityFacts": _count(option.get("unresolvedFeasibilityFacts")),
+        "votes": {
+            _text(vote.get("worker")): {
+                "verdict": _text(vote.get("verdict")),
+                "rationale": _text(vote.get("rationale")),
+                "counterevidence": _text(vote.get("counterevidence")),
+            }
+            for vote in _rows(option.get("feasibilityVotes"))
+            if _text(vote.get("worker"))
+        },
+    }
+
+
+def build_comparison(report_data: Mapping[str, Any]) -> dict[str, Any]:
+    """선택 리포트 기록 → 비교 자료 사실 묶음."""
+    selection = report_data.get("implementationOptionSelection")
+    if not isinstance(selection, Mapping):
+        raise OptionComparisonError(
+            "report has no implementationOptionSelection block; "
+            "pass an implementation-option-selection report record"
+        )
+    recommended_id = _text(selection.get("recommendedOptionId"))
+    options = [
+        _option(row, recommended_id) for row in _rows(selection.get("rankedOptions"))
+    ]
+    if not options:
+        raise OptionComparisonError("report ranks no direction; there is nothing to compare")
+    # 투표 열 순서는 처음 등장한 순서다 — 방향마다 같은 분석자 집합이 투표한다.
+    workers: list[str] = []
+    for option in options:
+        for worker in option["votes"]:
+            if worker not in workers:
+                workers.append(worker)
+    narrative = selection.get("userNarrative")
+    narrative = narrative if isinstance(narrative, Mapping) else {}
+    return {
+        "mode": _text(selection.get("mode")),
+        "routing": _text(selection.get("routing")),
+        "recommendedOptionId": recommended_id,
+        "criteria": [
+            {"criterion": _text(row.get("criterion")), "weight": row.get("weight")}
+            for row in _rows(selection.get("evaluationCriteria"))
+        ],
+        "workers": workers,
+        "options": options,
+        "narrative": {
+            key: _text(block.get("text"))
+            for key, block in narrative.items()
+            if isinstance(block, Mapping) and _text(block.get("text"))
+        },
+        # "남은 절차" 문단의 근거. 다음 phase 포인터와 같은 문장이다.
+        "nextStep": next_phase.project(report_data)["rationale"],
+    }
+
+
+def _load(report: Path) -> Mapping[str, Any]:
+    data_path = final_report_data_path(report)
+    try:
+        data = load_owned_object(data_path, artifact="implementation option data")
+    except (OSError, JsonBoundaryError) as exc:
+        raise OptionComparisonError(f"cannot read report record {data_path}: {exc}") from exc
+    return data
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="okstra option-comparison",
+        description=(
+            "Print the comparison facts of an implementation-option-selection "
+            "report as JSON: criteria and weights, per-direction scores and "
+            "recorded weighted score, requirement coverage, blocker counts, "
+            "per-worker feasibility votes, the report narrative, and the next step."
+        ),
+    )
+    parser.add_argument(
+        "--report",
+        required=True,
+        help="final-report-implementation-option-selection-<seq>.data.json (a .md sibling is accepted)",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        payload = build_comparison(_load(Path(args.report)))
+    except OptionComparisonError as exc:
+        print(f"option-comparison: {exc}", file=sys.stderr)
+        return 2
+    json.dump(payload, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/runtime/python/okstra_ctl/path_hints.py

@@ -64,6 +64,7 @@ def compact_active_run_context(
         "run": {
             "stage": ctx.get("RUN_STAGE", ""),
             "fixRunCarry": ctx.get("FIX_RUN_CONTEXT", ""),
+            "hostSessionContract": ctx.get("HOST_SESSION_CONTRACT_PATH", ""),
         },
         "agentContract": dict(_mapping(payload.get("agentContract"))),
         "inputs": _compact_active_inputs(payload),
@@ -118,8 +119,13 @@ def hydrate_active_run_context(payload: Mapping[str, Any]) -> dict[str, Any]:
                     "IMPLEMENTATION_WORKER_PREAMBLE_PATH", ""
                 ),
                 "report-writer": ctx.get("REPORT_WRITER_PREAMBLE_PATH", ""),
+                "translator": ctx.get("TRANSLATOR_PREAMBLE_PATH", ""),
             },
             "workerErrorContractPath": ctx.get("WORKER_ERROR_CONTRACT_PATH", ""),
+            "hostSessionContractPath": (
+                str(_mapping(payload.get("run")).get("hostSessionContract", ""))
+                or ctx.get("HOST_SESSION_CONTRACT_PATH", "")
+            ),
         },
         "executorWorktree": dict(_mapping(payload.get("executorWorktree"))),
         "verificationTarget": dict(_mapping(payload.get("verificationTarget"))),
@@ -509,6 +515,9 @@ def _runtime_fields(paths: Mapping[str, Any]) -> dict[str, str]:
         "REPORT_WRITER_PREAMBLE_PATH": str(
             runtime_home / "templates" / "report-writer-prompt-preamble.md"
         ),
+        "TRANSLATOR_PREAMBLE_PATH": str(
+            runtime_home / "templates" / "translator-prompt-preamble.md"
+        ),
         "WORKER_ERROR_CONTRACT_PATH": str(
             runtime_home / "templates" / "worker-error-contract.md"
         ),

package/runtime/python/okstra_ctl/paths.py

@@ -647,6 +647,9 @@ def compute_run_paths(
         "REPORT_WRITER_PREAMBLE_PATH": str(
             runtime_home / "templates" / "report-writer-prompt-preamble.md"
         ),
+        "TRANSLATOR_PREAMBLE_PATH": str(
+            runtime_home / "templates" / "translator-prompt-preamble.md"
+        ),
         "WORKER_ERROR_CONTRACT_PATH": str(
             runtime_home / "templates" / "worker-error-contract.md"
         ),

package/runtime/python/okstra_ctl/profile_show.py

@@ -19,6 +19,7 @@ import sys
 from pathlib import Path
 
 from .paths import find_asset_root
+from .role_requirements import RoleProfileError, load_role_profile
 from .run import PrepareError, _expand_profile_includes
 
 _PROFILES_REL = ("prompts", "profiles")
@@ -82,9 +83,49 @@ def sidecar_bodies(root: Path, profile_text: str) -> list[str]:
 def render(root: Path, task_type: str, *, resolved: bool) -> str:
     path = profile_path(root, task_type)
     if not resolved:
+        # 계약상 이 출력은 디스크의 파일 그대로다. 역할 구조는 이제 `.json` 에
+        # 있으므로 `--resolved` 가 렌더한다.
         return path.read_text(encoding="utf-8")
     expanded = _expand_profile_includes(path)
-    return expanded + "".join(sidecar_bodies(root, expanded))
+    body = expanded + "".join(sidecar_bodies(root, expanded))
+    return body + _role_requirements_section(path)
+
+
+def _role_requirements_section(profile_path: Path) -> str:
+    """Render the profile's role structure from its contract.
+
+    The structure moved out of the Markdown into the `.json` sibling, so a
+    reader of `okstra profile show` would otherwise no longer see which roles
+    the phase runs — which is most of what the command is read for.
+    """
+    try:
+        profile = load_role_profile(profile_path)
+    except RoleProfileError as exc:
+        return f"\n## Role requirements\n\nunavailable: {exc}\n"
+    if not profile.roles:
+        return "\n## Role requirements\n\nThis phase runs a single lead and no workers.\n"
+    lines = [
+        "",
+        "## Role requirements",
+        "",
+        "| Role | Duty | Count (min/recommended/max) | Activation |",
+        "|---|---|---|---|",
+    ]
+    for requirement in profile.roles:
+        if requirement.dynamic:
+            sources = ", ".join(f"`{role}`" for role in requirement.source_role_ids)
+            counts = f"one per activated {sources} slot"
+            activation = requirement.activation
+        else:
+            counts = (
+                f"{requirement.min_count} / {requirement.recommended_count} / "
+                f"{requirement.max_count}"
+            )
+            activation = "static"
+        lines.append(
+            f"| `{requirement.role}` | `{requirement.duty}` | {counts} | {activation} |"
+        )
+    return "\n".join(lines) + "\n"
 
 
 def _write_stdout(text: str) -> None:

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

@@ -18,6 +18,8 @@ class HostManifest:
     native_provider_id: str
     required_executables: tuple[str, ...]
     relay_contract: Path
+    # 선언하지 않은 호스트는 None. 이 호스트 세션 안에서 도는 워커가 읽는 계약이다.
+    worker_session_contract: Path | None = None
 
 
 def discover_host_manifests(roots: Iterable[Path]) -> tuple[HostManifest, ...]:
@@ -54,7 +56,15 @@ def _read_manifest(manifest_path: Path) -> HostManifest:
     native_provider_id = _optional_id(raw, "nativeProviderId", manifest_path)
     required_executables = _string_tuple(raw, "requiredExecutables", manifest_path)
     relay_ref = _required_string(raw, "relayContract", manifest_path)
-    relay_contract = _resolve_relay_contract(manifest_path, relay_ref)
+    relay_contract = _resolve_adapter_file(manifest_path, relay_ref, "relay contract")
+    session_ref = raw.get("workerSessionContract")
+    if session_ref is not None and (not isinstance(session_ref, str) or not session_ref):
+        raise HostAdapterContractError(f"invalid host manifest: {manifest_path}")
+    worker_session_contract = (
+        _resolve_adapter_file(manifest_path, session_ref, "worker session contract")
+        if session_ref is not None
+        else None
+    )
     return HostManifest(
         path=manifest_path,
         host_id=host_id,
@@ -62,6 +72,7 @@ def _read_manifest(manifest_path: Path) -> HostManifest:
         native_provider_id=native_provider_id,
         required_executables=required_executables,
         relay_contract=relay_contract,
+        worker_session_contract=worker_session_contract,
     )
 
 
@@ -111,15 +122,12 @@ def _string_tuple(
     return tuple(value)
 
 
-def _resolve_relay_contract(manifest_path: Path, relay_ref: str) -> Path:
+def _resolve_adapter_file(manifest_path: Path, ref: str, label: str) -> Path:
+    """어댑터 디렉터리 안의 파일 하나를 해석한다. 밖을 가리키면 거절한다."""
     adapter_root = manifest_path.parent.resolve()
-    if Path(relay_ref).is_absolute():
-        raise HostAdapterContractError(
-            f"relay contract escapes adapter root: {relay_ref!r}"
-        )
-    relay_contract = (adapter_root / relay_ref).resolve()
-    if adapter_root not in relay_contract.parents or not relay_contract.is_file():
-        raise HostAdapterContractError(
-            f"relay contract escapes adapter root: {relay_ref!r}"
-        )
-    return relay_contract
+    if Path(ref).is_absolute():
+        raise HostAdapterContractError(f"{label} escapes adapter root: {ref!r}")
+    resolved = (adapter_root / ref).resolve()
+    if adapter_root not in resolved.parents or not resolved.is_file():
+        raise HostAdapterContractError(f"{label} escapes adapter root: {ref!r}")
+    return resolved

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

@@ -248,6 +248,15 @@ def _validated_descriptor(adapter: object, manifest: HostManifest) -> HostDescri
         raise HostAdapterContractError(
             f"relay contract mismatch for {manifest.host_id!r}"
         )
+    declared = (
+        Path(descriptor.worker_session_contract).resolve()
+        if descriptor.worker_session_contract
+        else None
+    )
+    if declared != manifest.worker_session_contract:
+        raise HostAdapterContractError(
+            f"worker session contract mismatch for {manifest.host_id!r}"
+        )
     return descriptor
 
 
@@ -286,6 +295,8 @@ def _copy_descriptor(raw: object, host_id: str) -> HostDescriptor:
             session_accounting=raw.session_accounting,
             has_claude_session=raw.has_claude_session,
             relay_contract=raw.relay_contract,
+            worker_session_contract=getattr(raw, "worker_session_contract", ""),
+            initial_prompt_delivery_mode=raw.initial_prompt_delivery_mode,
         )
     except (AttributeError, TypeError) as exc:
         raise HostAdapterContractError(