okstra 0.167.0 → 0.169.0

package/runtime/python/okstra_ctl/initial_prompt_materialization.py

@@ -11,6 +11,16 @@ from pathlib import Path
 from typing import Any, Callable, Literal, Mapping, Sequence
 
 from .final_report_paths import final_report_data_path
+from .agent_invocation import (
+    AgentInstruction,
+    AgentInstructionSource,
+    AgentInvocationError,
+    AgentInvocationRequest,
+    agent_model_assignment_from_payload,
+    compose_agent_prompt,
+    prepare_agent_invocation,
+    verify_agent_invocation,
+)
 from .path_hints import hydrate_active_run_context
 from .report_language import resolve_report_language
 from .worker_prompt_body import (
@@ -101,6 +111,30 @@ _CLARIFICATION_AUTHORITY_INTRO = (
 _CLARIFICATION_SOURCE_PREFIX = "Source:"
 _REQUIRED_PROMPT_RESOURCES_HEADING = "## Required prompt resources"
 _HTML_COMMENTS = re.compile(r"<!--.*?-->\n?", re.DOTALL)
+_AGENT_CONTRACT_KEYS = {
+    "schemaVersion",
+    "dutyRootPath",
+    "catalogDigest",
+    "invocationReservationRootPath",
+    "allowedAudiences",
+    "authorizedPaths",
+}
+_MODEL_ASSIGNMENT_KEYS = {
+    "provider",
+    "model",
+    "modelExecutionValue",
+    "runner",
+    "hostRuntime",
+    "hostModelValue",
+}
+_RUN_INVOCATION_PATH_KEYS = {
+    "runManifestPath",
+    "workerPromptsDirectoryPath",
+    "leadInstructionsPath",
+    "leadExecutionPromptPath",
+    "leadPromptMetadataPath",
+    "invocationReservationRootPath",
+}
 
 
 @dataclass(frozen=True)
@@ -198,6 +232,7 @@ def _load_materialization_context(
         )
     manifest_path = _resolve_input_path(project_root, request.run_manifest_path)
     manifest = _load_json_object(manifest_path, "run manifest")
+    _validate_invocation_manifest_authority(manifest)
     team_state = _load_referenced_json(project_root, manifest, "teamStatePath")
     active_context = hydrate_active_run_context(
         _load_referenced_json(
@@ -215,6 +250,39 @@ def _load_materialization_context(
     )
 
 
+def _validate_invocation_manifest_authority(
+    manifest: Mapping[str, Any],
+) -> None:
+    has_contract = "agentContract" in manifest
+    has_assignments = "invocationAssignments" in manifest
+    if not has_contract and not has_assignments:
+        return
+    contract = manifest.get("agentContract")
+    assignments = manifest.get("invocationAssignments")
+    complete = (
+        isinstance(contract, Mapping)
+        and set(contract) == _AGENT_CONTRACT_KEYS
+        and contract.get("schemaVersion") == 1
+        and isinstance(assignments, Mapping)
+        and bool(assignments)
+        and all(
+            isinstance(item, Mapping)
+            and set(item) == _MODEL_ASSIGNMENT_KEYS
+            for item in assignments.values()
+        )
+        and all(
+            isinstance(manifest.get(key), str)
+            and bool(manifest.get(key))
+            for key in _RUN_INVOCATION_PATH_KEYS
+        )
+    )
+    if not complete:
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            "new invocation manifest is incomplete",
+        )
+
+
 def _resolve_prompt_item(
     context: _MaterializationContext,
     worker: InitialPromptWorkerRequest,
@@ -312,12 +380,23 @@ def _render_prompt(
     context: _MaterializationContext,
     item: _PromptItem,
 ) -> str:
+    request = _agent_invocation_request(context, item)
+    if request is not None:
+        return compose_agent_prompt(request)
+    anchors, body = _render_prompt_parts(context, item)
+    return "\n".join([*anchors, *body]).rstrip() + "\n"
+
+
+def _render_prompt_parts(
+    context: _MaterializationContext,
+    item: _PromptItem,
+) -> tuple[list[str], list[str]]:
     worker = item.worker
     state = _worker_state(context.team_state, worker.worker_id)
     prompt_rel = _project_relative(context.project_root, item.final_path)
     result_rel, audit_source_rel = _result_paths(context, state, worker.worker_id)
     try:
-        lines = worker_prompt_headers(
+        anchors = worker_prompt_headers(
             project_root=context.project_root,
             prompt_rel=prompt_rel,
             result_rel=result_rel,
@@ -327,12 +406,12 @@ def _render_prompt(
             manifest=context.manifest,
             active_context=context.active_context,
         )
-        lines.append(
+        anchors.append(
             f"**Prompt Delivery Mode:** {context.request.delivery_mode.value}"
         )
-        lines.extend(_implementation_anchor_lines(context, item.plan))
-        lines.extend(_prompt_body(context, state, worker, item.plan))
-        lines.extend(_resource_lines(context, item))
+        anchors.extend(_implementation_anchor_lines(context, item.plan))
+        body = _prompt_body(context, state, worker, item.plan)
+        body.extend(_resource_lines(context, item))
     except InitialPromptMaterializationError:
         raise
     except Exception as exc:
@@ -340,7 +419,62 @@ def _render_prompt(
             "render_failed",
             f"cannot compose initial prompt for {worker.worker_id}: {exc}",
         ) from exc
-    return "\n".join(lines).rstrip() + "\n"
+    return anchors, body
+
+
+def _agent_invocation_request(
+    context: _MaterializationContext,
+    item: _PromptItem,
+) -> AgentInvocationRequest | None:
+    contract = context.manifest.get("agentContract")
+    if not isinstance(contract, Mapping):
+        return None
+    assignment_ref = f"initial/{item.worker.worker_id}"
+    assignments = context.manifest.get("invocationAssignments")
+    payload = assignments.get(assignment_ref) if isinstance(assignments, Mapping) else None
+    try:
+        assignment = agent_model_assignment_from_payload(payload)
+    except AgentInvocationError as exc:
+        raise InitialPromptMaterializationError(
+            "required_input_missing", str(exc)
+        ) from exc
+    if assignment.model_execution_value != item.worker.model:
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            f"requested model does not match {assignment_ref}",
+        )
+    anchors, body = _render_prompt_parts(context, item)
+    source_paths = (
+        AgentInstructionSource(
+            "project",
+            _project_relative(context.project_root, context.request.run_manifest_path),
+        ),
+        AgentInstructionSource(
+            "project", _required_string(context.manifest, "activeRunContextPath")
+        ),
+        AgentInstructionSource(
+            "project", _required_string(context.manifest, "teamStatePath")
+        ),
+    )
+    return AgentInvocationRequest(
+        invocation_id=f"initial-{item.worker.worker_id}",
+        worker_id=item.worker.worker_id,
+        audience=item.plan.duty_audience,
+        assignment_ref=assignment_ref,
+        purpose=None,
+        assignment=assignment,
+        instruction=AgentInstruction(
+            anchor_lines=tuple(anchors),
+            body="\n".join(body).rstrip() + "\n",
+            source_paths=source_paths,
+        ),
+        project_root=context.project_root,
+        run_manifest_path=context.request.run_manifest_path,
+        duty_root=context.project_root / _required_string(contract, "dutyRootPath"),
+        prompt_path=item.final_path,
+        metadata_path=item.final_path.with_name(item.final_path.name + ".meta.json"),
+        dispatch_kind="initial",
+    )
 
 
 def _prompt_body(
@@ -366,7 +500,6 @@ def _prompt_body(
         context.active_context,
         worker.worker_id,
         worker.model,
-        _worker_role(plan),
         plan,
     )
 
@@ -607,15 +740,30 @@ def _publish_or_reuse(
 ) -> _PublishedPrompt:
     if item.existed:
         return _published_prompt(item, existed=True)
-    temp_path = _required_temp_path(item)
+    invocation = _agent_invocation_request(context, item)
+    if invocation is None:
+        temp_path = _required_temp_path(item)
+        try:
+            os.link(temp_path, item.final_path)
+        except FileExistsError:
+            _validate_existing_prompt(context, item)
+            return _published_prompt(item, existed=True)
+        except OSError as exc:
+            raise InitialPromptMaterializationError(
+                "publication_failed",
+                f"cannot publish initial prompt {item.final_path}: {exc}",
+            ) from exc
+        return _published_prompt(item, existed=False)
     try:
-        os.link(temp_path, item.final_path)
-    except FileExistsError:
-        _validate_existing_prompt(context, item)
-        return _published_prompt(item, existed=True)
-    except OSError as exc:
+        prepare_agent_invocation(invocation)
+    except AgentInvocationError as exc:
+        reason: MaterializationReason = (
+            "existing_prompt_conflict"
+            if exc.reason == "existing_invocation_conflict"
+            else "publication_failed"
+        )
         raise InitialPromptMaterializationError(
-            "publication_failed",
+            reason,
             f"cannot publish initial prompt {item.final_path}: {exc}",
         ) from exc
     return _published_prompt(item, existed=False)
@@ -625,6 +773,7 @@ def _validate_existing_prompt(
     context: _MaterializationContext,
     item: _PromptItem,
 ) -> None:
+    expects_invocation = isinstance(context.manifest.get("agentContract"), Mapping)
     text = _require_readable_prompt(
         item.final_path,
         item.worker.worker_id,
@@ -636,6 +785,10 @@ def _validate_existing_prompt(
         item.worker.worker_id,
         "initial",
         item.final_path,
+        metadata_path=_metadata_path(item.final_path) if expects_invocation else None,
+        expected_duty_audience=(
+            item.plan.duty_audience if expects_invocation else None
+        ),
     )
     basic_errors = validate_initial_prompt_records(
         manifest=context.manifest,
@@ -653,6 +806,10 @@ def _validate_existing_prompt(
         item.final_path,
         expected_model=item.worker.model,
         expected_delivery_mode=context.request.delivery_mode.value,
+        metadata_path=_metadata_path(item.final_path) if expects_invocation else None,
+        expected_duty_audience=(
+            item.plan.duty_audience if expects_invocation else None
+        ),
     )
     expected_errors = validate_initial_prompt_records(
         manifest=context.manifest,
@@ -665,6 +822,23 @@ def _validate_existing_prompt(
             reason,
             "existing initial prompt metadata: " + "; ".join(expected_errors),
         )
+    invocation = _agent_invocation_request(context, item)
+    if invocation is not None:
+        errors = verify_agent_invocation(
+            invocation.metadata_path,
+            project_root=context.project_root,
+            expected_run_manifest_path=context.request.run_manifest_path,
+            expected_assignment=invocation.assignment,
+            expected_invocation_id=invocation.invocation_id,
+            expected_worker_id=invocation.worker_id,
+            expected_assignment_ref=invocation.assignment_ref,
+            expected_audience=invocation.audience,
+        )
+        if errors:
+            raise InitialPromptMaterializationError(
+                "existing_prompt_invalid",
+                "existing initial prompt invocation: " + "; ".join(errors),
+            )
 
 
 def _validate_existing_clarification_metadata(
@@ -854,12 +1028,20 @@ def _item_record(
     item: _PromptItem,
 ) -> PromptRecord:
     path = item.final_path if item.existed else _required_temp_path(item)
+    expects_invocation = (
+        item.existed
+        and isinstance(context.manifest.get("agentContract"), Mapping)
+    )
     return PromptRecord(
         item.worker.worker_id,
         "initial",
         path,
         expected_model=item.worker.model,
         expected_delivery_mode=context.request.delivery_mode.value,
+        metadata_path=_metadata_path(item.final_path) if expects_invocation else None,
+        expected_duty_audience=(
+            item.plan.duty_audience if expects_invocation else None
+        ),
     )
 
 
@@ -867,15 +1049,24 @@ def _published_record(
     context: _MaterializationContext,
     prompt: _PublishedPrompt,
 ) -> PromptRecord:
+    expects_invocation = isinstance(context.manifest.get("agentContract"), Mapping)
     return PromptRecord(
         prompt.worker.worker_id,
         "initial",
         prompt.path,
         expected_model=prompt.worker.model,
         expected_delivery_mode=context.request.delivery_mode.value,
+        metadata_path=_metadata_path(prompt.path) if expects_invocation else None,
+        expected_duty_audience=(
+            prompt.plan.duty_audience if expects_invocation else None
+        ),
     )
 
 
+def _metadata_path(prompt_path: Path) -> Path:
+    return prompt_path.with_name(prompt_path.name + ".meta.json")
+
+
 def _worker_prompt_path(
     context: _MaterializationContext,
     worker_id: str,
@@ -1094,14 +1285,6 @@ def _validate_worker_request(worker: InitialPromptWorkerRequest) -> None:
     )
 
 
-def _worker_role(plan: PromptPlan) -> str:
-    if plan.audience == "implementation-executor":
-        return "executor"
-    if plan.audience == "implementation-verifier":
-        return "verifier"
-    return "worker"
-
-
 def _existing_metadata_reason(
     errors: Sequence[str],
 ) -> MaterializationReason:
@@ -1164,7 +1347,15 @@ def _required_temp_path(item: _PromptItem) -> Path:
 
 
 def _project_relative(project_root: Path, path: Path) -> str:
-    return path.relative_to(project_root).as_posix()
+    # macOS commonly exposes the same temporary directory as both `/var/...`
+    # and `/private/var/...`; project-root resolution already canonicalizes the
+    # former. Resolve the candidate too so provenance does not reject an alias
+    # for the same directory. `strict=False` is required for a prompt that has
+    # not been published yet, while still resolving every existing parent and
+    # therefore preserving the symlink-escape check in `relative_to`.
+    return path.resolve(strict=False).relative_to(
+        project_root.resolve(strict=True)
+    ).as_posix()
 
 
 def _resolve_input_path(project_root: Path, path: Path) -> Path:

package/runtime/python/okstra_ctl/path_hints.py

@@ -60,6 +60,7 @@ def compact_active_run_context(
             "stage": ctx.get("RUN_STAGE", ""),
             "fixRunCarry": ctx.get("FIX_RUN_CONTEXT", ""),
         },
+        "agentContract": dict(_mapping(payload.get("agentContract"))),
         "inputs": _compact_active_inputs(payload),
         "workers": _compact_active_workers(payload),
         "executorWorktree": dict(_mapping(payload.get("executorWorktree"))),
@@ -97,6 +98,7 @@ def hydrate_active_run_context(payload: Mapping[str, Any]) -> dict[str, Any]:
         "task": _hydrate_active_task(payload, ctx),
         "workflow": dict(_mapping(payload.get("workflow"))),
         "run": _hydrate_active_run(payload, ctx),
+        "agentContract": dict(_mapping(payload.get("agentContract"))),
         "instructionSet": _hydrate_active_instruction_set(payload, ctx),
         "workers": _hydrate_active_workers(payload, ctx),
         "errorLogs": _hydrate_active_error_logs(ctx),
@@ -416,6 +418,12 @@ def _run_files(
         "run_context_file": run_manifests / f"run-context-{task_type_segment}-{sequences['manifests']}.json",
         "run_inputs_file": run_manifests / f"run-inputs-{task_type_segment}-{sequences['manifests']}.json",
         "run_prompt_snapshot": run_prompts / f"lead-execution-prompt{suffixes['prompts']}.md",
+        "duty_contract_root": run_prompts / f"duty-contracts{suffixes['prompts']}",
+        "lead_instructions": run_prompts / f"lead-instructions{suffixes['prompts']}.md",
+        "lead_prompt_metadata": (
+            run_prompts / f"lead-execution-prompt{suffixes['prompts']}.md.meta.json"
+        ),
+        "invocation_reservation_root": run_prompts / ".agent-invocations",
         "claude_worker_prompt": run_prompts / f"claude-worker-prompt{suffixes['prompts']}.md",
         "codex_worker_prompt": run_prompts / f"codex-worker-prompt{suffixes['prompts']}.md",
         "antigravity_worker_prompt": run_prompts / f"antigravity-worker-prompt{suffixes['prompts']}.md",
@@ -535,6 +543,10 @@ def _absolute_run_fields(paths: Mapping[str, Any]) -> dict[str, str]:
         "RUN_MANIFEST_PATH": str(paths["run_manifest_file"]),
         "RUN_CONTEXT_FILE": str(paths["run_context_file"]),
         "RUN_PROMPT_SNAPSHOT_FILE": str(paths["run_prompt_snapshot"]),
+        "DUTY_CONTRACT_ROOT": str(paths["duty_contract_root"]),
+        "LEAD_INSTRUCTIONS_PATH": str(paths["lead_instructions"]),
+        "LEAD_PROMPT_METADATA_PATH": str(paths["lead_prompt_metadata"]),
+        "INVOCATION_RESERVATION_ROOT": str(paths["invocation_reservation_root"]),
         "FINAL_REPORT_PATH": str(paths["final_report"]),
         "CONVERGENCE_STATE_PATH": str(paths["convergence_state"]),
         "FINAL_STATUS_PATH": str(paths["final_status"]),
@@ -569,6 +581,8 @@ def _filename_fields(paths: Mapping[str, Any]) -> dict[str, str]:
     return {
         "RUN_MANIFEST_FILENAME": Path(paths["run_manifest_file"]).name,
         "RUN_PROMPT_SNAPSHOT_FILENAME": Path(paths["run_prompt_snapshot"]).name,
+        "LEAD_INSTRUCTIONS_FILENAME": Path(paths["lead_instructions"]).name,
+        "LEAD_PROMPT_METADATA_FILENAME": Path(paths["lead_prompt_metadata"]).name,
         "FINAL_REPORT_FILENAME": Path(paths["final_report"]).name,
         "FINAL_STATUS_FILENAME": Path(paths["final_status"]).name,
         "CLAUDE_RESUME_COMMAND_FILENAME": Path(paths["claude_resume_command"]).name,
@@ -621,6 +635,18 @@ def _relative_file_fields(project_root: Path, paths: Mapping[str, Any]) -> dict[
         "RUN_CONTEXT_RELATIVE_PATH": _rel(project_root, paths["run_context_file"]),
         "RUN_INPUTS_RELATIVE_PATH": _rel(project_root, paths["run_inputs_file"]),
         "RUN_PROMPT_SNAPSHOT_RELATIVE_PATH": _rel(project_root, paths["run_prompt_snapshot"]),
+        "DUTY_CONTRACT_ROOT_RELATIVE_PATH": _rel(
+            project_root, paths["duty_contract_root"]
+        ),
+        "LEAD_INSTRUCTIONS_RELATIVE_PATH": _rel(
+            project_root, paths["lead_instructions"]
+        ),
+        "LEAD_PROMPT_METADATA_RELATIVE_PATH": _rel(
+            project_root, paths["lead_prompt_metadata"]
+        ),
+        "INVOCATION_RESERVATION_ROOT_RELATIVE_PATH": _rel(
+            project_root, paths["invocation_reservation_root"]
+        ),
         "CLAUDE_WORKER_PROMPT_RELATIVE_PATH": _rel(project_root, paths["claude_worker_prompt"]),
         "CODEX_WORKER_PROMPT_RELATIVE_PATH": _rel(project_root, paths["codex_worker_prompt"]),
         "ANTIGRAVITY_WORKER_PROMPT_RELATIVE_PATH": _rel(project_root, paths["antigravity_worker_prompt"]),

package/runtime/python/okstra_ctl/paths.py

@@ -524,6 +524,16 @@ def compute_run_paths(
 
     run_manifest_file = run_manifests / f"run-manifest{suffixes['manifests']}.json"
     run_prompt_snapshot = run_prompts / f"lead-execution-prompt{suffixes['prompts']}.md"
+    duty_contract_root = (
+        run_prompts / f"duty-contracts{suffixes['prompts']}"
+    )
+    lead_instructions = (
+        run_prompts / f"lead-instructions{suffixes['prompts']}.md"
+    )
+    lead_prompt_metadata = run_prompt_snapshot.with_name(
+        run_prompt_snapshot.name + ".meta.json"
+    )
+    invocation_reservation_root = run_prompts / ".agent-invocations"
     claude_worker_prompt = run_prompts / f"claude-worker-prompt{suffixes['prompts']}.md"
     codex_worker_prompt = run_prompts / f"codex-worker-prompt{suffixes['prompts']}.md"
     antigravity_worker_prompt = run_prompts / f"antigravity-worker-prompt{suffixes['prompts']}.md"
@@ -625,6 +635,10 @@ def compute_run_paths(
         "RUN_CARRY_PATH": str(run_carry),
         "RUN_MANIFEST_PATH": str(run_manifest_file),
         "RUN_PROMPT_SNAPSHOT_FILE": str(run_prompt_snapshot),
+        "DUTY_CONTRACT_ROOT": str(duty_contract_root),
+        "LEAD_INSTRUCTIONS_PATH": str(lead_instructions),
+        "LEAD_PROMPT_METADATA_PATH": str(lead_prompt_metadata),
+        "INVOCATION_RESERVATION_ROOT": str(invocation_reservation_root),
         "CLAUDE_WORKER_PROMPT_FILE": str(claude_worker_prompt),
         "CODEX_WORKER_PROMPT_FILE": str(codex_worker_prompt),
         "ANTIGRAVITY_WORKER_PROMPT_FILE": str(antigravity_worker_prompt),
@@ -652,6 +666,8 @@ def compute_run_paths(
         "RUN_VALIDATOR_PATH": str(run_validator_script),
         "RUN_MANIFEST_FILENAME": run_manifest_file.name,
         "RUN_PROMPT_SNAPSHOT_FILENAME": run_prompt_snapshot.name,
+        "LEAD_INSTRUCTIONS_FILENAME": lead_instructions.name,
+        "LEAD_PROMPT_METADATA_FILENAME": lead_prompt_metadata.name,
         "FINAL_REPORT_FILENAME": final_report.name,
         "FINAL_STATUS_FILENAME": final_status.name,
         "CLAUDE_RESUME_COMMAND_FILENAME": claude_resume_command.name,
@@ -688,6 +704,10 @@ def compute_run_paths(
         ("RUN_SESSIONS_RELATIVE_PATH", run_sessions),
         ("RUN_MANIFEST_RELATIVE_PATH", run_manifest_file),
         ("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", run_prompt_snapshot),
+        ("DUTY_CONTRACT_ROOT_RELATIVE_PATH", duty_contract_root),
+        ("LEAD_INSTRUCTIONS_RELATIVE_PATH", lead_instructions),
+        ("LEAD_PROMPT_METADATA_RELATIVE_PATH", lead_prompt_metadata),
+        ("INVOCATION_RESERVATION_ROOT_RELATIVE_PATH", invocation_reservation_root),
         ("CLAUDE_WORKER_PROMPT_RELATIVE_PATH", claude_worker_prompt),
         ("CODEX_WORKER_PROMPT_RELATIVE_PATH", codex_worker_prompt),
         ("ANTIGRAVITY_WORKER_PROMPT_RELATIVE_PATH", antigravity_worker_prompt),

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

@@ -1,6 +1,11 @@
 """Host-facing ports consumed by application use cases."""
 
 from .host import HostAdapter
+from .host_model import (
+    HostModelBindingError,
+    HostModelBindingPort,
+    HostModelBindingRequest,
+)
 from .interaction import InteractionPort
 from .lead_session import LeadSessionPort
 from .usage_accounting import UsageAccountingPort
@@ -8,6 +13,9 @@ from .worker_dispatch import WorkerDispatchPort
 
 __all__ = (
     "HostAdapter",
+    "HostModelBindingError",
+    "HostModelBindingPort",
+    "HostModelBindingRequest",
     "InteractionPort",
     "LeadSessionPort",
     "UsageAccountingPort",

package/runtime/python/okstra_ctl/ports/host.py

@@ -11,6 +11,7 @@ from ..domain.host import (
     HostSessionContext,
 )
 from .interaction import InteractionPort
+from .host_model import HostModelBindingPort
 from .lead_session import LeadSessionPort
 from .usage_accounting import UsageAccountingPort
 from .worker_dispatch import WorkerDispatchPort
@@ -25,6 +26,8 @@ class HostAdapter(Protocol):
 
     def interaction(self) -> InteractionPort: ...
 
+    def host_model(self) -> HostModelBindingPort: ...
+
     def lead_session(self) -> LeadSessionPort: ...
 
     def worker_dispatch(self) -> WorkerDispatchPort: ...

package/runtime/python/okstra_ctl/ports/host_model.py

@@ -0,0 +1,60 @@
+"""Host-owned binding from provider model values to native call arguments."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+
+class HostModelBindingError(ValueError):
+    """Raised when a host has no explicit native model mapping."""
+
+
+@dataclass(frozen=True)
+class HostModelBindingRequest:
+    host_runtime: str
+    provider: str
+    model: str
+    model_execution_value: str
+    runner: str
+
+
+class HostModelBindingPort(Protocol):
+    def resolve(self, request: HostModelBindingRequest) -> str | None: ...
+
+
+class FailClosedHostModelBindingPort:
+    def __init__(self, host_runtime: str) -> None:
+        self._host_runtime = host_runtime
+
+    def resolve(self, request: HostModelBindingRequest) -> str | None:
+        if request.runner == "cli-wrapper":
+            return None
+        raise HostModelBindingError(
+            "unsupported host model: "
+            f"host={self._host_runtime!r}, provider={request.provider!r}, "
+            f"model={request.model_execution_value!r}"
+        )
+
+
+class NativeExecutionValueHostModelBindingPort:
+    """Explicit policy for hosts whose native API accepts provider CLI values."""
+
+    def __init__(self, host_runtime: str, native_provider: str) -> None:
+        self._host_runtime = host_runtime
+        self._native_provider = native_provider
+
+    def resolve(self, request: HostModelBindingRequest) -> str | None:
+        if request.runner == "cli-wrapper":
+            return None
+        if (
+            request.runner != "native-session"
+            or request.host_runtime != self._host_runtime
+            or request.provider != self._native_provider
+            or not request.model_execution_value.strip()
+        ):
+            raise HostModelBindingError(
+                "unsupported host model: "
+                f"host={request.host_runtime!r}, provider={request.provider!r}, "
+                f"model={request.model_execution_value!r}"
+            )
+        return request.model_execution_value

package/runtime/python/okstra_ctl/pr_template.py

@@ -6,8 +6,8 @@ release-handoff 단계에서 lead 가 PR 본문을 작성할 때 사용하는
     1. per-run override (okstra-run Step 6 에서 입력)
     2. project: <project_root>/.okstra/project.json 의 ``prTemplatePath``
     3. global:  ~/.okstra/config.json 의 ``prTemplatePath``
-    4. default: ``$OKSTRA_HOME/templates/pr/pr-body.template.md`` (구버전
-       ``~/.claude/skills/...`` 후보는 backward-compat 로 유지)
+    4. default: ``$OKSTRA_SKILLS_DIR/okstra-run/templates/pr-body.template.md``
+       (env 가 설정된 경우에만) → ``$OKSTRA_HOME/templates/pr/pr-body.template.md``
 
 경로는 절대경로 또는 ``~`` 시작 경로를 권장한다. 상대경로일 경우 project
 스코프는 ``project_root`` 기준, override 는 호출자 cwd 기준으로 해석한다.
@@ -41,10 +41,7 @@ def _default_template_candidates() -> list[Path]:
     env_dir = os.environ.get("OKSTRA_SKILLS_DIR", "").strip()
     if env_dir:
         out.append(Path(env_dir) / "okstra-run" / "templates" / _DEFAULT_FILENAME)
-    out.append(okstra_home() / "templates" / "prd" / _DEFAULT_FILENAME)
-    out.append(
-        Path.home() / ".claude" / "skills" / "okstra-run" / "templates" / _DEFAULT_FILENAME
-    )
+    out.append(okstra_home() / "templates" / "pr" / _DEFAULT_FILENAME)
     return out
 
 

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

@@ -26,12 +26,14 @@ _ADAPTER_METHODS = (
     "detect",
     "probe",
     "interaction",
+    "host_model",
     "lead_session",
     "worker_dispatch",
     "usage_accounting",
 )
 _PORT_METHODS = {
     "interaction": ("plan",),
+    "host_model": ("resolve",),
     "lead_session": ("build_start", "build_resume"),
     "worker_dispatch": ("build_plan",),
     "usage_accounting": ("collect",),
@@ -52,6 +54,9 @@ class _RegisteredHostAdapter:
     def interaction(self):
         return self._adapter.interaction()
 
+    def host_model(self):
+        return self._adapter.host_model()
+
     def lead_session(self):
         return self._adapter.lead_session()