umbra-core 0.1.0__py3-none-any.whl

umbra_core/__init__.py

@@ -0,0 +1,101 @@
+"""umbra-core — an agent-agnostic change-control plane for coding agents."""
+from .executors.base import ExecutionResult, Executor
+from .executors.claude_code import ClaudeCodeExecutor
+from .executors.codex import CodexExecutor
+from .executors.null import NullExecutor
+from .executors.registry import (
+    available_executors,
+    get_executor,
+    resolve_available,
+)
+from .pipeline import (
+    AUTHORITY,
+    AUTHORITY_LABEL,
+    AdmissionReport,
+    ChecksReport,
+    Contract,
+    ContractResult,
+    InMemoryLogStore,
+    InMemoryPassportStore,
+    JsonFileLogStore,
+    JsonFilePassportStore,
+    PassportError,
+    PassportStatus,
+    TransparencyLog,
+    TrustBoundaryResult,
+    VerifierReport,
+    build_receipt,
+    default_contract,
+    evaluate_contract,
+    evaluate_passport,
+    gate_pr,
+    issue_passport,
+    load_contract,
+    merkle_root,
+    public_key_b64,
+    revoke,
+    run_admission,
+    run_required_checks,
+    sanitize_checkout,
+    scan_repository_text,
+    sign,
+    to_slsa_provenance,
+    verify_change,
+    verify_inclusion,
+    verify_receipt,
+    verify_signature,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # executors
+    "Executor",
+    "ExecutionResult",
+    "CodexExecutor",
+    "ClaudeCodeExecutor",
+    "NullExecutor",
+    "available_executors",
+    "get_executor",
+    "resolve_available",
+    # pipeline
+    "run_admission",
+    "AdmissionReport",
+    "AUTHORITY",
+    "AUTHORITY_LABEL",
+    "Contract",
+    "ContractResult",
+    "default_contract",
+    "evaluate_contract",
+    "load_contract",
+    "ChecksReport",
+    "run_required_checks",
+    "TrustBoundaryResult",
+    "scan_repository_text",
+    "sanitize_checkout",
+    "VerifierReport",
+    "verify_change",
+    "build_receipt",
+    "verify_receipt",
+    "verify_signature",
+    "sign",
+    "public_key_b64",
+    # passport / emergency brake
+    "issue_passport",
+    "gate_pr",
+    "revoke",
+    "evaluate_passport",
+    "PassportStatus",
+    "PassportError",
+    "InMemoryPassportStore",
+    "JsonFilePassportStore",
+    # SLSA / in-toto provenance
+    "to_slsa_provenance",
+    # transparency log
+    "TransparencyLog",
+    "InMemoryLogStore",
+    "JsonFileLogStore",
+    "merkle_root",
+    "verify_inclusion",
+    "__version__",
+]

umbra_core/cli.py

