okstra 0.179.2 → 0.183.2

package/runtime/prompts/profiles/requirements-discovery.md

@@ -4,7 +4,7 @@
 roles:
   - role: analyser
     min: 2
-    recommended: 2
+    recommended: 3
     max: 5
     duty: discovery-worker
   - role: critic

package/runtime/prompts/wizard/prompts.ko.json

@@ -623,7 +623,6 @@
     "static_role": "  static-role   : {role}#{ordinal} / {model}",
     "dynamic_role": "  dynamic-role  : {role} / reuse selected participant model",
     "workers_implementation_default": "  workers       : (프로필 기본 — executor + verifier 2 + report-writer)",
-    "critic_shares_analyser_provider": "                  ⚠ critic provider 가 분석 워커 `{worker}` 와 같습니다 — gap 검증에서 그 워커는 투표할 수 없어 유효 투표자가 {remaining}명으로 줍니다",
     "base_ref_stage_isolated": "  base-ref      : (stage 격리 — 의존 stage 기준으로 run 준비 시점에 자동 해소)",
     "base_ref_reuse_task_dir": "  base-ref      : (기존 `{task_key}` 디렉터리 재사용 — 최초 base 유지)",
     "worktree_new": "  worktree      : 새 브랜치 `{branch}` (base-ref `{base_ref}`) → `{path}`",

package/runtime/python/okstra_ctl/adapters/hosts/capability_adapter.py

@@ -1,8 +1,10 @@
 """Capability-based strategy shared by bundled host adapters."""
 from __future__ import annotations
 
+import json
 from collections.abc import Callable, Mapping
 from dataclasses import dataclass
