clink-cli 0.2.1__py3-none-any.whl

clink/parsers/codex_native_generation.py

@@ -0,0 +1,367 @@
+"""Validate native generation telemetry without publishing operational output."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import re
+from pathlib import Path
+from typing import Any
+
+from .base import MAX_METADATA_NUMBER, BaseParser, ParsedCLIResponse, ParserError, cli_failure, load_json
+
+MAX_EVENTS = 16384
+_MAX_SOURCE_BYTES = 1024 * 1024
+_USAGE_REQUIRED = frozenset({"input_tokens", "cached_input_tokens", "output_tokens", "reasoning_output_tokens"})
+_USAGE_OPTIONAL = frozenset({"cache_write_input_tokens"})
+_ITEM_EVENTS = frozenset({"item.started", "item.updated", "item.completed"})
+_TOOL_ITEMS = frozenset({"command_execution", "file_change", "mcp_tool_call", "collab_tool_call"})
+_STATUSES = frozenset({"in_progress", "completed", "failed"})
+_SESSION = re.compile(r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\Z")
+_EXEC_POLICY_DENIAL = re.compile(
+    r"`(?P<command>[^`\r\n]+)` rejected: policy forbids commands starting with `(?P<prefix>[^`\r\n]+)`\Z"
+)
+_COMMAND_APPROVAL_DENIALS = frozenset(
+    {
+        "approval required by policy, but AskForApproval is set to Never",
+        "approval required by policy, but AskForApproval::Granular.sandbox_approval is false",
+        "approval required by policy rule, but AskForApproval::Granular.rules is false",
+    }
+)
+_MCP_APPROVAL_DENIALS = frozenset(
+    {
+        "MCP tool call requires approval, but approval policy is never",
+        "MCP tool call cancelled: interactive approval is unavailable in exec mode",
+    }
+)
+
+# This independent contract binds only the new profile. The service validates
+# the private final-message file separately; streamed text is never an answer.
+PARSER_CONTRACT = (
+    "codex-native-generation-jsonl/v1\n"
+    "source=codex-6ff1e1ca3b30fc8b914720681fcf5fe62e95f856;max-events=16384;jsonl-newline=LF\n"
+    "strict-json:no-duplicate-keys-except-pinned-direct-web-search-ids,no-nonfinite-numbers,utf8-text\n"
+    "thread.started:{type,thread_id:uuid};turn.started:{type};one-thread,one-turn,in-order\n"
+    "item.started|updated|completed:{type,item};item:{id:nonblank-text,type:known,typed-payload}\n"
+    "known-items=agent_message,reasoning,command_execution,file_change,mcp_tool_call,collab_tool_call,"
+    "web_search,todo_list,error;unknown-fields-rejected;opaque-JsonValue-subtrees-preserved-only-during-validation\n"
+    "lifecycle:no-reused-completed-id,no-type-change,no-duplicate-start,no-incomplete-observed-items;"
+    "completed-without-start-allowed;pre-turn-completed-error-warnings-allowed\n"
+    "final:one-last-turn.completed:{type,usage};no-stream-message-required;content-always-empty;"
+    "private-final-file-validation-owned-by-service;no-stream-finalfile-equality\n"
+    "usage:required=input_tokens,cached_input_tokens,output_tokens,reasoning_output_tokens;"
+    "optional=cache_write_input_tokens;nonnegative-safe-json-integers\n"
+    "recoverable-completed-tool-failures-and-item-errors-counted;"
+    "exact-source-supported-command-and-MCP-refusals=permission_needed\n"
+    "error:{type,message:utf8};turn.failed:{type,error:{message:utf8}};"
+    "failed,unknown,malformed,incomplete=protocol_error;known-auth-and-rate-diagnostics-safe-codes\n"
+    "metadata:usage,actual_model=null,tool_error_count,permission_denial_count;no-identities-or-bodies\n"
+    "identity:sha256(canonical-json(contract,source_sha256(codex_native_generation.py,base.py)));"
+    "source-limit=1048576-bytes-each\n"
+)
+
+
+def _protocol_error(message: str = "Codex native generation output violates its protocol") -> ParserError:
+    return ParserError(message, code="protocol_error")
+
+
+def parser_contract_digest() -> str:
+    """Bind the native generation contract and its parser dependencies."""
+
+    sources = {}
+    try:
+        for name in ("codex_native_generation.py", "base.py"):
+            with Path(__file__).with_name(name).open("rb") as source:
+                content = source.read(_MAX_SOURCE_BYTES + 1)
+            if len(content) > _MAX_SOURCE_BYTES:
+                raise _protocol_error("Codex native generation parser source exceeds its identity limit")
+            sources[name] = hashlib.sha256(content).hexdigest()
+    except OSError:
+        raise _protocol_error("Codex native generation parser source identity is unavailable") from None
+    identity = json.dumps(
+        {"contract": PARSER_CONTRACT, "source_sha256": sources},
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+    )
+    return hashlib.sha256(identity.encode("utf-8")).hexdigest()
+
+
+def _object(
+    value: object, required: set[str] | frozenset[str], optional: frozenset[str] = frozenset()
+) -> dict[str, Any]:
+    if not isinstance(value, dict) or not required <= value.keys() or value.keys() - (required | optional):
+        raise _protocol_error()
+    return value
+
+
+def _text(value: object, *, nonempty: bool = False) -> str:
+    if not isinstance(value, str) or (nonempty and not value.strip()):
+        raise _protocol_error()
+    try:
+        value.encode("utf-8")
+    except UnicodeError:
+        raise _protocol_error() from None
+    return value
+
+
+def _json_value(value: object) -> None:
+    """Validate wire JSON without interpreting tool-owned nested objects."""
+
+    pending = [value]
+    while pending:
+        part = pending.pop()
+        if isinstance(part, dict):
+            for key in part:
+                _text(key)
+            pending.extend(part.values())
+        elif isinstance(part, list):
+            pending.extend(part)
+        elif isinstance(part, str):
+            _text(part)
+        elif isinstance(part, float) and not math.isfinite(part):
+            raise _protocol_error()
+
+
+def _error(value: object) -> dict[str, Any]:
+    error = _object(value, {"message"})
+    _text(error["message"])
+    return error
+
+
+def _status(value: object, *, command: bool = False) -> None:
+    if not isinstance(value, str) or value not in (_STATUSES | {"declined"} if command else _STATUSES):
+        raise _protocol_error()
+
+
+def _item(value: object) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise _protocol_error()
+    _text(value.get("id"), nonempty=True)
+    item_type = _text(value.get("type"))
+    common = {"id", "type"}
+    if item_type in {"agent_message", "reasoning"}:
+        _object(value, common | {"text"})
+        _text(value["text"])
+    elif item_type == "error":
+        _object(value, common | {"message"})
+        _text(value["message"])
+    elif item_type == "command_execution":
+        _object(value, common | {"command", "aggregated_output", "exit_code", "status"})
+        _text(value["command"])
+        _text(value["aggregated_output"])
+        exit_code = value["exit_code"]
+        if exit_code is not None and (type(exit_code) is not int or not -(2**31) <= exit_code < 2**31):
+            raise _protocol_error()
+        _status(value["status"], command=True)
+    elif item_type == "file_change":
+        _object(value, common | {"changes", "status"})
+        _status(value["status"])
+        if not isinstance(value["changes"], list):
+            raise _protocol_error()
+        for change in value["changes"]:
+            _object(change, {"path", "kind"})
+            _text(change["path"])
+            if not isinstance(change["kind"], str) or change["kind"] not in {"add", "delete", "update"}:
+                raise _protocol_error()
+    elif item_type == "mcp_tool_call":
+        _object(value, common | {"server", "tool", "arguments", "result", "error", "status"})
+        _text(value["server"])
+        _text(value["tool"])
+        _status(value["status"])
+        if value["error"] is not None:
+            _error(value["error"])
+        if value["result"] is not None:
+            result = _object(value["result"], {"content", "structured_content"}, frozenset({"_meta"}))
+            if not isinstance(result["content"], list):
+                raise _protocol_error()
+    elif item_type == "collab_tool_call":
+        _object(
+            value, common | {"tool", "sender_thread_id", "receiver_thread_ids", "prompt", "agents_states", "status"}
+        )
+        if not isinstance(value["tool"], str) or value["tool"] not in {
+            "spawn_agent",
+            "send_input",
+            "wait",
+            "close_agent",
+        }:
+            raise _protocol_error()
+        _text(value["sender_thread_id"], nonempty=True)
+        if value["prompt"] is not None:
+            _text(value["prompt"])
+        if not isinstance(value["receiver_thread_ids"], list) or not isinstance(value["agents_states"], dict):
+            raise _protocol_error()
+        for receiver in value["receiver_thread_ids"]:
+            _text(receiver, nonempty=True)
+        for agent_id, state in value["agents_states"].items():
+            _text(agent_id, nonempty=True)
+            _object(state, {"status", "message"})
+            if not isinstance(state["status"], str) or state["status"] not in {
+                "pending_init",
+                "running",
+                "interrupted",
+                "completed",
+                "errored",
+                "shutdown",
+                "not_found",
+            }:
+                raise _protocol_error()
+            if state["message"] is not None:
+                _text(state["message"])
+        _status(value["status"])
+    elif item_type == "web_search":
+        _object(value, common | {"query", "action"}, frozenset({"results"}))
+        _text(value["query"])
+        # The imported WebSearchAction is tool-owned. The pinned mapper exposes
+        # its container, while results explicitly contain arbitrary JsonValue.
+        if not isinstance(value["action"], dict):
+            raise _protocol_error()
+        if "results" in value and not isinstance(value["results"], list):
+            raise _protocol_error()
+    elif item_type == "todo_list":
+        _object(value, common | {"items"})
+        if not isinstance(value["items"], list):
+            raise _protocol_error()
+        for step in value["items"]:
+            _object(step, {"text", "completed"})
+            _text(step["text"])
+            if type(step["completed"]) is not bool:
+                raise _protocol_error()
+    else:
+        raise _protocol_error()
+    return value
+
+
+def _permission_denial(item: dict[str, Any]) -> bool:
+    """Recognize only pinned refusal signatures, never arbitrary tool prose."""
+
+    if item["type"] == "command_execution" and item["status"] == "declined" and item["exit_code"] == -1:
+        output = item["aggregated_output"]
+        if output in _COMMAND_APPROVAL_DENIALS:
+            return True
+        marker = _EXEC_POLICY_DENIAL.fullmatch(output)
+        return (
+            marker is not None
+            and marker["command"] == item["command"]
+            and bool(marker["command"].strip())
+            and bool(marker["prefix"].strip())
+        )
+    return (
+        item["type"] == "mcp_tool_call"
+        and item["status"] == "failed"
+        and item["result"] is None
+        and item["error"] is not None
+        and item["error"]["message"] in _MCP_APPROVAL_DENIALS
+    )
+
+
+class CodexNativeGenerationParser(BaseParser):
+    """Validate one native turn; leave final-message publication to its owner."""
+
+    name = "codex_native_generation_jsonl"
+
+    def parse(self, stdout: str, stderr: str = "") -> ParsedCLIResponse:
+        if not isinstance(stdout, str) or not isinstance(stderr, str):
+            raise _protocol_error()
+        _text(stdout)
+        _text(stderr)
+        lines = [line for line in stdout.split("\n") if line.strip(" \t\r")]
+        if not lines or len(lines) > MAX_EVENTS:
+            raise cli_failure(
+                stderr, message="Codex native generation output is empty or too large", code="protocol_error"
+            )
+        thread_started = False
+        turn_started = False
+        terminal = False
+        fatal: dict[str, Any] | None = None
+        failed: dict[str, Any] | None = None
+        item_types: dict[str, str] = {}
+        active_items: set[str] = set()
+        completed_items: set[str] = set()
+        metadata: dict[str, Any] = {"actual_model": None, "tool_error_count": 0, "permission_denial_count": 0}
+
+        for line in lines:
+            try:
+                event = load_json(line, allow_codex_web_search_ids=True)
+            except ParserError:
+                raise _protocol_error() from None
+            _json_value(event)
+            if not isinstance(event, dict) or not isinstance(event.get("type"), str) or terminal:
+                raise _protocol_error()
+            event_type = event["type"]
+            # Native terminal handling reconciles outstanding tool/todo items
+            # before emitting turn.failed. A prior fatal error still prevents
+            # success, but must not discard its safe authentication/rate code.
+            if fatal is not None and event_type not in {"item.completed", "turn.failed"}:
+                raise _protocol_error()
+
+            if event_type == "error":
+                _object(event, {"type", "message"})
+                _text(event["message"])
+                fatal = event
+            elif event_type == "turn.failed":
+                _object(event, {"type", "error"})
+                _error(event["error"])
+                failed = event
+                terminal = True
+            elif event_type == "thread.started":
+                _object(event, {"type", "thread_id"})
+                session = _text(event["thread_id"])
+                if thread_started or turn_started or not _SESSION.fullmatch(session):
+                    raise _protocol_error()
+                thread_started = True
+            elif event_type == "turn.started":
+                _object(event, {"type"})
+                if not thread_started or turn_started:
+                    raise _protocol_error()
+                turn_started = True
+            elif event_type in _ITEM_EVENTS:
+                _object(event, {"type", "item"})
+                item = _item(event["item"])
+                item_id, item_type = item["id"], item["type"]
+                if not thread_started or (
+                    not turn_started and not (item_type == "error" and event_type == "item.completed")
+                ):
+                    raise _protocol_error()
+                if item_id in completed_items or (item_id in item_types and item_types[item_id] != item_type):
+                    raise _protocol_error()
+                if event_type == "item.started" and item_id in item_types:
+                    raise _protocol_error()
+                item_types[item_id] = item_type
+                if event_type == "item.completed":
+                    if item_type in _TOOL_ITEMS and item["status"] == "in_progress":
+                        raise _protocol_error()
+                    active_items.discard(item_id)
+                    completed_items.add(item_id)
+                    tool_failed = item_type == "error" or (
+                        item_type in _TOOL_ITEMS
+                        and (
+                            item["status"] in {"failed", "declined"}
+                            or (item_type == "command_execution" and item["exit_code"] not in (None, 0))
+                            or (item_type == "mcp_tool_call" and item["error"] is not None)
+                        )
+                    )
+                    metadata["tool_error_count"] += int(tool_failed)
+                    metadata["permission_denial_count"] += int(_permission_denial(item))
+                else:
+                    active_items.add(item_id)
+            elif event_type == "turn.completed":
+                _object(event, {"type", "usage"})
+                if not turn_started or active_items:
+                    raise _protocol_error()
+                usage = _object(event["usage"], _USAGE_REQUIRED, _USAGE_OPTIONAL)
+                if any(type(count) is not int or not 0 <= count <= MAX_METADATA_NUMBER for count in usage.values()):
+                    raise _protocol_error()
+                metadata["usage"] = usage.copy()
+                terminal = True
+            else:
+                raise _protocol_error()
+
+        if metadata["permission_denial_count"]:
+            raise ParserError("Codex native generation requires permission", code="permission_needed")
+        if failed is not None or fatal is not None or not terminal:
+            raise cli_failure(
+                failed, fatal, stderr, message="Codex native generation did not complete", code="protocol_error"
+            )
+        return ParsedCLIResponse(content="", metadata=metadata)

clink/parsers/gemini.py

@@ -0,0 +1,110 @@
+"""Parser for Gemini CLI JSON output; execution availability is adapter policy."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .base import (
+    BaseParser,
+    ParsedCLIResponse,
+    ParserError,
+    bounded_counts,
+    bounded_number,
+    cli_failure,
+    load_json,
+    model_identifier,
+)
+
+_TOKEN_FIELDS = ("prompt", "candidates", "total", "cached", "thoughts", "tool")
+
+
+class GeminiJSONParser(BaseParser):
+    """Require response text and reject explicit Gemini errors."""
+
+    name = "gemini_json"
+
+    def parse(self, stdout: str, stderr: str) -> ParsedCLIResponse:
+        if not stdout.strip():
+            raise cli_failure(stderr, message="Gemini CLI returned empty stdout")
+
+        payload = load_json(stdout)
+        if not isinstance(payload, dict):
+            raise ParserError("Gemini CLI JSON must be an object")
+        if "type" in payload and not isinstance(payload["type"], str):
+            raise ParserError("Gemini CLI response type must be textual")
+        if "status" in payload and not isinstance(payload["status"], str):
+            raise ParserError("Gemini CLI response status must be textual")
+        if (
+            payload.get("type") in ("error", "failed")
+            or payload.get("status") in ("error", "failed", "cancelled", "aborted", "interrupted")
+            or payload.get("error") is not None
+            or payload.get("errors")
+            or payload.get("is_error", False) is not False
+        ):
+            raise cli_failure(payload, stderr, message="Gemini CLI reported a failure")
+        if payload.get("status", "success") not in ("completed", "success"):
+            raise ParserError("Gemini CLI response status did not indicate success")
+
+        metadata = self._metadata(payload, stderr)
+        response = payload.get("response")
+        if not isinstance(response, str):
+            raise ParserError("Gemini CLI response must be textual")
+        if not response.strip():
+            raise cli_failure(stderr, message="Gemini CLI response was empty", code="empty_response")
+
+        return ParsedCLIResponse(content=response.strip(), metadata=metadata)
+
+    def _metadata(self, payload: dict[str, Any], stderr: str) -> dict[str, Any]:
+        stats = payload.get("stats", {})
+        if not isinstance(stats, dict):
+            raise ParserError("Gemini CLI stats must be an object")
+        pending: list[object] = [stats]
+        while pending:
+            record = pending.pop()
+            if isinstance(record, list):
+                pending.extend(record)
+            elif isinstance(record, dict):
+                if "status" in record and not isinstance(record["status"], str):
+                    raise ParserError("Gemini CLI stats status must be textual")
+                if (
+                    record.get("type") in ("error", "failed")
+                    or record.get("status") in ("error", "failed", "cancelled", "aborted", "interrupted")
+                    or record.get("error") is not None
+                    or record.get("errors")
+                    or record.get("is_error", False) is not False
+                ):
+                    raise cli_failure(record, stderr, message="Gemini CLI stats reported a failure")
+                for field in ("totalErrors", "totalFail", "fail"):
+                    if field not in record:
+                        continue
+                    errors = record[field]
+                    if not isinstance(errors, int) or isinstance(errors, bool) or errors < 0:
+                        raise ParserError("Gemini CLI failure counts must be nonnegative integers")
+                    if errors:
+                        raise cli_failure(stderr, message="Gemini CLI stats reported a failure")
+                pending.extend(record.values())
+        models = stats.get("models", {})
+        if not isinstance(models, dict):
+            raise ParserError("Gemini CLI model stats must be objects")
+
+        metadata: dict[str, Any] = {}
+        for model_stats in models.values():
+            if not isinstance(model_stats, dict):
+                raise ParserError("Gemini CLI model stats must be objects")
+            api_stats = model_stats.get("api", {})
+            if not isinstance(api_stats, dict):
+                raise ParserError("Gemini CLI API stats must be an object")
+
+        if len(models) == 1:
+            model_name, model_stats = next(iter(models.items()))
+            actual_model = model_identifier(model_name)
+            if actual_model:
+                metadata["actual_model"] = actual_model
+            tokens = bounded_counts(model_stats.get("tokens"), _TOKEN_FIELDS)
+            if tokens:
+                metadata["usage"] = tokens
+            latency = bounded_number(model_stats.get("api", {}).get("totalLatencyMs"))
+            if latency is not None:
+                metadata["latency_ms"] = latency
+
+        return metadata

clink/parsers/grok.py

@@ -0,0 +1,63 @@
+"""Parse Grok Build's single-document JSON result without admitting execution."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .base import BaseParser, ParsedCLIResponse, ParserError, bounded_counts, cli_failure, load_json, model_identifier
+
+_USAGE_FIELDS = (
+    "input_tokens",
+    "output_tokens",
+    "cache_read_input_tokens",
+    "cache_creation_input_tokens",
+    "reasoning_tokens",
+    "total_tokens",
+)
+
+
+class GrokJSONParser(BaseParser):
+    """Require a complete end_turn response, rejecting partial or error results."""
+
+    name = "grok_json"
+
+    def parse(self, stdout: str, stderr: str) -> ParsedCLIResponse:
+        if not stdout.strip():
+            raise cli_failure(stderr, message="Grok CLI returned empty stdout")
+
+        payload = load_json(stdout)
+        if not isinstance(payload, dict):
+            raise ParserError("Grok CLI JSON must be an object")
+        if (
+            payload.get("type") in ("error", "failed")
+            or payload.get("error") is not None
+            or ("errors" in payload and payload["errors"] is not None and payload["errors"] != [])
+            or payload.get("is_error", False) is not False
+        ):
+            raise cli_failure(payload, stderr, message="Grok CLI reported a failure")
+        if "type" in payload or "event" in payload or "status" in payload:
+            raise ParserError("Grok CLI returned an unsupported JSON dialect")
+        # Installed 1.0.70 documents end_turn, max_tokens, max_turn_requests,
+        # refusal and cancelled. Only end_turn establishes a complete answer.
+        if payload.get("stopReason") != "end_turn":
+            raise ParserError("Grok CLI did not include a complete terminal stop reason")
+
+        text = payload.get("text")
+        if not isinstance(text, str):
+            raise ParserError("Grok CLI response must be textual")
+        if not text.strip():
+            raise cli_failure(stderr, message="Grok CLI response was empty", code="empty_response")
+
+        metadata: dict[str, Any] = bounded_counts(payload, ("num_turns",))
+        usage = bounded_counts(payload.get("usage"), _USAGE_FIELDS)
+        if usage:
+            metadata["usage"] = usage
+
+        model_usage = payload.get("modelUsage")
+        if isinstance(model_usage, dict) and len(model_usage) == 1:
+            model_name, model_stats = next(iter(model_usage.items()))
+            actual_model = model_identifier(model_name)
+            if actual_model and actual_model != "unknown" and isinstance(model_stats, dict):
+                metadata["actual_model"] = actual_model
+
+        return ParsedCLIResponse(content=text.strip(), metadata=metadata)

clink/parsers/grok_native.py

@@ -0,0 +1,91 @@
+"""Parse Grok native JSON and documented headless refusal diagnostics."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from clink.native_contracts import ParsedNativeResponse
+from clink.parsers.base import ParserError, bounded_counts, cli_failure, load_json, model_identifier
+
+RESULT_CHARACTERS = 20000
+MAX_EVENTS = 16384
+_SESSION = re.compile(r"[0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}\Z")
+_PERMISSION_REFUSAL = re.compile(
+    r"permission required: [^\r\n]+ was not run, as a headless run cannot ask for approval\Z"
+)
+_STOP_REASONS = {"end_turn", "max_tokens", "max_turn_requests", "refusal", "cancelled"}
+_USAGE_FIELDS = (
+    "input_tokens",
+    "output_tokens",
+    "cache_read_input_tokens",
+    "cache_creation_input_tokens",
+    "reasoning_tokens",
+    "total_tokens",
+)
+
+
+def validate_session_id(value: str | None) -> str | None:
+    """Accept only the UUID identity consumed by Grok's native session flags."""
+
+    if value is not None and (not isinstance(value, str) or not _SESSION.fullmatch(value)):
+        raise ParserError("Grok native session identity is invalid")
+    return value
+
+
+class GrokNativeParser:
+    """Keep native execution outcomes separate from advisory answer validity."""
+
+    def parse(self, stdout: str, stderr: str = "") -> ParsedNativeResponse:
+        denials = min(MAX_EVENTS, sum(bool(_PERMISSION_REFUSAL.fullmatch(line)) for line in stderr.splitlines()))
+        if not stdout.strip():
+            if denials:
+                return ParsedNativeResponse(
+                    "permission_needed", metadata={"permission_denial_count": denials, "truncated": False}
+                )
+            raise cli_failure(stderr, message="Grok native output was empty")
+        payload = load_json(stdout)
+        if not isinstance(payload, dict):
+            raise ParserError("Grok native JSON must be an object")
+        if any(name in payload for name in ("event", "status")) or ("type" in payload and payload["type"] != "error"):
+            raise ParserError("Grok native output used an unsupported JSON dialect")
+        if "is_error" in payload and not isinstance(payload["is_error"], bool):
+            raise ParserError("Grok native error flag must be boolean")
+        if "errors" in payload and payload["errors"] is not None and not isinstance(payload["errors"], list):
+            raise ParserError("Grok native errors must be an array")
+        session_id = validate_session_id(payload.get("sessionId"))
+        error = (
+            payload.get("type") == "error"
+            or payload.get("error") is not None
+            or bool(payload.get("errors"))
+            or payload.get("is_error") is True
+        )
+        reason = payload.get("stopReason")
+        if reason is not None and (not isinstance(reason, str) or reason not in _STOP_REASONS):
+            raise ParserError("Grok native terminal stop reason is invalid")
+        if reason is None and not error:
+            raise ParserError("Grok native output omitted its terminal stop reason")
+        if not error and session_id is None:
+            raise ParserError("Grok native terminal result omitted its session identity")
+        content = payload.get("text", "") if error else payload.get("text")
+        if not isinstance(content, str):
+            raise ParserError("Grok native result must be textual")
+        state = "permission_needed" if denials else "completed" if reason == "end_turn" and not error else "failed"
+        metadata: dict[str, Any] = {
+            "permission_denial_count": denials,
+            "truncated": len(content) > RESULT_CHARACTERS,
+        }
+        if reason is not None:
+            metadata["terminal_stop_reason"] = reason
+        metadata.update(bounded_counts(payload, ("num_turns",)))
+        if usage := bounded_counts(payload.get("usage"), _USAGE_FIELDS):
+            metadata["usage"] = usage
+        model_usage = payload.get("modelUsage")
+        if isinstance(model_usage, dict) and len(model_usage) == 1:
+            model, stats = next(iter(model_usage.items()))
+            actual_model = model_identifier(model)
+            if actual_model is not None and actual_model != "unknown" and isinstance(stats, dict):
+                metadata["actual_model"] = actual_model
+        if state == "failed":
+            metadata["error_code"] = cli_failure(payload, stderr, code="native_error").code
+        return ParsedNativeResponse(state, content[:RESULT_CHARACTERS], session_id, metadata)