@@ -0,0 +1,199 @@
+"""The ``umbra`` command-line interface.
+
+One entry point over the agent-agnostic core, so the same governance runs on a
+developer's machine, in a git hook, and in CI:
+
+    umbra admit  <repo> --agent claude-code --mission "..."   # govern an agent's change
+    umbra verify <receipt.json>                                # verify a signed receipt
+    umbra brake  <owner> <repo> --store passports.json         # Emergency Brake -> L0
+    umbra provenance <receipt.json>                            # emit SLSA/in-toto statement
+
+``admit`` exits non-zero unless the run earns branch-PR authority (L2), so it
+gates a pre-push hook or a CI required check. ``--min-authority`` tunes the bar.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from . import (
+    JsonFilePassportStore,
+    build_receipt,
+    get_executor,
+    issue_passport,
+    resolve_available,
+    revoke,
+    run_admission,
+    to_slsa_provenance,
+    verify_receipt,
+)
+
+
+def _print(obj: Any, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(obj, indent=2, default=str))
+
+
+def _receipt_from_report(report) -> dict[str, Any]:
+    return build_receipt(
+        repo=report.repo, base_commit=report.base_commit, contract=report.contract,
+        contract_result=report.contract_result, verifier=report.verifier,
+        trust_boundary=report.trust_boundary, proposed_change=report.proposed_change,
+        providers=report.providers, authority_level=report.authority_level,
+        authority=report.authority, executor=report.executor, diff=report.diff,
+        checks=report.checks, baseline_checks=report.baseline_checks,
+        check_diagnosis=report.check_diagnosis, model_identity=report.model_identity,
+        context_manifest=report.context_manifest, outcome=report.outcome,
+    )
+
+
+def cmd_admit(args: argparse.Namespace) -> int:
+    repo_path = Path(args.repo).resolve()
+    if not repo_path.is_dir():
+        print(f"error: {repo_path} is not a directory", file=sys.stderr)
+        return 2
+
+    # Resolve the executor: explicit --agent, else first available, else fail clearly.
+    if args.agent:
+        try:
+            executor = get_executor(args.agent)
+        except ValueError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+        if not executor.available():
+            print(
+                f"error: agent {args.agent!r} is not available. Enable + authenticate it "
+                f"(e.g. UMBRA_ENABLE_CLAUDE_CODE=true / UMBRA_ENABLE_CODEX_CLI=true).",
+                file=sys.stderr,
+            )
+            return 2
+    else:
+        executor = resolve_available(args.prefer.split(",") if args.prefer else None)
+        if executor is None:
+            print(
+                "error: no coding agent is available. Enable one with "
+                "UMBRA_ENABLE_CLAUDE_CODE=true or UMBRA_ENABLE_CODEX_CLI=true, "
+                "or pass --agent.",
+                file=sys.stderr,
+            )
+            return 2
+
+    report = run_admission(repo_path, args.label or repo_path.name, args.mission, executor)
+    envelope = _receipt_from_report(report)
+
+    # Persist the earned-authority passport when a store is given.
+    if args.store:
+        store = JsonFilePassportStore(args.store)
+        store.save(args.owner, report.repo, issue_passport(report, receipt_hash=envelope["canonical_hash"]))
+
+    if args.receipt_out:
+        Path(args.receipt_out).write_text(json.dumps(envelope, indent=2, default=str))
+
+    payload = {"report": report.to_public(), "receipt": envelope}
+    if args.json:
+        _print(payload, True)
+    else:
+        print(f"repo        : {report.repo}")
+        print(f"agent       : {report.executor}")
+        print(f"changed     : {', '.join(report.changed_files) or '(none)'}")
+        print(f"contract    : {'PASS' if report.contract_result['passed'] else 'VIOLATED'}")
+        tb = report.trust_boundary
+        print(f"trust bound.: {'clean' if tb['clean'] else str(tb['quarantined_count']) + ' line(s) quarantined'}")
+        if report.verifier:
+            print(f"verifier    : {'BLOCKED' if report.verifier['blocked'] else 'reviewable'}")
+        checks = report.checks or {}
+        print(f"checks      : ran={checks.get('ran')} all_passed={checks.get('all_passed')} enforcement={checks.get('enforcement')}")
+        print(f"authority   : L{report.authority_level} ({report.authority})")
+        print(f"outcome     : {report.outcome}")
+        print(f"receipt     : {envelope['canonical_hash']}  (key_ephemeral={envelope['key_ephemeral']})")
+
+    # Exit code gates hooks/CI: non-zero unless the run met the authority bar.
+    return 0 if report.authority_level >= args.min_authority else 1
+
+
+def cmd_verify(args: argparse.Namespace) -> int:
+    try:
+        envelope = json.loads(Path(args.receipt).read_text())
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"error: cannot read receipt: {exc}", file=sys.stderr)
+        return 2
+    result = verify_receipt(envelope, expected_public_key=args.public_key)
+    if args.json:
+        _print(result, True)
+    else:
+        ok = result["verified"]
+        print(("VERIFIED" if ok else "NOT VERIFIED") + f"  (issued_by_umbra={result['issued_by_umbra']}, hash_matches={result['hash_matches']})")
+    return 0 if result["verified"] else 1
+
+
+def cmd_brake(args: argparse.Namespace) -> int:
+    store = JsonFilePassportStore(args.store)
+    rec = revoke(store, args.owner, args.repo, reason=args.reason)
+    if args.json:
+        _print(rec, True)
+    else:
+        print(f"Emergency Brake applied: {args.owner}/{args.repo} -> L{rec['authority_level']} ({rec['authority']})")
+    return 0
+
+
+def cmd_provenance(args: argparse.Namespace) -> int:
+    try:
+        envelope = json.loads(Path(args.receipt).read_text())
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"error: cannot read receipt: {exc}", file=sys.stderr)
+        return 2
+    stmt = to_slsa_provenance(envelope)
+    print(json.dumps(stmt, indent=2, default=str))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="umbra", description="Agent-agnostic change-control plane for coding agents.")
+    parser.add_argument("--json", action="store_true", help="Machine-readable JSON output.")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_admit = sub.add_parser("admit", help="Run the admission pipeline: govern an agent's change to a repo.")
+    p_admit.add_argument("repo", help="Path to a git checkout to run the agent in.")
+    p_admit.add_argument("--mission", required=True, help="The bounded task handed to the agent.")
+    p_admit.add_argument("--agent", help="Force a specific agent (e.g. codex-cli, claude-code, or any registered executor).")
+    p_admit.add_argument("--prefer", help="Comma-separated preference order when auto-selecting (e.g. 'claude-code,codex-cli').")
+    p_admit.add_argument("--label", help="Repo label for the receipt (defaults to the directory name).")
+    p_admit.add_argument("--owner", default="local", help="Owner key for the passport store.")
+    p_admit.add_argument("--store", help="Path to a JSON passport store to persist the earned authority.")
+    p_admit.add_argument("--receipt-out", help="Write the signed receipt envelope to this file.")
+    p_admit.add_argument("--min-authority", type=int, default=2, help="Exit non-zero unless the run earns at least this level (default 2 = branch-PR).")
+    p_admit.set_defaults(func=cmd_admit)
+
+    p_verify = sub.add_parser("verify", help="Verify a signed receipt against a pinned public key.")
+    p_verify.add_argument("receipt", help="Path to a receipt envelope JSON file.")
+    p_verify.add_argument("--public-key", help="Base64 Ed25519 public key to verify against (defaults to this instance's key).")
+    p_verify.set_defaults(func=cmd_verify)
+
+    p_brake = sub.add_parser("brake", help="Emergency Brake: revoke a repo's earned authority to Level 0.")
+    p_brake.add_argument("owner", help="Owner key.")
+    p_brake.add_argument("repo", help="Repo label.")
+    p_brake.add_argument("--store", required=True, help="Path to the JSON passport store.")
+    p_brake.add_argument("--reason", help="Reason recorded with the revocation.")
+    p_brake.set_defaults(func=cmd_brake)
+
+    p_prov = sub.add_parser("provenance", help="Emit an in-toto/SLSA provenance statement for a receipt.")
+    p_prov.add_argument("receipt", help="Path to a receipt envelope JSON file.")
+    p_prov.set_defaults(func=cmd_provenance)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    # Thread the top-level --json down to subcommands.
+    if not hasattr(args, "json"):
+        args.json = False
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

umbra_core/executors/__init__.py

@@ -0,0 +1,16 @@
+from .base import ExecutionResult, Executor
+from .claude_code import ClaudeCodeExecutor
+from .codex import CodexExecutor
+from .null import NullExecutor
+from .registry import available_executors, get_executor, resolve_available
+
+__all__ = [
+    "Executor",
+    "ExecutionResult",
+    "CodexExecutor",
+    "ClaudeCodeExecutor",
+    "NullExecutor",
+    "available_executors",
+    "get_executor",
+    "resolve_available",
+]

umbra_core/executors/_shared.py

@@ -0,0 +1,67 @@
+"""Shared, side-effect-free helpers for executor adapters."""
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+from typing import Callable
+
+Runner = Callable[..., "subprocess.CompletedProcess[str]"]
+
+
+def git(repo_path: Path, args: list[str]) -> str:
+    """Run a read-only git command in the checkout and return stdout."""
+    result = subprocess.run(["git", *args], cwd=repo_path, text=True, capture_output=True, check=False)
+    return result.stdout
+
+
+def changed_files(repo_path: Path) -> list[str]:
+    return [line for line in git(repo_path, ["diff", "--name-only"]).splitlines() if line]
+
+
+def unified_diff(repo_path: Path) -> str:
+    return git(repo_path, ["diff", "--binary"])
+
+
+def sanitize_paths(text: str, repo_path: Path) -> str:
+    """Strip the disposable checkout's absolute path out of agent prose.
+
+    Agents freely embed the absolute temp-dir path in explanations; left raw it
+    leaks the host filesystem layout into user-facing reports. The git diff
+    already uses repo-relative ``a/…``/``b/…`` prefixes, so only free text needs
+    this.
+    """
+    if not text:
+        return text
+    prefixes: set[str] = set()
+    for base in (str(repo_path), str(repo_path.resolve())):
+        prefixes.add(base)
+        if base.startswith("/private/"):
+            prefixes.add(base[len("/private"):])
+        elif base.startswith("/var/"):
+            prefixes.add("/private" + base)
+    for prefix in sorted(prefixes, key=len, reverse=True):
+        text = text.replace(prefix + os.sep, "").replace(prefix, "")
+    return text
+
+
+def bounded_prompt(mission: str, agent_label: str) -> str:
+    """The hard no-authority instruction wrapped around every mission."""
+    return f"""You are {agent_label} working for Umbra in a disposable local checkout.
+Mission: {mission}
+
+Hard rules: never push, commit, create a PR, merge, approve, deploy, force-push,
+or expose a secret. You may inspect and edit only this checkout. Make the minimum
+safe change, run relevant tests, and finish with a concise explanation of changed
+files, exact tests run, and anything that prevented verification."""
+
+
+def reason_prompt(mission: str, agent_label: str) -> str:
+    return f"""You are {agent_label} acting as Umbra's reasoning analyst in a read-only workspace.
+Task:
+{mission}
+
+Rules: Do not edit, create, run, push, or inspect any files. Reason only from the
+text supplied above. Never invent files, line numbers, commit SHAs, CVEs, or
+behavior. If context is insufficient, say so plainly. Respond with a concise,
+well-structured analysis and nothing else."""

umbra_core/executors/base.py

@@ -0,0 +1,108 @@
+"""The agent-agnostic executor interface.
+
+The central idea of umbra-core: a coding agent (Codex, Claude Code, Cursor, …)
+is an *untrusted engine*. It proposes a change inside a disposable checkout; it
+never pushes, commits, or merges, and it can never approve its own authority.
+
+Every agent is adapted to one interface — :class:`Executor` — so the admission
+pipeline (contract → trust boundary → checks → verifier → earned authority →
+signed receipt) treats them identically. Adding a new agent means writing one
+adapter, not touching the governance core.
+"""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+
+@dataclass
+class ExecutionResult:
+    """The auditable, replayable record of a single agent invocation.
+
+    Fields are deliberately provider-neutral so a receipt can bind any agent's
+    output identically. Honesty rule: ``provider`` describes *produced* output,
+    never a mere launch attempt — a failed run is recorded as such, never green.
+    """
+
+    prompt: str
+    summary: str
+    diff: str
+    tests_passed: bool | None
+    files: list[str]
+    # Which agent produced this — e.g. "codex-cli", "claude-code", "cursor",
+    # "deterministic". Never fabricated; a failed run reports "unavailable".
+    executor: str
+    created_at: str
+    command: list[str] | None = None
+    stdout: str = ""
+    error: str | None = None
+    # Provider-attested model provenance for the signed receipt. Kept honest:
+    # "configured" is what we requested, "resolved" stays unavailable unless the
+    # agent explicitly reports the model that ran.
+    model_identity: dict[str, Any] = field(default_factory=dict)
+
+    def as_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+    @classmethod
+    def failed(cls, prompt: str, executor: str, error: str, command: list[str] | None = None) -> "ExecutionResult":
+        return cls(
+            prompt=prompt,
+            summary=f"{executor} did not produce a change: {error}",
+            diff="",
+            tests_passed=False,
+            files=[],
+            executor="unavailable",
+            created_at=datetime.now(UTC).isoformat(),
+            command=command,
+            error=error,
+        )
+
+    @classmethod
+    def disabled(cls, prompt: str, executor: str, reason: str) -> "ExecutionResult":
+        return cls(
+            prompt=prompt,
+            summary=reason,
+            diff="",
+            tests_passed=None,
+            files=[],
+            executor=f"{executor}-disabled",
+            created_at=datetime.now(UTC).isoformat(),
+        )
+
+
+@runtime_checkable
+class Executor(Protocol):
+    """Any coding agent Umbra can govern.
+
+    Implementations wrap a CLI or API (Codex, Claude Code, Cursor, …) behind
+    this single contract. The governance core depends only on this protocol, so
+    it is fully agent-agnostic.
+    """
+
+    #: Stable identifier used in receipts and the provider ledger.
+    name: str
+
+    def available(self) -> bool:
+        """Whether this agent can actually run here (binary present, auth ok).
+
+        Must never raise; a probe failure returns ``False`` so the pipeline can
+        fall back or cap authority rather than crash.
+        """
+        ...
+
+    def propose(self, prompt: str, repo_path: Path, *, read_only: bool = False) -> ExecutionResult:
+        """Run the agent in ``repo_path`` (a disposable checkout) and return the
+        produced change as an :class:`ExecutionResult`.
+
+        The agent MUST be invoked with no push/commit/merge authority and no
+        write credentials. ``read_only`` requests a pure-reasoning pass with no
+        filesystem side effects.
+        """
+        ...
+
+    def model_identity(self) -> dict[str, Any]:
+        """Truthful model provenance for the receipt (never fabricated)."""
+        ...

umbra_core/executors/claude_code.py

@@ -0,0 +1,179 @@
+"""Claude Code executor — adapts the ``claude`` CLI to the Executor protocol.
+
+This is the proof that umbra-core is agent-agnostic: Claude Code is governed by
+the *same* admission pipeline as Codex. It runs headless (``-p``) inside a
+disposable checkout with:
+
+- ``--bare`` — skips CLAUDE.md auto-discovery, so the agent does not silently
+  ingest untrusted repository instruction files. This reinforces Umbra's trust
+  boundary: the agent can't read manipulation Umbra hasn't vetted.
+- ``--disallowed-tools`` — git push/commit/merge and other authority-bearing
+  commands are refused at the tool layer; the agent cannot self-grant authority.
+- the diff is recomputed from ``git`` on the final tree, so the signed change
+  reflects only the agent's real edits.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import subprocess
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from .base import ExecutionResult
+from ._shared import (
+    Runner,
+    bounded_prompt,
+    changed_files,
+    reason_prompt,
+    sanitize_paths,
+    unified_diff,
+)
+
+logger = logging.getLogger("umbra.executor.claude")
+
+# Tools that would let the agent push, merge, or otherwise self-grant authority.
+# Refused at the CLI layer so a governed run can only ever propose a change.
+_DISALLOWED_TOOLS = [
+    "Bash(git push:*)",
+    "Bash(git commit:*)",
+    "Bash(git merge:*)",
+    "Bash(git rebase:*)",
+    "Bash(gh pr *)",
+    "Bash(gh pr create:*)",
+    "Bash(git remote *)",
+    "WebFetch",
+]
+
+
+class ClaudeCodeExecutor:
+    name = "claude-code"
+
+    def __init__(
+        self,
+        runner: Runner = subprocess.run,
+        model: str | None = None,
+    ) -> None:
+        self.runner = runner
+        # Free-form alias/full name (e.g. "opus", "sonnet"); passed only via
+        # --model. No allowlist coupling to a specific vendor catalog.
+        self.model = (model if model is not None else os.getenv("UMBRA_CLAUDE_MODEL") or "").strip() or None
+
+    # --- capability ---------------------------------------------------------
+    def available(self) -> bool:
+        if os.getenv("UMBRA_ENABLE_CLAUDE_CODE", "false").lower() != "true":
+            return False
+        return self._cli_version() is not None
+
+    def _cli_version(self) -> str | None:
+        try:
+            r = self.runner(["claude", "--version"], text=True, capture_output=True, timeout=15, check=False)
+        except (OSError, subprocess.SubprocessError):
+            return None
+        if r is None:
+            return None
+        out = ((getattr(r, "stdout", "") or "") + (getattr(r, "stderr", "") or "")).strip()
+        return out.splitlines()[0].strip() if out else None
+
+    # --- provenance ---------------------------------------------------------
+    def model_identity(self) -> dict[str, Any]:
+        return {
+            "executor": self.name,
+            "cli_version": self._cli_version() or "unavailable",
+            "model_configured": self.model or "claude-default",
+            # Resolved only if the CLI's JSON result reports the model that ran;
+            # filled in _run_cli when observed. Never inferred from --model.
+            "model_resolved": "unavailable",
+            "model_evidence": "cli-argument" if self.model else "claude-default",
+        }
+
+    # --- run ----------------------------------------------------------------
+    def propose(self, prompt: str, repo_path: Path, *, read_only: bool = False) -> ExecutionResult:
+        if not self.available():
+            return ExecutionResult.disabled(
+                prompt, self.name,
+                "Claude Code is disabled. Set UMBRA_ENABLE_CLAUDE_CODE=true and authenticate the `claude` CLI.",
+            )
+        if repo_path is None or not repo_path.is_dir():
+            raise RuntimeError("A checked-out repository is required for ClaudeCodeExecutor.propose()")
+        return self._run_cli(prompt, repo_path, read_only=read_only)
+
+    def _run_cli(self, prompt: str, repo_path: Path, *, read_only: bool) -> ExecutionResult:
+        # acceptEdits lets the agent edit files in the checkout without prompting;
+        # plan mode forbids edits entirely for a read-only reasoning pass.
+        permission_mode = "plan" if read_only else "acceptEdits"
+        model_args = ["--model", self.model] if self.model else []
+        cli_prompt = reason_prompt(prompt, "Claude Code") if read_only else bounded_prompt(prompt, "Claude Code")
+        command = [
+            "claude", "-p", cli_prompt,
+            "--output-format", "json",
+            "--bare",  # do NOT auto-read CLAUDE.md — Umbra's trust boundary owns that
+            "--permission-mode", permission_mode,
+            "--disallowed-tools", *_DISALLOWED_TOOLS,
+            "--add-dir", str(repo_path),
+            *model_args,
+        ]
+        try:
+            completed = self.runner(
+                command, text=True, capture_output=True, timeout=900, check=False, cwd=str(repo_path),
+            )
+        except (OSError, subprocess.SubprocessError) as exc:
+            return ExecutionResult.failed(prompt, self.name, str(exc)[:300], command=command[:2] + ["<prompt>"])
+
+        rc = getattr(completed, "returncode", 1)
+        raw_stdout = getattr(completed, "stdout", "") or ""
+        summary, resolved_model = self._parse_result(raw_stdout)
+
+        diff = unified_diff(repo_path)
+        files = changed_files(repo_path)
+        if not summary:
+            summary = (
+                ("Claude Code completed; see the diff below." if diff else "Claude Code ran and produced no changes.")
+                if rc == 0
+                else f"Claude Code failed (exit {rc})."
+            )
+        if rc != 0:
+            logger.warning("claude -p failed (rc=%s): %s", rc, (getattr(completed, "stderr", "") or "")[-1000:])
+
+        identity = self.model_identity()
+        if resolved_model:
+            identity["model_resolved"] = resolved_model
+            identity["model_evidence"] = "provider-attested"
+
+        return ExecutionResult(
+            prompt=prompt,
+            summary=sanitize_paths(summary, repo_path),
+            diff=diff,
+            tests_passed=rc == 0,
+            files=files,
+            executor=self.name if rc == 0 else "unavailable",
+            created_at=datetime.now(UTC).isoformat(),
+            command=command[:2] + ["<agent prompt redacted from command replay>"] + command[3:],
+            stdout=sanitize_paths(raw_stdout[-12000:], repo_path),
+            error=sanitize_paths((getattr(completed, "stderr", "") or "")[-4000:], repo_path) or None,
+            model_identity=identity,
+        )
+
+    @staticmethod
+    def _parse_result(stdout: str) -> tuple[str, str | None]:
+        """Extract the final assistant text and (if reported) the resolved model
+        from ``--output-format json``. Falls back to raw stdout on any parse
+        failure — we never fabricate a model that ran.
+        """
+        text = (stdout or "").strip()
+        if not text:
+            return "", None
+        try:
+            data = json.loads(text)
+        except (json.JSONDecodeError, ValueError):
+            return text, None
+        summary = ""
+        resolved = None
+        if isinstance(data, dict):
+            summary = str(data.get("result") or data.get("text") or data.get("content") or "").strip()
+            model = data.get("model")
+            if isinstance(model, str) and model.strip():
+                resolved = model.strip()
+        return summary or text, resolved