+from pathlib import Path
 
 from okstra_ctl.adapters.dispatch import default_worker_dispatch_port
 from okstra_ctl.domain.host import (
@@ -57,27 +59,52 @@ INTERACTION_FUNCTIONS = PLAIN_TEXT_FUNCTIONS | frozenset({
     "native_multi_select",
     "native_question_group",
 })
-_NATIVE_QUESTION_LIMIT = 4
-_NATIVE_OPTION_RANGE = range(2, 5)
+_RELAY_HEADING = "## Wizard interaction relay"
 
 
-def _native_options_fit(prompt: WizardPrompt) -> bool:
-    labels = tuple(option.label for option in prompt.options)
-    return (
-        len(labels) in _NATIVE_OPTION_RANGE
-        and len(set(labels)) == len(labels)
-        and (not prompt.multi or all(", " not in label for label in labels))
-    )
-
-
-def _native_group_fits(prompt: WizardPrompt) -> bool:
-    return (
-        1 <= len(prompt.questions) <= _NATIVE_QUESTION_LIMIT
-        and all(_native_options_fit(question) for question in prompt.questions)
+@dataclass(frozen=True)
+class NativePickerLimits:
+    """How many questions and options a host's native picker can show.
+
+    Counts that miss the range keep every option and fall back to numbered
+    text. The defaults are Claude Code's AskUserQuestion shape; a host that
+    can show more must declare that in its relay `nativeLimits`.
+    """
+
+    min_options: int = 2
+    max_options: int = 4
+    max_questions: int = 4
+
+    def option_count_fits(self, count: int) -> bool:
+        return self.min_options <= count <= self.max_options
+
+
+def wizard_relay_contract(path: Path) -> dict[str, object]:
+    """The JSON object under `## Wizard interaction relay` in a host relay."""
+    body = path.read_text(encoding="utf-8")
+    section = body.split(_RELAY_HEADING, 1)[1]
+    encoded = section.split("```json\n", 1)[1].split("\n```", 1)[0]
+    payload = json.loads(encoded)
+    if not isinstance(payload, dict):
+        raise ValueError(f"wizard relay in {path} is not a JSON object")
+    return payload
+
+
+def native_limits_from_relay(contract: Mapping[str, object]) -> NativePickerLimits:
+    raw = contract.get("nativeLimits")
+    if not isinstance(raw, Mapping):
+        return NativePickerLimits()
+    return NativePickerLimits(
+        min_options=int(raw.get("minOptions", 2)),
+        max_options=int(raw.get("maxOptions", 4)),
+        max_questions=int(raw.get("maxQuestions", 4)),
     )
 
 
 class CapabilityInteractionPort:
+    def __init__(self, *, limits: NativePickerLimits | None = None) -> None:
+        self._limits = limits or NativePickerLimits()
+
     def plan(
         self,
         prompt: WizardPrompt,
@@ -87,7 +114,7 @@ class CapabilityInteractionPort:
         if prompt.kind == "pick_group":
             if (
                 "native_question_group" in functions
-                and _native_group_fits(prompt)
+                and self._native_group_fits(prompt, functions)
             ):
                 return InteractionPlan("native-group", AnswerProtocol("group-json"))
             return InteractionPlan(
@@ -96,7 +123,7 @@ class CapabilityInteractionPort:
             )
         if prompt.kind != "pick":
             return InteractionPlan("plain-text", AnswerProtocol("exact-value"))
-        native_options_fit = _native_options_fit(prompt)
+        native_options_fit = self._native_options_fit(prompt)
         if (
             prompt.multi
             and "native_multi_select" in functions
@@ -115,11 +142,36 @@ class CapabilityInteractionPort:
         kind = "numbered-multi" if prompt.multi else "numbered-single"
         return InteractionPlan(kind, AnswerProtocol("numbered", multi=prompt.multi))
 
+    def _native_options_fit(self, prompt: WizardPrompt) -> bool:
+        labels = tuple(option.label for option in prompt.options)
+        return (
+            self._limits.option_count_fits(len(labels))
+            and len(set(labels)) == len(labels)
+            and (not prompt.multi or all(", " not in label for label in labels))
+        )
+
+    def _native_group_fits(
+        self, prompt: WizardPrompt, functions: frozenset[str]
+    ) -> bool:
+        if any(question.multi for question in prompt.questions) and (
+            "native_multi_select" not in functions
+        ):
+            return False
+        return (
+            1 <= len(prompt.questions) <= self._limits.max_questions
+            and all(self._native_options_fit(question) for question in prompt.questions)
+        )
+
 
 def numbered_interaction_port() -> CapabilityInteractionPort:
     return CapabilityInteractionPort()
 
 
+def relay_interaction_port(relay_path: str | Path) -> CapabilityInteractionPort:
+    contract = wizard_relay_contract(Path(relay_path))
+    return CapabilityInteractionPort(limits=native_limits_from_relay(contract))
+
+
 class ProviderLeadSessionPort:
     def __init__(
         self,

package/runtime/python/okstra_ctl/adapters/hosts/claude-code/adapter.py

@@ -12,7 +12,7 @@ from okstra_ctl.adapters.hosts.capability_adapter import (
     INTERACTION_FUNCTIONS,
     PENDING_HOST_PORT,
     CapabilityHostAdapter,
-    numbered_interaction_port,
+    relay_interaction_port,
 )
 from okstra_ctl.domain.host import HostClaim, HostDescriptor, HostResolutionContext
 from okstra_ctl.domain.provider import HostModelBinding
@@ -21,6 +21,11 @@ from okstra_ctl.ports.host_model import (
     HostModelBindingRequest,
 )
 from okstra_ctl.registry.provider_registry import ProviderRegistry
+from okstra_ctl.json_boundary import (
+    JsonBoundaryError,
+    external_claude_global_json_source,
+    load_external_json,
+)
 
 
 DESCRIPTOR = HostDescriptor(
@@ -108,7 +113,11 @@ def _workspace_trust_checks(context) -> tuple[dict[str, object], ...]:
     if not (project_root / ".claude" / "settings.local.json").exists():
         return ({"id": "workspace-trust", "status": "not-applicable"},)
     try:
-        state = json.loads((home_dir / ".claude.json").read_text(encoding="utf-8"))
+        # 외부 입력: Claude Code가 소유하는 사용자 workspace trust 상태다.
+        state = load_external_json(
+            external_claude_global_json_source(home_dir / ".claude.json", home_dir),
+            artifact="Claude Code configuration",
+        )
         projects = state.get("projects") if isinstance(state, dict) else None
         if not isinstance(projects, dict):
             return _workspace_trust_unavailable()
@@ -124,7 +133,7 @@ def _workspace_trust_checks(context) -> tuple[dict[str, object], ...]:
         if accepted is False or accepted is None:
             return _workspace_trust_required()
         return _workspace_trust_unavailable()
-    except (OSError, json.JSONDecodeError):
+    except JsonBoundaryError:
         return _workspace_trust_unavailable()
 
 
@@ -160,7 +169,7 @@ def create_adapter(
         interaction_port=(
             interaction_port
             if interaction_port is not None
-            else numbered_interaction_port()
+            else relay_interaction_port(DESCRIPTOR.relay_contract)
         ),
         lead_session_port=lead_session_port,
         worker_dispatch_port=worker_dispatch_port,

package/runtime/python/okstra_ctl/adapters/hosts/claude-code/relay.md

@@ -32,6 +32,11 @@ Read this contract when `okstra preflight` returns this file as `runtimeReadines
     "native_multi_select",
     "native_question_group"
   ],
+  "nativeLimits": {
+    "minOptions": 2,
+    "maxOptions": 4,
+    "maxQuestions": 4
+  },
   "interactions": {
     "native-single": {
       "function": "AskUserQuestion",
@@ -124,7 +129,7 @@ Read this contract when `okstra preflight` returns this file as `runtimeReadines
 }
 ```
 
-For `AskUserQuestion`, map each wizard option to the tool's `{label, description}` input without removing, shortening, or reordering entries. Look up each answer by the exact rendered `question` string sent to the tool, including the progress suffix; the `answers` keys are question text, not positions or headers. A single-select answer is the selected label. A multi-select answer is one string whose selected labels are joined with `, `. Match those labels back to the complete original option list, emit their `value` fields in original option order, and join the values with `,` for the wizard. Native plans are emitted only for one to four questions whose option labels are unique and whose complete option lists each contain two to four entries; other prompts use the text mapping so no option is dropped. For a group, key the compact JSON object by the corresponding `questions[].step`; a multi-select question stores its ordered value CSV as one string, not a JSON array. Never use the display header as an answer key. The `Q1`…`Q4` headers only satisfy the host tool's short-header input and carry no domain meaning.
+For `AskUserQuestion`, map each wizard option to the tool's `{label, description}` input without removing, shortening, or reordering entries. Look up each answer by the exact rendered `question` string sent to the tool, including the progress suffix; the `answers` keys are question text, not positions or headers. A single-select answer is the selected label. A multi-select answer is one string whose selected labels are joined with `, `. Match those labels back to the complete original option list, emit their `value` fields in original option order, and join the values with `,` for the wizard. Native plans are emitted only when the prompt fits `nativeLimits` (unique option labels, two to four options, one to four questions); other prompts use the text mapping so no option is dropped. For a group, key the compact JSON object by the corresponding `questions[].step`; a multi-select question stores its ordered value CSV as one string, not a JSON array. Never use the display header as an answer key. The `Q1`…`Q4` headers only satisfy the host tool's short-header input and carry no domain meaning.
 
 For a `host-text` mapping, render each numbered item as its option label followed by its description verbatim; preserve every item and its order. The next user message is the raw answer. Do not translate numbers, CSV members, labels, or values before `okstra wizard step`. A sequential group wraps each raw reply in one compact JSON object keyed by `questions[].step`; the wizard owns normalization.
 
@@ -158,7 +163,8 @@ For a `host-text` mapping, render each numbered item as its option label followe
 - CLI-wrapper assignments never enter the Agent layer. `okstra worker-dispatch` validates the metadata and passes `modelExecutionValue` to the registered provider script.
 - Missing or unsupported family-token mapping is a pre-dispatch contract failure. Never inherit the lead model, choose a nearby alias, or switch provider silently.
 - Every analysis dispatch sets `name: "<workerId>-worker"`; convergence retries append `-reverify-r<N>`, implementation uses the functional `-executor` / `-verifier` suffix, and report writing uses `report-writer`. These values are retained as `agentName` in session JSONL for usage attribution.
-- Every CLI-worker prompt includes `**Pane role:** <functional-role>` so the entrypoint's optional fifth argument carries the dispatched role. That argument selects the dispatch's idle budget — `executor` and `verifier` run silent build+test suites and get 1500s, every other role 600s — and is recorded in the run's status sidecar. Omitting it defaults to `worker`, i.e. the short budget, which reaps a healthy build mid-suite.
+- A CLI worker's role reaches the entrypoint from the invocation's duty, NOT from the prompt text. `WorkerJob.wrapper_role` resolves `role_for_duty(dutyId)` and passes the canonical role in the role positional; the entrypoint checks it against the same derivation in the invocation metadata and refuses a mismatch. Do not add, edit, or rely on a `**Pane role:**` line to change what a dispatch runs as — the prompt body carries that header for the initial analysis audiences only, and it selects nothing.
+- The role decides the dispatch's idle budget, and `worker-dispatch` leaves the budget positional EMPTY so it can: an empty slot makes the entrypoint read the role's own budget (`domain/worker_role.role_spec` — `implementer` and `verifier` run silent build+test suites and get 1500s, every other role 600s). Passing an explicit `--idle-timeout-seconds` overrides that for the whole dispatch, so pass one only for a run-specific reason; filling the slot with a blanket default is what made the role budgets unreachable and reaped healthy workers mid-suite.
 - The host may supply transport metadata for native calls, but acceptance records only the verified invocation specification link. Record `enforcementMode=host-native-spec-link-gate`, `promptPath`, and `metadataPath`; do not claim the host-delivered bytes were observed.
 - A retry keeps the same Agent `name`. When logging a twice-failed CLI-wrapper attempt, reference both attempts' `bash_ids` and prompt-history paths.
 - An internally detected contract violation without a specific worker uses `--agent "claude-lead"` in the error-log event.

package/runtime/python/okstra_ctl/adapters/hosts/codex/adapter.py

@@ -12,7 +12,7 @@ from okstra_ctl.adapters.hosts.capability_adapter import (
     PENDING_HOST_PORT,
     CapabilityHostAdapter,
     no_automatic_claim,
-    numbered_interaction_port,
+    relay_interaction_port,
 )
 from okstra_ctl.domain.host import HostDescriptor
 from okstra_ctl.ports.host_model import NativeExecutionValueHostModelBindingPort
@@ -73,7 +73,7 @@ def create_adapter(
         interaction_port=(
             interaction_port
             if interaction_port is not None
-            else numbered_interaction_port()
+            else relay_interaction_port(DESCRIPTOR.relay_contract)
         ),
         lead_session_port=lead_session_port,
         worker_dispatch_port=worker_dispatch_port,

package/runtime/python/okstra_ctl/adapters/hosts/codex/relay.md

@@ -10,7 +10,7 @@ This adapter maps the neutral Okstra lead operations to the Codex artifact-first
 |---|---|
 | `runtime` | `codex` |
 | `leadRoleLabel` | `Codex lead` |
-| `userPromptMode` | `host-text` |
+| `userPromptMode` | `native-question` |
 | `workerDispatchBackend` | `mixed` |
 | `initialPromptDeliveryMode` | `eager-include` |
 | `sessionAccounting` | `artifact-only` |
@@ -20,14 +20,57 @@ This adapter maps the neutral Okstra lead operations to the Codex artifact-first
 
 ## Wizard interaction relay
 
-Read this contract when `okstra preflight` returns this file as `runtimeReadiness.relayContract`. The JSON is the complete interaction mapping for this host. This relay exposes only text input; do not invent a native picker function.
+Read this contract when `okstra preflight` returns this file as `runtimeReadiness.relayContract`. The JSON is the complete interaction mapping for this host. `semanticFunctions` is an allowlist: the skill may declare a function only when both this list and the live harness expose it. Codex `request_user_input` is single-select only (2–3 mutually exclusive choices, 1–3 questions); it has no native multi-select.
 
 ```json
 {
   "schemaVersion": 1,
   "runtime": "codex",
-  "semanticFunctions": ["plain_text_input"],
+  "semanticFunctions": [
+    "plain_text_input",
+    "native_single_select",
+    "native_question_group"
+  ],
+  "nativeLimits": {
+    "minOptions": 2,
+    "maxOptions": 3,
+    "maxQuestions": 3
+  },
   "interactions": {
+    "native-single": {
+      "function": "request_user_input",
+      "input": {
+        "callCount": 1,
+        "questions": "one",
+        "id": "prompt.step",
+        "header": "Q1",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-label-description"
+      },
+      "response": {
+        "envelope": "answers",
+        "key": "question-id",
+        "selection": "answers-array",
+        "submit": "matching-option-value"
+      }
+    },
+    "native-group": {
+      "function": "request_user_input",
+      "input": {
+        "callCount": 1,
+        "questions": "all-in-original-order",
+        "id": "questions[].step",
+        "header": "Q<one-based-question-position>",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-label-description"
+      },
+      "response": {
+        "envelope": "answers",
+        "key": "question-id",
+        "selection": "answers-array",
+        "submit": "compact-step-json-values"
+      }
+    },
     "numbered-single": {
       "function": "host-text",
       "input": {
@@ -67,7 +110,9 @@ Read this contract when `okstra preflight` returns this file as `runtimeReadines
 }
 ```
 
-Render every numbered item as its option label followed by its description verbatim, preserving every item and its original order. The next user message is the raw answer: do not translate a number such as `1`, a CSV reply such as `1, 3`, an option label, or an option value before `okstra wizard step`. For `sequential-group`, collect one raw reply per question in order and build one compact JSON object keyed by the corresponding `questions[].step`; the wizard owns all normalization.
+For `request_user_input`, send one to three questions. Each question carries `id` (`prompt.step` or `questions[].step`), a header of at most 12 characters (`Q1`…`Q3`), the rendered question text including the progress suffix, and every wizard option as `{label, description}` in original order — the tool has no option `value` field. Do not include an `Other` option; the client adds a free-form row. Native plans are emitted only when the prompt fits `nativeLimits` (unique labels, two or three options, one to three questions) and no grouped question is multi-select. Other prompts use the text mapping so no option is dropped. Look up each answer by question `id`. The selected strings are in `answers[id].answers`. Match those strings to option labels, emit their `value` fields in original option order, and join with `,` when more than one is present. If the typed Other text matches no label, submit it unchanged.
+
+For a `host-text` mapping, render each numbered item as its option label followed by its description verbatim; preserve every item and its order. The next user message is the raw answer: do not translate a number such as `1`, a CSV reply such as `1, 3`, an option label, or an option value before `okstra wizard step`. For `sequential-group`, collect one raw reply per question in order and build one compact JSON object keyed by the corresponding `questions[].step`; the wizard owns all normalization.
 
 
 ## Semantic operation mapping
@@ -76,7 +121,7 @@ Render every numbered item as its option label followed by its description verba
 |---|---|
 | `read_artifacts` | Read the manifest-provided paths through the current host's file interface. |
 | `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
-| `prompt_user` | Ask through the host text/question interface and stop at approval gates until an explicit answer arrives. |
+| `prompt_user` | Use `request_user_input` for approvals and clarifications that fit two or three options; otherwise ask through host text and stop until an explicit answer arrives. |
 | `dispatch_worker` | Verify each materialized invocation first. Dispatch `runner=native-session` with the current Codex host's primitive, the returned `promptPath`, and `hostModelValue`. Pass `runner=cli-wrapper` assignments to `okstra worker-dispatch --project-root <root> --run-manifest <path> --workers <ids>`; use `--dry-run` first when required. **Not in a cmux run:** when `terminalBackend` is `cmux-pane`, the cmux adapter overrides this row. |
 | `await_workers` | Await native host workers through the host primitive and CLI workers through synchronous dispatch, then verify team-state terminal records and Result Paths for both. |
 | `redispatch_worker` | Materialize and verify a fresh invocation, then start a fresh native worker or `okstra worker-dispatch` attempt according to the persisted runner. |

package/runtime/python/okstra_ctl/adapters/hosts/external/relay.md

@@ -91,7 +91,7 @@ Render every numbered item as its option label followed by its description verba
 - Worker completion is valid only from `workerDispatches[]`, terminal status sidecars, and required Result Paths. Pane creation alone is not completion.
 - Reverify uses a fresh jobs file at `runs/<task-type>/state/reverify-jobs-r<N>-<task-type>-<seq>.json`, sets `dispatchKind: "reverify-r<N>"`, and dispatches with `okstra team dispatch --project-root <root> --run-manifest <path> --dispatch-kind reverify-r<N> --jobs-file <jobs-file>`.
 - Report-writer uses a fresh one-job jobs file with `dispatchKind: "report-writer"` and the same schema, then dispatches through `okstra team dispatch --project-root <root> --run-manifest <path> --jobs-file <jobs-file>`.
-- Every reverify or report-writer jobs file carries `workerId`, `provider`, `role`, `modelExecutionValue`, `promptPath`, `promptMetadataPath`, `invocationId`, `assignmentRef`, `audience`, the five prompt digests, `resultPath`, `workerResultPath`, and `completionPaths`. `worker-dispatch` verifies these fields before launching the provider process. For reverify, set `role` to `worker-reverify-r<N>`. The report-writer completion paths include both data.json and the worker-results audit file.
+- Every reverify or report-writer jobs file carries `workerId`, `provider`, `role`, `modelExecutionValue`, `promptPath`, `promptMetadataPath`, `invocationId`, `assignmentRef`, `audience`, the five prompt digests, `resultPath`, `workerResultPath`, and `completionPaths`. `worker-dispatch` verifies these fields before launching the provider process. For reverify, set `role` to `worker-reverify-r<N>`. The report-writer completion paths include its narrative Markdown, worker-result pointer, and audit sidecar; Phase 7 later assembles `data.json`.
 - After either dispatch, run `okstra team await --project-root <root> --run-manifest <path>` before evaluating terminal status or completion paths.
 
 ## Completion, cleanup, and resume

package/runtime/python/okstra_ctl/adapters/hosts/grok/adapter.py

@@ -11,7 +11,7 @@ from okstra_ctl.adapters.hosts.capability_adapter import (
     PENDING_HOST_PORT,
     CapabilityHostAdapter,
     no_automatic_claim,
-    numbered_interaction_port,
+    relay_interaction_port,
 )
 from okstra_ctl.domain.host import HostDescriptor
 from okstra_ctl.ports.host_model import NativeExecutionValueHostModelBindingPort
@@ -54,7 +54,7 @@ def create_adapter(
         interaction_port=(
             interaction_port
             if interaction_port is not None
-            else numbered_interaction_port()
+            else relay_interaction_port(DESCRIPTOR.relay_contract)
         ),
         lead_session_port=lead_session_port,
         worker_dispatch_port=worker_dispatch_port,

package/runtime/python/okstra_ctl/adapters/hosts/grok/relay.md

@@ -10,7 +10,7 @@ This adapter maps neutral Okstra lead operations to the Grok CLI. Read it only w
 |---|---|
 | `runtime` | `grok` |
 | `leadRoleLabel` | `Grok lead` |
-| `userPromptMode` | `host-text` |
+| `userPromptMode` | `native-question` |
 | `workerDispatchBackend` | `mixed` |
 | `initialPromptDeliveryMode` | `eager-include` |
 | `sessionAccounting` | `artifact-only` |
@@ -20,14 +20,73 @@ This adapter maps neutral Okstra lead operations to the Grok CLI. Read it only w
 
 ## Wizard interaction relay
 
-Read this contract when `okstra preflight` returns this file as `runtimeReadiness.relayContract`. The JSON is the complete interaction mapping for this host. This relay exposes only text input; do not invent a native picker function.
+Read this contract when `okstra preflight` returns this file as `runtimeReadiness.relayContract`. The JSON is the complete interaction mapping for this host. `semanticFunctions` is an allowlist: the skill may declare a function only when both this list and the live harness expose it.
 
 ```json
 {
   "schemaVersion": 1,
   "runtime": "grok",
-  "semanticFunctions": ["plain_text_input"],
+  "semanticFunctions": [
+    "plain_text_input",
+    "native_single_select",
+    "native_multi_select",
+    "native_question_group"
+  ],
+  "nativeLimits": {
+    "minOptions": 2,
+    "maxOptions": 15,
+    "maxQuestions": 8
+  },
   "interactions": {
+    "native-single": {
+      "function": "ask_user_question",
+      "input": {
+        "callCount": 1,
+        "questions": "one",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-label-description",
+        "multiSelect": false
+      },
+      "response": {
+        "envelope": "answers",
+        "key": "rendered-question-text",
+        "selection": "selected-label",
+        "submit": "matching-option-value"
+      }
+    },
+    "native-multi": {
+      "function": "ask_user_question",
+      "input": {
+        "callCount": 1,
+        "questions": "one",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-label-description",
+        "multiSelect": true
+      },
+      "response": {
+        "envelope": "answers",
+        "key": "rendered-question-text",
+        "selection": "selected-labels-joined-comma-space",
+        "submit": "csv-matching-option-values-in-option-order"
+      }
+    },
+    "native-group": {
+      "function": "ask_user_question",
+      "input": {
+        "callCount": 1,
+        "questions": "all-in-original-order",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-label-description",
+        "multiSelect": "questions[].multi"
+      },
+      "response": {
+        "envelope": "answers",
+        "key": "rendered-question-text",
+        "selection": "selected-label-or-labels-joined-comma-space",
+        "multiValue": "csv-matching-option-values-in-option-order",
+        "submit": "compact-step-json-values"
+      }
+    },
     "numbered-single": {
       "function": "host-text",
       "input": {
@@ -67,7 +126,9 @@ Read this contract when `okstra preflight` returns this file as `runtimeReadines
 }
 ```
 
-Render every numbered item as its option label followed by its description verbatim, preserving every item and its original order. Submit the next user message unchanged. For `sequential-group`, collect one raw reply per question in order and build one compact JSON object keyed by the corresponding `questions[].step`.
+For `ask_user_question`, map each wizard option to the tool's `{label, description}` input without removing, shortening, or reordering entries. Do not send `preview`. Look up each answer by the exact rendered `question` string sent to the tool, including the progress suffix. A single-select answer is the selected label. A multi-select answer is one string whose selected labels are joined with `, `. Match those labels back to the complete original option list, emit their `value` fields in original option order, and join the values with `,` for the wizard. Native plans are emitted only when the prompt fits `nativeLimits` (unique option labels, two to fifteen options, one to eight questions); other prompts use the text mapping so no option is dropped. The host adds a free-text row on every question. Do not drop a wizard option to make room for it. If the user types in that row and the text matches no option label, submit the typed text unchanged. For a group, key the compact JSON object by the corresponding `questions[].step`; a multi-select question stores its ordered value CSV as one string, not a JSON array.
+
+For a `host-text` mapping, render each numbered item as its option label followed by its description verbatim; preserve every item and its order. The next user message is the raw answer. Do not translate numbers, CSV members, labels, or values before `okstra wizard step`. A sequential group wraps each raw reply in one compact JSON object keyed by `questions[].step`; the wizard owns normalization.
 
 ## Semantic operation mapping
 
@@ -75,7 +136,7 @@ Render every numbered item as its option label followed by its description verba
 |---|---|
 | `read_artifacts` | Read the manifest-provided paths through the current Grok host file interface. |
 | `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
-| `prompt_user` | Ask through the current host text interface and wait for an explicit answer. |
+| `prompt_user` | Use `ask_user_question` for approvals and clarifications; do not infer an answer from silence. |
 | `dispatch_worker` | Verify the materialized invocation. Use the host primitive with `promptPath` and `hostModelValue` for `native-session`; use deterministic `okstra worker-dispatch` with `modelExecutionValue` for `cli-wrapper`. **Not in a cmux run:** the cmux adapter overrides this row. |
 | `await_workers` | Await through the selected common dispatch backend, then verify terminal state and Result Paths. |
 | `redispatch_worker` | Start a fresh attempt from the persisted assignment and record the supplied dispatch kind. |

package/runtime/python/okstra_ctl/adapters/providers/grok/adapter.py

@@ -16,7 +16,8 @@ from okstra_ctl.domain.worker_exec import (
     PolicySupport,
     WorkerExecRequest,
 )
-from okstra_ctl.domain.worker_presentation import MergedText
+from okstra_ctl.domain.worker_presentation import JsonEvents
+from okstra_ctl.domain.worker_stream import StreamEvent, Text, ToolCall, ToolResult
 
 
 GROK = {
@@ -108,6 +109,65 @@ def observe_served_model(event: Mapping[str, Any]) -> str | None:
                 return names[0]
     return None
 
+
+def stream_events(event: Mapping[str, Any]) -> tuple[StreamEvent, ...]:
+    """grok `--output-format streaming-json` 한 줄을 공통 이벤트로 옮긴다.
+
+    이 CLI 의 `-p` 기본 `plain` 은 종료 시에만 stdout 에 쓴다. 파이프에 붙은
+    워커는 그 동안 pane 과 로그가 0바이트다(실측 2026-08-22). 같은 호출에
+    `streaming-json` 을 주면 ACP 세션 업데이트가 NDJSON 으로 흐른다. 키는
+    `type=text|tool_call|tool_call_update|end` 이고 Claude 의
+    `message.content` 가 아니다 — 그 스키마로 읽으면 이벤트는 전부 버려진다.
+    """
+    kind = event.get("type")
+    if kind == "text":
+        data = event.get("data")
+        # 공백만 있는 토큰도 살린다. 버리면 붙인 문장에서 단어가 붙는다.
+        return (Text(body=data),) if isinstance(data, str) and data else ()
+    if kind == "tool_call":
+        name = str(event.get("toolName") or event.get("title") or "tool")
+        return (ToolCall(name=name, detail=_call_detail(event)),)
+    if kind == "tool_call_update":
+        return _completed_tool(event)
+    if kind == "error":
+        message = event.get("message")
+        return (Text(body=message),) if isinstance(message, str) and message.strip() else ()
+    return ()
+
+
+def _call_detail(event: Mapping[str, Any]) -> str:
+    payload = event.get("rawInput")
+    if isinstance(payload, Mapping):
+        for key in ("command", "file_path", "path", "pattern", "query"):
+            value = payload.get(key)
+            if value:
+                return str(value)
+        return next(
+            (str(value) for value in payload.values() if isinstance(value, str) and value),
+            "",
+        )
+    title = event.get("title")
+    return str(title) if isinstance(title, str) else ""
+
+
+def _completed_tool(event: Mapping[str, Any]) -> tuple[StreamEvent, ...]:
+    if event.get("status") != "completed":
+        return ()
+    body = _output_body(event.get("rawOutput"))
+    return (ToolResult(body=body, size_bytes=len(body.encode("utf-8"))),)
+
+
+def _output_body(output: Any) -> str:
+    if isinstance(output, str):
+        return output
+    if isinstance(output, Mapping):
+        text = next(
+            (str(value) for value in output.values() if isinstance(value, str) and value),
+            "",
+        )
+        return text or json.dumps(output, ensure_ascii=False)
+    return "" if output is None else str(output)
+
 GROK_LEAD_LAUNCH = LeadLaunchSpec(
     executable="grok",
     model_flag="--model",
@@ -125,6 +185,8 @@ class GrokExecution:
 
     def build_command(self, request: WorkerExecRequest) -> ExecCommand:
         cwd = request.worktree_path or request.project_root
+        # `-p` 기본 `plain` 은 종료 시에만 stdout 에 쓴다. 러너는 파이프라
+        # TUI 도 열리지 않고, `--no-alt-screen` 도 그 침묵을 바꾸지 않는다.
         return ExecCommand(
             argv=(
                 "grok",
@@ -134,10 +196,16 @@ class GrokExecution:
                 request.model,
                 "--cwd",
                 str(cwd),
+                "--output-format",
+                "streaming-json",
             ),
             stdin_text=None,
             cwd=cwd,
-            presentation=MergedText(served_model_at_exit=served_model_from_session),
+            presentation=JsonEvents(
+                normalise=stream_events,
+                observe=observe_served_model,
+                join_adjacent_text=True,
+            ),
         )
 
     def policy_support(self) -> PolicySupport: