okstra 0.180.0 → 0.183.2

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/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:

package/runtime/python/okstra_ctl/agent_activity.py

@@ -3,10 +3,8 @@ from __future__ import annotations
 
 import argparse
 import json
-import os
 import re
 import sys
-import tempfile
 from collections.abc import Mapping, Sequence
 from datetime import datetime, timezone
 from pathlib import Path
@@ -22,6 +20,11 @@ from okstra_ctl.worker_audit_ledger import (
     parse_evidence_commands,
     read_evidence_commands,
 )
+from okstra_ctl.json_boundary import (
+    JsonBoundaryError,
+    load_owned_object,
+    mutate_owned_object_atomic,
+)
 
 
 ACTIVITY_KINDS = frozenset({
@@ -59,12 +62,9 @@ class ActivityProjectionError(ValueError):
 
 def _read_json_object(path: Path) -> dict[str, Any]:
     try:
-        payload = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
-        raise ActivityProjectionError(f"cannot read JSON object {path}: {exc}") from exc
-    if not isinstance(payload, dict):
-        raise ActivityProjectionError(f"JSON value must be an object: {path}")
-    return payload
+        return load_owned_object(path, artifact="agent activity artifact")
+    except JsonBoundaryError as exc:
+        raise ActivityProjectionError(str(exc)) from exc
 
 
 def _resolve_project_path(project_root: Path, value: str | Path) -> Path:
@@ -88,6 +88,50 @@ def _manifest_run_seq(manifest: Mapping[str, Any]) -> str:
     return _require_string(sequences, "manifests")
 
 
+def _validate_activity_ownership(
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    details: Mapping[str, Any],
+) -> None:
+    executions = manifest.get("roleExecutions")
+    assignments = manifest.get("workerAssignments")
+    if isinstance(assignments, list):
+        assigned = {
+            row["workerId"] for row in assignments
+            if isinstance(row, Mapping) and isinstance(row.get("workerId"), str)
+        }
+    elif isinstance(executions, list):
+        assigned = {
+            f"{row['provider']}-worker"
+            for row in executions
+            if isinstance(row, Mapping) and isinstance(row.get("provider"), str)
+        }
+    else:
+        assigned = set()
+    if isinstance(assignments, list) or isinstance(executions, list):
+        assigned.update({"okstra-lead", f"{manifest.get('leadRuntime', '')}-lead"})
+        agent = _require_string(details, "agent")
+        if agent not in assigned:
+            raise ActivityProjectionError(
+                f"agent `{agent}` is not assigned to this run"
+            )
+    state_value = manifest.get("planBodyVerificationPath")
+    if not isinstance(state_value, str) or not details.get("planItemIds"):
+        return
+    state = _read_json_object(_resolve_project_path(project_root, state_value))
+    verification = state.get("planBodyVerification")
+    items = verification.get("planItems") if isinstance(verification, Mapping) else []
+    known = {
+        row.get("id") for row in items
+        if isinstance(row, Mapping) and isinstance(row.get("id"), str)
+    }
+    unknown = sorted(set(details["planItemIds"]) - known)
+    if unknown:
+        raise ActivityProjectionError(
+            "plan item(s) not in the current plan state: " + ", ".join(unknown)
+        )
+
+
 def _utc_now() -> str:
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 
@@ -139,27 +183,6 @@ def _validate_activity_order(rows: Sequence[Mapping[str, Any]]) -> None:
         )
 
 
-def _atomic_write_json(path: Path, payload: Mapping[str, Any]) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    temporary_path: Path | None = None
-    try:
-        with tempfile.NamedTemporaryFile(
-            mode="w",
-            encoding="utf-8",
-            dir=path.parent,
-            prefix=f".{path.name}.",
-            suffix=".tmp",
-            delete=False,
-        ) as handle:
-            temporary_path = Path(handle.name)
-            json.dump(payload, handle, ensure_ascii=False, indent=2)
-            handle.write("\n")
-        os.replace(temporary_path, path)
-    finally:
-        if temporary_path is not None and temporary_path.exists():
-            temporary_path.unlink()
-
-
 def record_activity(
     project_root: Path,
     run_manifest_path: Path,
@@ -172,6 +195,7 @@ def record_activity(
         raise ActivityProjectionError(
             "run manifest does not declare activityContractVersion 1"
         )
+    _validate_activity_ownership(project_root, manifest, details)
     event = LeadEvent(
         event_type="activity",
         lead_runtime=_require_string(manifest, "leadRuntime"),
@@ -184,7 +208,10 @@ def record_activity(
     events_path = _resolve_project_path(
         project_root, _require_string(manifest, "leadEventsPath")
     )
-    return append_activity_event(events_path, event)
+    try:
+        return append_activity_event(events_path, event)
+    except ValueError as exc:
+        raise ActivityProjectionError(str(exc)) from exc
 
 
 def agent_activity_rows(
@@ -224,9 +251,14 @@ def project_agent_activity(
     manifest = _read_json_object(run_manifest_path)
     if manifest.get("activityContractVersion") != 1:
         return ()
-    data = _read_json_object(data_path)
-    data["agentActivity"] = list(rows)
-    _atomic_write_json(data_path, data)
+    try:
+        mutate_owned_object_atomic(
+            data_path,
+            lambda data: {**data, "agentActivity": list(rows)},
+            artifact="final report record",
+        )
+    except JsonBoundaryError as exc:
+        raise ActivityProjectionError(str(exc)) from exc
     return rows
 
 
@@ -242,6 +274,9 @@ def _parse_command_records(raw_records: Sequence[str]) -> tuple[EvidenceCommand,
 
 def _activity_commands(args: argparse.Namespace) -> tuple[EvidenceCommand, ...]:
     commands = list(_parse_command_records(args.command_record))
+    typed = _typed_command(args)
+    if typed is not None:
+        commands.append(typed)
     if args.audit_sidecar is not None:
         audit_commands, failures = read_evidence_commands(args.audit_sidecar)
         if failures:
@@ -250,6 +285,45 @@ def _activity_commands(args: argparse.Namespace) -> tuple[EvidenceCommand, ...]:
     return tuple(commands)
 
 
+def _typed_command(args: argparse.Namespace) -> EvidenceCommand | None:
+    values = (
+        args.evidence_command,
+        args.command_cwd,
+        args.command_exit_code,
+        args.command_output_file,
+    )
+    if not any(value is not None for value in values):
+        return None
+    if any(value is None for value in values):
+        raise ActivityProjectionError(
+            "--command requires --command-cwd, --command-exit-code, and "
+            "--command-output-file"
+        )
+    try:
+        output_summary = args.command_output_file.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise ActivityProjectionError(
+            f"cannot read command output {args.command_output_file}: {exc}"
+        ) from exc
+    return EvidenceCommand(
+        command=args.evidence_command,
+        cwd=args.command_cwd,
+        exit_code=args.command_exit_code,
+        output_summary=output_summary,
+    )
+
+
+def _activity_summary(args: argparse.Namespace) -> str:
+    if args.summary is not None:
+        return args.summary
+    try:
+        return args.summary_file.read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeError) as exc:
+        raise ActivityProjectionError(
+            f"cannot read activity summary {args.summary_file}: {exc}"
+        ) from exc
+
+
 def _conversation_activity_line(details: Mapping[str, Any]) -> str:
     plan_items = ",".join(details["planItemIds"]) or "<none>"
     result_path = str(details["resultPath"] or "<none>")
@@ -266,13 +340,15 @@ def _append(args: argparse.Namespace) -> int:
     details = {
         "kind": args.kind,
         "agent": args.agent,
-        "summary": args.summary,
+        "summary": _activity_summary(args),
         "planItemIds": args.plan_item_id,
         "resultPath": args.result_path,
         "commands": [command.to_record() for command in commands],
         "evidenceRefs": args.evidence_ref,
         "outcome": args.outcome,
     }
+    if args.request_ref is not None:
+        details["activityRequestRef"] = args.request_ref
     event = record_activity(args.project_root, args.run_manifest, details)
     payload = dict(event.details)
     payload["ok"] = True
@@ -301,15 +377,22 @@ def _parser() -> argparse.ArgumentParser:
         "--kind", choices=sorted(ACTIVITY_KINDS), required=True
     )
     append_parser.add_argument("--agent", required=True)
-    append_parser.add_argument("--summary", required=True)
+    summary = append_parser.add_mutually_exclusive_group(required=True)
+    summary.add_argument("--summary")
+    summary.add_argument("--summary-file", type=Path)
     append_parser.add_argument(
         "--outcome", choices=sorted(ACTIVITY_OUTCOMES), required=True
     )
     append_parser.add_argument("--plan-item-id", action="append", default=[])
     append_parser.add_argument("--evidence-ref", action="append", default=[])
     append_parser.add_argument("--command-record", action="append", default=[])
+    append_parser.add_argument("--command", dest="evidence_command")
+    append_parser.add_argument("--command-cwd")
+    append_parser.add_argument("--command-exit-code", type=int)
+    append_parser.add_argument("--command-output-file", type=Path)
     append_parser.add_argument("--result-path", default="")
     append_parser.add_argument("--audit-sidecar", type=Path)
+    append_parser.add_argument("--request-ref")
     project_parser = subparsers.add_parser("project")
     project_parser.add_argument("--project-root", type=Path, required=True)
     project_parser.add_argument("--run-manifest", type=Path, required=True)

package/runtime/python/okstra_ctl/agent_invocation.py

@@ -15,6 +15,12 @@ import tempfile
 from typing import Iterator, Literal, Mapping, get_args
 
 from .domain.role import RoleCatalogError, role_for_duty
+from .json_boundary import (
+    JsonBoundaryError,
+    external_invocation_json_source,
+    load_external_json,
+    load_owned_object,
+)
 
 
 AgentAudience = Literal[
@@ -935,8 +941,15 @@ def _verified_result_envelope(
 ) -> tuple[bytes, str]:
     try:
         body = result_path.read_bytes()
-        envelope = json.loads(body.decode("utf-8"))
-    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        envelope = load_external_json(
+            external_invocation_json_source(
+                result_path,
+                project_root=project_root,
+                purpose=purpose,
+            ),
+            artifact="standalone worker result",
+        )
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError, JsonBoundaryError) as exc:
         raise AgentInvocationError(
             f"standalone result envelope is missing or invalid: {result_path}"
         ) from exc
@@ -1494,8 +1507,8 @@ def _metadata_difference(
     so they are reported by name too.
     """
     try:
-        existing = json.loads(metadata.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
+        existing = load_owned_object(metadata, artifact="agent invocation metadata")
+    except JsonBoundaryError as exc:
         return f"existing metadata is unreadable: {exc}"
     composed = materialized.metadata
     if not isinstance(existing, dict):
@@ -2240,8 +2253,8 @@ def _load_json_object(path: Path, label: str) -> dict[str, object]:
 
 def _read_json_if_object(path: Path) -> dict[str, object] | None:
     try:
-        value = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
+        value = load_owned_object(path, artifact="agent invocation metadata")
+    except JsonBoundaryError:
         return None
     return value if isinstance(value, dict) else None