dsh-aris-panel 0.1.0

package/tools/copilot_native_evidence.py

@@ -0,0 +1,818 @@
+#!/usr/bin/env python3
+"""Bind an ARIS review to Copilot CLI's native rubber-duck subagent.
+
+Copilot persists machine-readable session events for the root model, tool call,
+subagent lifecycle, resolved reviewer model, and tool result.  This helper turns
+that host-owned event chain into a small evidence artifact.  It deliberately
+does not accept executor/reviewer model names from the caller.
+
+The protocol prevents a recent, unrelated Copilot session from being
+mistaken for the current one:
+
+1. ``marker`` runs as one short root tool call and emits a unique caller token.
+2. After that call returns (and Copilot has persisted it), ``challenge`` binds
+   the marker event and records the host-reported executor model.
+3. The caller includes the returned nonce in a native ``rubber-duck`` task.
+   ``verify`` then requires a successful, completed child subagent with the
+   same tool-call id, extracts its host-reported model and raw result, and
+   rejects same/unknown-family pairs.
+
+The resulting evidence is revalidated by ``review_gate.py`` before a native
+positive verdict is allowed to stop the loop.
+"""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import secrets
+import stat
+import sys
+from typing import Any, Iterable
+
+
+CHALLENGE_SCHEMA = "aris.copilot-native.challenge/v1"
+EVIDENCE_SCHEMA = "aris.copilot-native.evidence/v1"
+NONCE_PREFIX = "ARIS_REVIEW_NONCE="
+MAX_EVENT_LOG_BYTES = 256 * 1024 * 1024
+KNOWN_FAMILIES = {"openai", "anthropic", "google"}
+
+
+class EvidenceError(RuntimeError):
+    """A deterministic evidence failure with a stable process exit code."""
+
+    def __init__(self, message: str, *, code: int = 2) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+class PolicyRejected(EvidenceError):
+    """The host event chain is real, but it violates reviewer policy."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, code=10)
+
+
+@dataclass(frozen=True)
+class EventRecord:
+    event: dict[str, Any]
+    end_offset: int
+
+
+def derive_model_family(model: str) -> str:
+    """Derive a provider family from an exact model id, failing closed."""
+
+    name = (model or "").strip().lower()
+    families: set[str] = set()
+    if re.search(r"(^|[^a-z0-9])(gpt|chatgpt|codex|oracle|o1|o3|o4)([^a-z0-9]|$)", name):
+        families.add("openai")
+    if re.search(r"(^|[^a-z0-9])(claude|sonnet|opus|haiku|anthropic)([^a-z0-9]|$)", name):
+        families.add("anthropic")
+    if re.search(r"(^|[^a-z0-9])(gemini|google)([^a-z0-9]|$)", name):
+        families.add("google")
+    return next(iter(families)) if len(families) == 1 else "unknown"
+
+
+def _sha256(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _canonical_json(data: dict[str, Any]) -> bytes:
+    return json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()
+
+
+def _parse_timestamp(value: Any) -> datetime:
+    if not isinstance(value, str) or not value:
+        raise EvidenceError("event is missing an ISO-8601 timestamp")
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise EvidenceError(f"invalid event timestamp: {value}") from exc
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)
+
+
+def _safe_regular_file(path: Path) -> None:
+    try:
+        info = path.lstat()
+    except FileNotFoundError as exc:
+        raise EvidenceError(f"file not found: {path}") from exc
+    if stat.S_ISLNK(info.st_mode) or not stat.S_ISREG(info.st_mode):
+        raise EvidenceError(f"expected a non-symlink regular file: {path}")
+    if hasattr(os, "getuid") and info.st_uid != os.getuid():
+        raise EvidenceError(f"refusing event file owned by another user: {path}")
+
+
+def _read_event_log(path: Path) -> tuple[bytes, list[EventRecord]]:
+    _safe_regular_file(path)
+    size = path.stat().st_size
+    if size > MAX_EVENT_LOG_BYTES:
+        raise EvidenceError(f"Copilot event log exceeds {MAX_EVENT_LOG_BYTES} bytes: {path}")
+    raw = path.read_bytes()
+    records: list[EventRecord] = []
+    offset = 0
+    for line_number, line in enumerate(raw.splitlines(keepends=True), start=1):
+        offset += len(line)
+        payload = line.rstrip(b"\r\n")
+        if not payload:
+            continue
+        try:
+            event = json.loads(payload)
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raise EvidenceError(f"malformed Copilot event JSON at {path}:{line_number}") from exc
+        if not isinstance(event, dict):
+            raise EvidenceError(f"non-object Copilot event at {path}:{line_number}")
+        records.append(EventRecord(event=event, end_offset=offset))
+    return raw, records
+
+
+def _session_metadata(records: Iterable[EventRecord]) -> tuple[str, str]:
+    starts = [record.event for record in records if record.event.get("type") == "session.start"]
+    if len(starts) != 1:
+        raise EvidenceError(f"expected exactly one session.start event, found {len(starts)}")
+    data = starts[0].get("data") or {}
+    context = data.get("context") or {}
+    session_id = data.get("sessionId")
+    cwd = context.get("cwd")
+    if not isinstance(session_id, str) or not session_id:
+        raise EvidenceError("session.start is missing sessionId")
+    if not isinstance(cwd, str) or not cwd:
+        raise EvidenceError("session.start is missing context.cwd")
+    return session_id, str(Path(cwd).resolve())
+
+
+def _event_arguments_text(event: dict[str, Any]) -> str:
+    data = event.get("data") or {}
+    try:
+        return json.dumps(data.get("arguments") or {}, sort_keys=True, ensure_ascii=False)
+    except (TypeError, ValueError):
+        return ""
+
+
+def _tool_result_text(event: dict[str, Any]) -> str:
+    data = event.get("data") or {}
+    result = data.get("result") or {}
+    if not isinstance(result, dict):
+        return ""
+    parts = [
+        value
+        for value in (result.get("content"), result.get("detailedContent"))
+        if isinstance(value, str)
+    ]
+    return "\n".join(parts)
+
+
+def _is_root_event(event: dict[str, Any]) -> bool:
+    return not event.get("agentId")
+
+
+def _atomic_write(path: Path, payload: bytes, *, replace: bool = False) -> None:
+    path = path.resolve()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.exists() and not replace:
+        raise EvidenceError(f"refusing to overwrite existing artifact: {path}")
+    temp = path.with_name(f".{path.name}.{os.getpid()}.{secrets.token_hex(6)}.tmp")
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+    descriptor = os.open(temp, flags, 0o600)
+    try:
+        with os.fdopen(descriptor, "wb") as handle:
+            handle.write(payload)
+            handle.flush()
+            os.fsync(handle.fileno())
+        if path.exists() and not replace:
+            raise EvidenceError(f"refusing to overwrite existing artifact: {path}")
+        os.replace(temp, path)
+    finally:
+        try:
+            temp.unlink()
+        except FileNotFoundError:
+            pass
+
+
+def _write_json(path: Path, data: dict[str, Any], *, replace: bool = False) -> None:
+    _atomic_write(path, json.dumps(data, indent=2, sort_keys=True, ensure_ascii=False).encode() + b"\n", replace=replace)
+
+
+def _load_json(path: Path) -> dict[str, Any]:
+    _safe_regular_file(path)
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise EvidenceError(f"invalid JSON artifact: {path}") from exc
+    if not isinstance(value, dict):
+        raise EvidenceError(f"JSON artifact must be an object: {path}")
+    return value
+
+
+def _iter_session_logs(root: Path) -> Iterable[Path]:
+    if not root.is_dir():
+        return []
+    return sorted(root.glob("*/events.jsonl"))
+
+
+def create_challenge(
+    *,
+    output: Path,
+    binding: str,
+    cwd: Path,
+    session_root: Path,
+    max_age_seconds: int,
+    replace: bool = False,
+) -> dict[str, Any]:
+    """Bind this helper invocation to one current root Copilot session."""
+
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.:-]{15,127}", binding):
+        raise EvidenceError("--binding must be a 16..128 character stable token")
+    canonical_cwd = str(cwd.resolve())
+    now = datetime.now(timezone.utc)
+    candidates: list[tuple[Path, bytes, EventRecord, EventRecord, str, str]] = []
+
+    for event_path in _iter_session_logs(session_root.resolve()):
+        try:
+            raw, records = _read_event_log(event_path)
+            session_id, session_cwd = _session_metadata(records)
+        except EvidenceError:
+            continue
+        if session_cwd != canonical_cwd:
+            continue
+        for record in records:
+            event = record.event
+            if event.get("type") != "tool.execution_start" or not _is_root_event(event):
+                continue
+            data = event.get("data") or {}
+            if str(data.get("toolName") or "").lower() not in {"bash", "shell", "powershell"}:
+                continue
+            model = data.get("model")
+            if not isinstance(model, str) or not model.strip():
+                continue
+            age = (now - _parse_timestamp(event.get("timestamp"))).total_seconds()
+            if age < -5 or age > max_age_seconds:
+                continue
+            argument_text = _event_arguments_text(event)
+            if binding not in argument_text or "marker" not in argument_text:
+                continue
+            tool_call_id = data.get("toolCallId")
+            marker_json = json.dumps(
+                {"schema": CHALLENGE_SCHEMA, "status": "marker", "binding": binding},
+                sort_keys=True,
+                ensure_ascii=False,
+            )
+            completions = [
+                candidate
+                for candidate in records
+                if candidate.event.get("type") == "tool.execution_complete"
+                and _is_root_event(candidate.event)
+                and (candidate.event.get("data") or {}).get("toolCallId") == tool_call_id
+                and (candidate.event.get("data") or {}).get("success") is True
+                and marker_json in _tool_result_text(candidate.event)
+            ]
+            if len(completions) != 1 or completions[0].end_offset <= record.end_offset:
+                continue
+            candidates.append(
+                (event_path.resolve(), raw, record, completions[0], session_id, model.strip())
+            )
+
+    if not candidates:
+        raise EvidenceError(
+            "binding marker is not present in a current Copilot root session event",
+            code=3,
+        )
+    if len(candidates) != 1:
+        raise EvidenceError(
+            f"ambiguous Copilot session binding: found {len(candidates)} matching events",
+            code=4,
+        )
+
+    event_path, raw, record, completion, session_id, executor_model = candidates[0]
+    executor_family = derive_model_family(executor_model)
+    if executor_family not in KNOWN_FAMILIES:
+        raise EvidenceError(f"host-reported executor model has unknown family: {executor_model}", code=5)
+    event = record.event
+    tool_call_id = (event.get("data") or {}).get("toolCallId")
+    event_id = event.get("id")
+    if not isinstance(tool_call_id, str) or not tool_call_id:
+        raise EvidenceError("challenge tool event is missing toolCallId")
+    if not isinstance(event_id, str) or not event_id:
+        raise EvidenceError("challenge tool event is missing id")
+
+    completion_id = completion.event.get("id")
+    if not isinstance(completion_id, str) or not completion_id:
+        raise EvidenceError("challenge marker completion is missing id")
+    prefix = raw[: completion.end_offset]
+    challenge = {
+        "schema": CHALLENGE_SCHEMA,
+        "status": "bound",
+        "binding": binding,
+        "nonce": secrets.token_urlsafe(24),
+        "issued_at": now.isoformat().replace("+00:00", "Z"),
+        "cwd": canonical_cwd,
+        "session_id": session_id,
+        "session_events": str(event_path),
+        "challenge_event_id": event_id,
+        "challenge_completion_event_id": completion_id,
+        "challenge_tool_call_id": tool_call_id,
+        "challenge_event_timestamp": event.get("timestamp"),
+        "executor_model": executor_model,
+        "executor_family": executor_family,
+        "event_prefix_bytes": len(prefix),
+        "event_prefix_sha256": _sha256(prefix),
+    }
+    _write_json(output, challenge, replace=replace)
+    return challenge
+
+
+def _require_string(data: dict[str, Any], key: str) -> str:
+    value = data.get(key)
+    if not isinstance(value, str) or not value:
+        raise EvidenceError(f"artifact is missing non-empty string field: {key}")
+    return value
+
+
+def _validate_challenge_prefix(challenge: dict[str, Any]) -> tuple[Path, bytes, list[EventRecord]]:
+    if challenge.get("schema") != CHALLENGE_SCHEMA or challenge.get("status") != "bound":
+        raise EvidenceError("unsupported or unbound Copilot challenge")
+    event_path = Path(_require_string(challenge, "session_events")).resolve()
+    raw, records = _read_event_log(event_path)
+    prefix_length = challenge.get("event_prefix_bytes")
+    if not isinstance(prefix_length, int) or prefix_length <= 0 or prefix_length > len(raw):
+        raise EvidenceError("challenge event prefix length is invalid")
+    if _sha256(raw[:prefix_length]) != _require_string(challenge, "event_prefix_sha256"):
+        raise EvidenceError("Copilot challenge event prefix changed after binding")
+    session_id, session_cwd = _session_metadata(records)
+    if session_id != _require_string(challenge, "session_id"):
+        raise EvidenceError("challenge session id does not match its event log")
+    if session_cwd != str(Path(_require_string(challenge, "cwd")).resolve()):
+        raise EvidenceError("challenge cwd does not match its event log")
+
+    matches = [
+        record
+        for record in records
+        if record.end_offset <= prefix_length
+        and record.event.get("id") == challenge.get("challenge_event_id")
+        and record.event.get("type") == "tool.execution_start"
+    ]
+    if len(matches) != 1:
+        raise EvidenceError("challenge root tool event is missing or duplicated")
+    event = matches[0].event
+    data = event.get("data") or {}
+    if not _is_root_event(event):
+        raise EvidenceError("challenge was not issued by the root Copilot agent")
+    if data.get("toolCallId") != challenge.get("challenge_tool_call_id"):
+        raise EvidenceError("challenge tool-call id mismatch")
+    if data.get("model") != challenge.get("executor_model"):
+        raise EvidenceError("challenge executor model mismatch")
+    if _require_string(challenge, "binding") not in _event_arguments_text(event):
+        raise EvidenceError("challenge binding token is absent from the host tool event")
+    completion_matches = [
+        record
+        for record in records
+        if record.end_offset <= prefix_length
+        and record.event.get("id") == challenge.get("challenge_completion_event_id")
+        and record.event.get("type") == "tool.execution_complete"
+    ]
+    if len(completion_matches) != 1:
+        raise EvidenceError("challenge marker completion is missing or duplicated")
+    completion = completion_matches[0]
+    completion_data = completion.event.get("data") or {}
+    expected_marker = json.dumps(
+        {
+            "schema": CHALLENGE_SCHEMA,
+            "status": "marker",
+            "binding": _require_string(challenge, "binding"),
+        },
+        sort_keys=True,
+        ensure_ascii=False,
+    )
+    if (
+        not _is_root_event(completion.event)
+        or completion_data.get("toolCallId") != challenge.get("challenge_tool_call_id")
+        or completion_data.get("success") is not True
+        or expected_marker not in _tool_result_text(completion.event)
+        or completion.end_offset <= matches[0].end_offset
+    ):
+        raise EvidenceError("challenge marker completion does not prove a successful marker call")
+    return event_path, raw, records
+
+
+def validate_challenge_artifact(path: Path) -> dict[str, Any]:
+    """Revalidate a bound challenge before selecting an external fallback."""
+
+    challenge = _load_json(path.resolve())
+    _validate_challenge_prefix(challenge)
+    executor_model = _require_string(challenge, "executor_model")
+    executor_family = derive_model_family(executor_model)
+    if executor_family not in KNOWN_FAMILIES:
+        raise EvidenceError(
+            f"host-reported executor model has unknown family: {executor_model}"
+        )
+    if challenge.get("executor_family") != executor_family:
+        raise EvidenceError("challenge executor family does not match its host model")
+    return challenge
+
+
+def _native_prompt(arguments: dict[str, Any]) -> str:
+    for key in ("prompt", "query", "input"):
+        value = arguments.get(key)
+        if isinstance(value, str):
+            return value
+    return ""
+
+
+def _is_rubber_duck_invocation(event: dict[str, Any], nonce: str) -> bool:
+    if event.get("type") != "tool.execution_start" or not _is_root_event(event):
+        return False
+    data = event.get("data") or {}
+    arguments = data.get("arguments") or {}
+    if not isinstance(arguments, dict):
+        return False
+    tool_name = str(data.get("toolName") or "").lower().replace("_", "-")
+    agent_name = arguments.get("agent_type", arguments.get("agentType"))
+    native_agent = tool_name == "task" and agent_name == "rubber-duck"
+    native_tool = tool_name in {"rubber-duck", "rubberduck"}
+    if not (native_agent or native_tool):
+        return False
+    marker = re.compile(rf"(?m)^{re.escape(NONCE_PREFIX + nonce)}\s*$")
+    return marker.search(_native_prompt(arguments)) is not None
+
+
+def _extract_response(result: Any) -> str:
+    if not isinstance(result, dict):
+        raise EvidenceError("native reviewer tool result is not an object")
+    content = result.get("content")
+    detailed = result.get("detailedContent")
+    if not isinstance(content, str) or not content.strip():
+        raise EvidenceError("native reviewer tool result has no text content")
+    if (
+        isinstance(detailed, str)
+        and len(detailed) >= len(content)
+        and "(Full response provided to agent)" not in detailed
+    ):
+        return detailed
+    return content
+
+
+def _evidence_identity(data: dict[str, Any]) -> str:
+    fields = {
+        "session_id": data.get("session_id"),
+        "challenge_event_id": data.get("challenge_event_id"),
+        "tool_call_id": data.get("tool_call_id"),
+        "executor_model": data.get("executor_model"),
+        "reviewer_model": data.get("reviewer_model"),
+        "response_sha256": data.get("response_sha256"),
+        "event_prefix_sha256": data.get("event_prefix_sha256"),
+    }
+    return f"cne_{_sha256(_canonical_json(fields))[:32]}"
+
+
+def verify_native_review(
+    *,
+    challenge_path: Path,
+    output: Path,
+    response_output: Path,
+    replace: bool = False,
+) -> dict[str, Any]:
+    """Verify and extract one native rubber-duck review from host events."""
+
+    challenge = _load_json(challenge_path.resolve())
+    event_path, raw, records = _validate_challenge_prefix(challenge)
+    nonce = _require_string(challenge, "nonce")
+    challenge_time = _parse_timestamp(challenge.get("challenge_event_timestamp"))
+
+    invocations = [
+        record
+        for record in records
+        if _parse_timestamp(record.event.get("timestamp")) >= challenge_time
+        and _is_rubber_duck_invocation(record.event, nonce)
+    ]
+    if len(invocations) != 1:
+        raise EvidenceError(
+            f"expected exactly one nonce-bound native rubber-duck invocation, found {len(invocations)}",
+            code=6,
+        )
+    invocation = invocations[0]
+    challenge_prefix_length = challenge.get("event_prefix_bytes")
+    if not isinstance(challenge_prefix_length, int) or invocation.end_offset <= challenge_prefix_length:
+        raise EvidenceError("native rubber-duck invocation does not follow the bound challenge")
+    invocation_data = invocation.event.get("data") or {}
+    tool_call_id = invocation_data.get("toolCallId")
+    if not isinstance(tool_call_id, str) or not tool_call_id:
+        raise EvidenceError("native rubber-duck invocation is missing toolCallId")
+
+    executor_model = invocation_data.get("model")
+    if not isinstance(executor_model, str) or not executor_model:
+        raise EvidenceError("native invocation is missing host-reported executor model")
+    if executor_model != challenge.get("executor_model"):
+        raise EvidenceError("executor model changed between challenge and native review")
+
+    starts = [
+        record
+        for record in records
+        if record.event.get("type") == "subagent.started"
+        and (record.event.get("data") or {}).get("toolCallId") == tool_call_id
+    ]
+    completions = [
+        record
+        for record in records
+        if record.event.get("type") == "subagent.completed"
+        and (record.event.get("data") or {}).get("toolCallId") == tool_call_id
+    ]
+    failures = [
+        record
+        for record in records
+        if record.event.get("type") == "subagent.failed"
+        and (record.event.get("data") or {}).get("toolCallId") == tool_call_id
+    ]
+    tool_completions = [
+        record
+        for record in records
+        if record.event.get("type") == "tool.execution_complete"
+        and (record.event.get("data") or {}).get("toolCallId") == tool_call_id
+    ]
+    if failures:
+        raise EvidenceError("native rubber-duck subagent failed", code=7)
+    if (
+        len(tool_completions) == 1
+        and (tool_completions[0].event.get("data") or {}).get("success") is not True
+    ):
+        raise EvidenceError("native rubber-duck tool execution did not succeed", code=7)
+    if len(starts) != 1 or len(completions) != 1 or len(tool_completions) != 1:
+        raise EvidenceError(
+            "native rubber-duck lifecycle is incomplete or ambiguous "
+            f"(started={len(starts)}, completed={len(completions)}, tool_complete={len(tool_completions)})",
+            code=7,
+        )
+    start_data = starts[0].event.get("data") or {}
+    completion_data = completions[0].event.get("data") or {}
+    tool_completion_data = tool_completions[0].event.get("data") or {}
+    if start_data.get("agentName") != "rubber-duck" or completion_data.get("agentName") != "rubber-duck":
+        raise EvidenceError("nonce-bound task was not completed by the rubber-duck subagent")
+    if starts[0].event.get("agentId") != tool_call_id or completions[0].event.get("agentId") != tool_call_id:
+        raise EvidenceError("rubber-duck lifecycle is not bound to its child agent id")
+    if not (
+        invocation.end_offset < starts[0].end_offset
+        <= completions[0].end_offset
+        < tool_completions[0].end_offset
+    ):
+        raise EvidenceError("native rubber-duck lifecycle events are out of order")
+    completion_executor_model = tool_completion_data.get("model")
+    if isinstance(completion_executor_model, str) and completion_executor_model != executor_model:
+        raise EvidenceError("root executor model changed before native tool completion")
+
+    start_model = start_data.get("model")
+    reviewer_model = completion_data.get("model") or start_model
+    if not isinstance(reviewer_model, str) or not reviewer_model:
+        raise EvidenceError("native reviewer completion is missing its resolved model")
+    if isinstance(start_model, str) and start_model and start_model != reviewer_model:
+        raise EvidenceError("native reviewer model changed within one subagent lifecycle")
+
+    response = _extract_response(tool_completion_data.get("result"))
+    response_bytes = response.encode("utf-8")
+    _atomic_write(response_output, response_bytes, replace=replace)
+
+    executor_family = derive_model_family(executor_model)
+    reviewer_family = derive_model_family(reviewer_model)
+    if executor_family not in KNOWN_FAMILIES or reviewer_family not in KNOWN_FAMILIES:
+        status = "rejected"
+        reason = "unknown-model-family"
+    elif executor_family == reviewer_family:
+        status = "rejected"
+        reason = "same-model-family"
+    else:
+        status = "verified"
+        reason = "host-event-verified-cross-family"
+
+    final_offset = max(invocation.end_offset, starts[0].end_offset, completions[0].end_offset, tool_completions[0].end_offset)
+    prefix = raw[:final_offset]
+    evidence: dict[str, Any] = {
+        "schema": EVIDENCE_SCHEMA,
+        "status": status,
+        "reason": reason,
+        "verified_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "binding": challenge.get("binding"),
+        "nonce": nonce,
+        "cwd": challenge.get("cwd"),
+        "session_id": challenge.get("session_id"),
+        "session_events": str(event_path),
+        "challenge_event_id": challenge.get("challenge_event_id"),
+        "challenge_completion_event_id": challenge.get("challenge_completion_event_id"),
+        "challenge_tool_call_id": challenge.get("challenge_tool_call_id"),
+        "tool_call_id": tool_call_id,
+        "agent_name": "rubber-duck",
+        "executor_model": executor_model,
+        "executor_model_source": "host-session-event",
+        "executor_family": executor_family,
+        "reviewer_model": reviewer_model,
+        "reviewer_model_source": "host-session-event",
+        "reviewer_family": reviewer_family,
+        "family_relation": "different" if executor_family != reviewer_family and "unknown" not in {executor_family, reviewer_family} else "same" if executor_family == reviewer_family and executor_family != "unknown" else "unknown",
+        "independence_verified": status == "verified",
+        "response_path": str(response_output.resolve()),
+        "response_sha256": _sha256(response_bytes),
+        "event_prefix_bytes": len(prefix),
+        "event_prefix_sha256": _sha256(prefix),
+    }
+    evidence["evidence_id"] = _evidence_identity(evidence)
+    _write_json(output, evidence, replace=replace)
+    if status != "verified":
+        raise PolicyRejected(f"native reviewer evidence rejected: {reason}")
+    return evidence
+
+
+def validate_evidence_artifact(path: Path) -> dict[str, Any]:
+    """Revalidate a verified evidence artifact against its event-log prefix."""
+
+    evidence = _load_json(path.resolve())
+    if evidence.get("schema") != EVIDENCE_SCHEMA:
+        raise EvidenceError("unsupported Copilot native evidence schema")
+    if evidence.get("status") != "verified" or evidence.get("independence_verified") is not True:
+        raise EvidenceError("Copilot native evidence is not verified")
+    if evidence.get("agent_name") != "rubber-duck":
+        raise EvidenceError("evidence agent is not rubber-duck")
+
+    event_path = Path(_require_string(evidence, "session_events")).resolve()
+    raw, records = _read_event_log(event_path)
+    prefix_length = evidence.get("event_prefix_bytes")
+    if not isinstance(prefix_length, int) or prefix_length <= 0 or prefix_length > len(raw):
+        raise EvidenceError("evidence event prefix length is invalid")
+    prefix = raw[:prefix_length]
+    if _sha256(prefix) != _require_string(evidence, "event_prefix_sha256"):
+        raise EvidenceError("Copilot evidence event prefix was modified")
+
+    session_id, session_cwd = _session_metadata(records)
+    if session_id != evidence.get("session_id") or session_cwd != str(Path(_require_string(evidence, "cwd")).resolve()):
+        raise EvidenceError("evidence session metadata mismatch")
+    tool_call_id = _require_string(evidence, "tool_call_id")
+    nonce = _require_string(evidence, "nonce")
+    challenge_matches = [
+        record
+        for record in records
+        if record.end_offset <= prefix_length
+        and record.event.get("id") == evidence.get("challenge_event_id")
+        and record.event.get("type") == "tool.execution_start"
+    ]
+    challenge_completions = [
+        record
+        for record in records
+        if record.end_offset <= prefix_length
+        and record.event.get("id") == evidence.get("challenge_completion_event_id")
+        and record.event.get("type") == "tool.execution_complete"
+    ]
+    if len(challenge_matches) != 1 or len(challenge_completions) != 1:
+        raise EvidenceError("evidence challenge marker lifecycle is missing or duplicated")
+    challenge_data = challenge_matches[0].event.get("data") or {}
+    challenge_completion_data = challenge_completions[0].event.get("data") or {}
+    expected_marker = json.dumps(
+        {
+            "schema": CHALLENGE_SCHEMA,
+            "status": "marker",
+            "binding": _require_string(evidence, "binding"),
+        },
+        sort_keys=True,
+        ensure_ascii=False,
+    )
+    if (
+        not _is_root_event(challenge_matches[0].event)
+        or not _is_root_event(challenge_completions[0].event)
+        or challenge_data.get("toolCallId") != evidence.get("challenge_tool_call_id")
+        or challenge_completion_data.get("toolCallId") != evidence.get("challenge_tool_call_id")
+        or challenge_completion_data.get("success") is not True
+        or expected_marker not in _tool_result_text(challenge_completions[0].event)
+        or challenge_data.get("model") != evidence.get("executor_model")
+        or challenge_completions[0].end_offset <= challenge_matches[0].end_offset
+    ):
+        raise EvidenceError("evidence challenge marker lifecycle is invalid")
+
+    prefix_records = [record for record in records if record.end_offset <= prefix_length]
+    invocations = [record for record in prefix_records if _is_rubber_duck_invocation(record.event, nonce)]
+    invocations = [record for record in invocations if (record.event.get("data") or {}).get("toolCallId") == tool_call_id]
+    starts = [record for record in prefix_records if record.event.get("type") == "subagent.started" and (record.event.get("data") or {}).get("toolCallId") == tool_call_id]
+    completions = [record for record in prefix_records if record.event.get("type") == "subagent.completed" and (record.event.get("data") or {}).get("toolCallId") == tool_call_id]
+    failures = [record for record in prefix_records if record.event.get("type") == "subagent.failed" and (record.event.get("data") or {}).get("toolCallId") == tool_call_id]
+    tool_completions = [record for record in prefix_records if record.event.get("type") == "tool.execution_complete" and (record.event.get("data") or {}).get("toolCallId") == tool_call_id]
+    if not (len(invocations) == len(starts) == len(completions) == len(tool_completions) == 1):
+        raise EvidenceError("evidence lifecycle events are missing or duplicated")
+    if failures:
+        raise EvidenceError("evidence contains a failed native reviewer lifecycle")
+    start_data = starts[0].event.get("data") or {}
+    completion_data = completions[0].event.get("data") or {}
+    tool_data = tool_completions[0].event.get("data") or {}
+    if start_data.get("agentName") != "rubber-duck" or completion_data.get("agentName") != "rubber-duck":
+        raise EvidenceError("evidence lifecycle agent mismatch")
+    if starts[0].event.get("agentId") != tool_call_id or completions[0].event.get("agentId") != tool_call_id:
+        raise EvidenceError("evidence child agent id mismatch")
+    if not (
+        challenge_completions[0].end_offset < invocations[0].end_offset
+        < starts[0].end_offset
+        <= completions[0].end_offset
+        < tool_completions[0].end_offset
+    ):
+        raise EvidenceError("evidence lifecycle events are out of order")
+    if not tool_data.get("success"):
+        raise EvidenceError("evidence tool completion is not successful")
+    executor_model = (invocations[0].event.get("data") or {}).get("model")
+    reviewer_model = completion_data.get("model") or start_data.get("model")
+    if executor_model != evidence.get("executor_model") or reviewer_model != evidence.get("reviewer_model"):
+        raise EvidenceError("evidence model ids differ from host lifecycle events")
+    if start_data.get("model") not in {None, "", reviewer_model}:
+        raise EvidenceError("evidence reviewer model changed within its lifecycle")
+    if tool_data.get("model") not in {None, "", executor_model}:
+        raise EvidenceError("evidence executor model changed before tool completion")
+    executor_family = derive_model_family(str(executor_model or ""))
+    reviewer_family = derive_model_family(str(reviewer_model or ""))
+    if executor_family not in KNOWN_FAMILIES or reviewer_family not in KNOWN_FAMILIES or executor_family == reviewer_family:
+        raise EvidenceError("evidence no longer establishes a known cross-family pair")
+    if evidence.get("executor_family") != executor_family or evidence.get("reviewer_family") != reviewer_family:
+        raise EvidenceError("evidence family fields do not match its model ids")
+    if evidence.get("family_relation") != "different":
+        raise EvidenceError("evidence family relation is not different")
+    if evidence.get("executor_model_source") != "host-session-event" or evidence.get("reviewer_model_source") != "host-session-event":
+        raise EvidenceError("evidence model sources are not host session events")
+
+    response = _extract_response(tool_data.get("result"))
+    response_path = Path(_require_string(evidence, "response_path")).resolve()
+    _safe_regular_file(response_path)
+    response_bytes = response_path.read_bytes()
+    if response_bytes != response.encode("utf-8") or _sha256(response_bytes) != evidence.get("response_sha256"):
+        raise EvidenceError("native reviewer response artifact does not match the host tool result")
+    if _evidence_identity(evidence) != evidence.get("evidence_id"):
+        raise EvidenceError("native evidence id does not match its bound fields")
+    return evidence
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    marker = subparsers.add_parser("marker", help="emit a binding marker in its own root tool call")
+    marker.add_argument("--binding", required=True)
+
+    challenge = subparsers.add_parser("challenge", help="bind the current Copilot root session")
+    challenge.add_argument("--output", type=Path, required=True)
+    challenge.add_argument("--binding", required=True)
+    challenge.add_argument("--cwd", type=Path, default=Path.cwd())
+    challenge.add_argument("--session-root", type=Path, default=Path.home() / ".copilot" / "session-state")
+    challenge.add_argument("--max-age-seconds", type=int, default=60)
+    challenge.add_argument("--replace", action="store_true")
+
+    verify = subparsers.add_parser("verify", help="verify one completed rubber-duck subagent call")
+    verify.add_argument("--challenge", type=Path, required=True)
+    verify.add_argument("--output", type=Path, required=True)
+    verify.add_argument("--response-output", type=Path, required=True)
+    verify.add_argument("--replace", action="store_true")
+
+    validate_challenge = subparsers.add_parser(
+        "validate-challenge",
+        help="revalidate a challenge before an opposite-family fallback",
+    )
+    validate_challenge.add_argument("--challenge", type=Path, required=True)
+
+    validate = subparsers.add_parser("validate", help="revalidate an existing evidence artifact")
+    validate.add_argument("--evidence", type=Path, required=True)
+    return parser
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    try:
+        if args.command == "marker":
+            if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.:-]{15,127}", args.binding):
+                raise EvidenceError("--binding must be a 16..128 character stable token")
+            result = {"schema": CHALLENGE_SCHEMA, "status": "marker", "binding": args.binding}
+        elif args.command == "challenge":
+            if args.max_age_seconds < 1 or args.max_age_seconds > 600:
+                raise EvidenceError("--max-age-seconds must be within 1..600")
+            result = create_challenge(
+                output=args.output,
+                binding=args.binding,
+                cwd=args.cwd,
+                session_root=args.session_root,
+                max_age_seconds=args.max_age_seconds,
+                replace=args.replace,
+            )
+        elif args.command == "verify":
+            result = verify_native_review(
+                challenge_path=args.challenge,
+                output=args.output,
+                response_output=args.response_output,
+                replace=args.replace,
+            )
+        elif args.command == "validate-challenge":
+            result = validate_challenge_artifact(args.challenge)
+        else:
+            result = validate_evidence_artifact(args.evidence)
+        print(json.dumps(result, sort_keys=True, ensure_ascii=False))
+        return 0
+    except EvidenceError as exc:
+        print(json.dumps({"status": "error", "error": str(exc), "exit_code": exc.code}), file=sys.stderr)
+        return exc.code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())