codetrail-cli 1.4.1__py3-none-any.whl

codetrail/agents/tools.py

@@ -0,0 +1,185 @@
+"""The four tools coding agents call: the map, a brief, a page and the changes (design sections 23.5 and 23.7).
+
+They read only the target's exported `index.json`: never `source/`, the mirror, the guide or the database. They run
+no git, call no assistant and never take the update lock, so a reader's `codetrail update` runs while agents call
+them; each call holds the target's shared in-use lock for its own length, as the page's requests do. Every argument
+is checked before it is used, and a path is only matched against the pages' scopes, never opened.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from collections.abc import Callable, Mapping
+from contextlib import ExitStack
+from datetime import date
+
+from codetrail.agents.convert import limit_words
+from codetrail.agents.export import AgentExport, ExportedPage, read_export
+from codetrail.config import AgentSettings, Paths
+from codetrail.errors import CodetrailError
+from codetrail.generate.outline import in_scope
+from codetrail.guide import PAGE_ID
+from codetrail.lock import target_in_use
+from codetrail.repo.source import safe_path
+
+COMMIT = re.compile(r"[0-9a-f]{7,40}")
+DATE = re.compile(r"\d{4}-\d{2}-\d{2}")
+MAX_PATH_CHARS = 1000
+
+
+class ToolInputError(CodetrailError):
+    """A bad argument: the agent is told what's wrong, as a tool error."""
+
+
+def _schema(properties: dict[str, object], required: list[str]) -> dict[str, object]:
+    return {"type": "object", "properties": properties, "required": required, "additionalProperties": False}
+
+
+PAGE = {"type": "string", "description": "A guide page id, such as areas/api or concepts/contract-first"}
+TOOLS: list[dict[str, object]] = [
+    {
+        "name": "codetrail_map",
+        "description": "Codetrail's map of the repository: its parts, decisions, recent changes and guide pages. Call "
+        "it before starting a task.",
+        "inputSchema": _schema({}, []),
+    },
+    {
+        "name": "codetrail_brief",
+        "description": "The brief for coding agents of a guide page, or of the pages covering a path: key files, "
+        "conventions and the reasons for them. Give a page or a path, not both.",
+        "inputSchema": _schema(
+            {"page": PAGE, "path": {"type": "string", "description": "A path relative to the repository's root"}}, []
+        ),
+    },
+    {
+        "name": "codetrail_page",
+        "description": "A whole guide page, for the full explanation behind a brief.",
+        "inputSchema": _schema({"page": PAGE}, ["page"]),
+    },
+    {
+        "name": "codetrail_changes",
+        "description": "The guide's digests of what changed since a commit or a date, newest first.",
+        "inputSchema": _schema(
+            {
+                "since": {
+                    "type": "string",
+                    "description": "A commit (7 to 40 lower-case hex characters) or a date (YYYY-MM-DD)",
+                }
+            },
+            ["since"],
+        ),
+    },
+]
+ARGUMENTS = {tool["name"]: set(tool["inputSchema"]["properties"]) for tool in TOOLS}  # type: ignore[index]
+
+
+class AgentTools:
+    def __init__(self, paths: Paths, name: str, settings: AgentSettings, repository: str) -> None:
+        self.paths = paths
+        self.name = name
+        self.settings = settings
+        self.repository = repository
+
+    def definitions(self) -> list[dict[str, object]]:
+        """The tools, each saying which repository it covers: the server is registered for the reader, so agents
+        working in other repositories see it too."""
+        scope = f"For {self.name}, the repository at {self.repository}, only; in any other repository don't call it. "
+        return [{**tool, "description": scope + str(tool["description"])} for tool in TOOLS]
+
+    def call(self, tool: str, arguments: Mapping[str, object]) -> str:
+        """The tool's answer; raises ToolInputError for a bad argument and KeyError for an unknown tool."""
+        handlers: dict[str, Callable[[AgentExport, Mapping[str, object]], str]] = {
+            "codetrail_map": lambda export, _arguments: export.map_text,
+            "codetrail_brief": self._brief,
+            "codetrail_page": lambda export, given: _page(export, given["page"]).text,
+            "codetrail_changes": self._changes,
+        }
+        handler = handlers[tool]
+        unknown = set(arguments) - ARGUMENTS[tool]
+        if unknown:
+            raise ToolInputError(f"{tool} takes no {', '.join(sorted(unknown))}.")
+        with ExitStack() as stack:
+            try:
+                stack.enter_context(target_in_use(self.paths, self.name))
+            except CodetrailError:
+                return f"Codetrail no longer has the target {self.name!r}."
+            export = read_export(self.paths.target_data(self.name) / "agents")
+            if export is None:
+                return (f"Codetrail has no context for {self.name} yet: run codetrail update {self.name} or "
+                        f"codetrail agents {self.name}.")  # fmt: skip
+            answer = handler(export, arguments)
+        limit = self.settings.max_response_words
+        text, left_out = limit_words(answer.rstrip(), limit)
+        if left_out:
+            text += f"\n\n(cut at {limit} words; ask for one page with codetrail_page or codetrail_brief.)"
+        return f"{text}\n\nDescribes {export.commit[:12]}.\n"
+
+    def _brief(self, export: AgentExport, arguments: Mapping[str, object]) -> str:
+        if ("page" in arguments) == ("path" in arguments):
+            raise ToolInputError("Give codetrail_brief either a page or a path, not both.")
+        if "page" in arguments:
+            page = _page(export, arguments["page"])
+            if page.kind == "digest":
+                raise ToolInputError(f"{page.id} is a digest; digests have no brief.")
+            return page.brief
+        path = _path(arguments["path"])
+        best: tuple[int, ExportedPage] | None = None
+        for page in export.pages:
+            if page.kind == "area":
+                for scope in page.scope_paths:
+                    if in_scope(path, [scope]) and (best is None or len(scope.strip("/")) > best[0]):
+                        best = (len(scope.strip("/")), page)
+        concepts = [page for page in export.pages if page.kind == "concept" and in_scope(path, page.scope_paths)]
+        chosen = ([best[1]] if best else []) + concepts
+        if not chosen:
+            return f"No page covers {path}; the map's Pages list what the guide covers."
+        return "\n\n".join(page.brief.rstrip() for page in chosen[: self.settings.max_briefs_per_call])
+
+    def _changes(self, export: AgentExport, arguments: Mapping[str, object]) -> str:
+        since = arguments.get("since")
+        digests = [page for page in export.pages if page.kind == "digest"]
+        notice = ""
+        if isinstance(since, str) and DATE.fullmatch(since):
+            try:
+                date.fromisoformat(since)
+            except ValueError as error:
+                raise ToolInputError(f"{since} isn't a date.") from error
+            found = [page for page in digests if page.written_at[:10] >= since]
+        elif isinstance(since, str) and COMMIT.fullmatch(since):
+            matches = {commit for commit in export.snapshots if commit.startswith(since)}
+            if len(matches) > 1:
+                raise ToolInputError(f"{since} matches several commits; give more characters.")
+            if matches:
+                positions = {commit: index for index, commit in enumerate(export.snapshots)}  # each commit's last
+                after = positions[matches.pop()]
+                found = [page for page in digests if positions.get(page.built_at, -1) > after]
+            else:
+                notice = f"{since} isn't a commit this guide knows; here are the latest digests.\n\n"
+                found = digests[: self.settings.recent_digests]
+        else:
+            raise ToolInputError("Give a commit (7 to 40 lower-case hexadecimal characters) or a date (YYYY-MM-DD).")
+        return notice + ("\n\n".join(page.text.rstrip() for page in found) or "No digests since then.")
+
+
+def _page(export: AgentExport, value: object) -> ExportedPage:
+    if not isinstance(value, str) or not PAGE_ID.fullmatch(value):
+        raise ToolInputError("A page id looks like areas/<name> or concepts/<name>.")
+    for page in export.pages:
+        if page.id == value:
+            return page
+    raise ToolInputError(f"{value} isn't a page in this guide; the map's Pages list them.")
+
+
+def _path(value: object) -> str:
+    if not isinstance(value, str) or len(value) > MAX_PATH_CHARS:
+        raise ToolInputError(f"A path is text of at most {MAX_PATH_CHARS} characters.")
+    if any(unicodedata.category(character) in ("Cc", "Cf") for character in value):
+        raise ToolInputError("A path can't hold control characters.")
+    path = value.strip()
+    while path.startswith("./"):
+        path = path[2:]
+    path = path.rstrip("/")
+    if not safe_path(path):
+        raise ToolInputError(f"{path or value!r} isn't a path relative to the repository's root.")
+    return path

codetrail/assistant/__init__.py

@@ -0,0 +1,161 @@
+"""The interface Codetrail needs from an assistant, shaped by Codetrail's tasks, not by any vendor (design 6.9, 15).
+
+Each provider (Claude Code, Codex, a local model) has its own adapter, the only code that knows it; tests use the fake.
+Every draft carries the call's usage: its tokens, and its cost when the provider or the configured prices give one.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from codetrail.errors import CodetrailError
+
+
+class AssistantError(CodetrailError):
+    """The assistant couldn't complete a task: an error, a limit reached, or no usable answer."""
+
+
+@dataclass(frozen=True)
+class PlanWindow:
+    """How much of a subscription's usage window is used (0 to 1), and when it resets (seconds since the epoch)."""
+
+    window: str  # "five_hour", "seven_day"...
+    utilization: float
+    resets_at: int
+
+
+@dataclass(frozen=True)
+class Usage:
+    """What one call used: tokens, and its cost in dollars when known (the provider's figure, or tokens x prices).
+
+    `input_tokens` counts input not read from a cache; `cached_input_tokens` counts input read from one.
+    """
+
+    provider: str = ""
+    model: str = ""
+    input_tokens: int = 0
+    cached_input_tokens: int = 0
+    output_tokens: int = 0
+    cost_usd: float | None = None
+    plan_windows: tuple[PlanWindow, ...] = ()
+
+
+@dataclass(frozen=True)
+class PlanRequest:
+    target: str
+    facts: str  # a rolled-up summary of the facts
+    existing_outline: str  # YAML, empty on the first run
+    uncovered: list[str] = field(default_factory=list)  # fact ids in no page's scope
+    paths_only: bool = False  # propose guided paths through the existing pages, and no new pages
+
+
+@dataclass(frozen=True)
+class PlanDraft:
+    pages: list[dict[str, Any]]
+    paths: list[dict[str, Any]] = field(default_factory=list)
+    files_read: list[str] = field(default_factory=list)
+    cost_usd: float = 0.0
+    usage: Usage = field(default_factory=Usage)
+
+
+@dataclass(frozen=True)
+class PageRequest:
+    page_id: str
+    kind: str
+    title: str
+    scope_paths: list[str]
+    facts: str
+    decisions: str
+    history: str
+    problems: list[str] = field(default_factory=list)  # from a failed validation, for the retry
+    previous_body: str = ""
+    # A revision (design 6.3): the page as it stands and what changed in its scope since it was written. With
+    # `changes`, the assistant returns only the sections to replace, and new checks only if the old ones don't fit.
+    current_body: str = ""
+    current_checks: list[dict[str, Any]] = field(default_factory=list)
+    changes: list[str] = field(default_factory=list)
+    brief_words: int = 300  # the brief for coding agents (design 23.3) has at most this many words
+    current_brief: str = ""  # a revision's brief as it stands; empty when the page has none yet
+
+
+@dataclass(frozen=True)
+class PageDraft:
+    body: str  # empty for a revision
+    checks: list[dict[str, Any]] = field(default_factory=list)
+    files_read: list[str] = field(default_factory=list)
+    cost_usd: float = 0.0
+    usage: Usage = field(default_factory=Usage)
+    sections: list[dict[str, Any]] = field(default_factory=list)  # a revision's sections: {"heading", "body"}
+    brief: str = ""  # the brief for coding agents; a revision may return none, keeping the page's
+
+
+@dataclass(frozen=True)
+class DigestRequest:
+    target: str
+    commits: str
+    fact_changes: str
+    pages_changed: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class DigestDraft:
+    title: str
+    body: str
+    files_read: list[str] = field(default_factory=list)
+    cost_usd: float = 0.0
+    usage: Usage = field(default_factory=Usage)
+
+
+@dataclass(frozen=True)
+class QuestionRequest:
+    target: str
+    question: str
+    language: str  # a validated, installed language code
+    page_title: str = ""
+    page_body: str = ""
+    page_facts: list[str] = field(default_factory=list)
+    diagrams: list[str] = field(default_factory=list)  # placeholders Codetrail can draw from this guide's facts
+
+
+@dataclass(frozen=True)
+class AnswerChunk:
+    """A piece of a streamed answer; the last one has `done` set, with the files read, the cost and the usage."""
+
+    text: str = ""
+    done: bool = False
+    files_read: list[str] = field(default_factory=list)
+    cost_usd: float = 0.0
+    usage: Usage = field(default_factory=Usage)
+
+
+@dataclass(frozen=True)
+class GradeRequest:
+    question: str
+    rubric: list[dict[str, Any]]
+    page_title: str
+    page_body: str
+    answer: str
+    language: str
+
+
+@dataclass(frozen=True)
+class Verdict:
+    verdict: str  # "pass", "partial" or "fail"; anything else is an error
+    missed: list[str] = field(default_factory=list)
+    feedback: str = ""
+    cost_usd: float = 0.0
+    usage: Usage = field(default_factory=Usage)
+
+
+class Assistant(Protocol):
+    async def plan(self, request: PlanRequest) -> PlanDraft: ...
+
+    async def write_page(self, request: PageRequest) -> PageDraft: ...
+
+    async def write_digest(self, request: DigestRequest) -> DigestDraft: ...
+
+    def answer(self, request: QuestionRequest) -> AsyncIterator[AnswerChunk]: ...
+
+    async def grade(self, request: GradeRequest) -> Verdict: ...

codetrail/assistant/claude_code.py

@@ -0,0 +1,330 @@
+"""The claude_code adapter: the reader's own `claude -p`, read-only, on the reader's sign-in (design 15.1, 15.2).
+
+Each call runs `claude -p` in `source/` with the prompt on stdin and two independent read-only layers: Claude Code's
+own permissions (only Read, Grep and Glob, allowed only under the working folder, `dontAsk` refusing the rest) and
+Codetrail's tool guard as a PreToolUse hook. No settings, MCP servers or slash commands of the reader's or the
+target's load. The environment comes from an allowlist, so with a subscription no key is visible. Structured answers
+come back through the `StructuredOutput` tool; usage, cost and the plan's usage windows come from the stream.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import sys
+import tempfile
+from collections.abc import AsyncIterator, Iterator, Mapping
+from contextlib import aclosing, contextmanager
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Final
+
+import anyio
+
+from codetrail.assistant import (
+    AnswerChunk,
+    AssistantError,
+    DigestDraft,
+    DigestRequest,
+    GradeRequest,
+    PageDraft,
+    PageRequest,
+    PlanDraft,
+    PlanRequest,
+    PlanWindow,
+    QuestionRequest,
+    Usage,
+    Verdict,
+    runner,
+)
+from codetrail.assistant.environment import child_environment, resolve_program
+from codetrail.assistant.guard import ALLOWED_TOOLS
+from codetrail.assistant.prompts import (
+    ANSWER_RULES,
+    DIGEST_SCHEMA,
+    GRADE_RULES,
+    GRADE_SCHEMA,
+    GROUND_RULES,
+    PAGE_SYNTAX,
+    PLAN_SCHEMA,
+    answer_prompt,
+    digest_prompt,
+    grade_prompt,
+    neutralize,
+    page_task,
+    plan_prompt,
+)
+from codetrail.config import ClaudeCodeSettings, GenerationSettings
+
+PROVIDER: Final = "claude_code"
+
+
+class _ProgramFailed(AssistantError):
+    """The program ended without a result: worth another try."""
+
+
+@dataclass
+class _Outcome:
+    result: dict[str, Any] | None = None
+    windows: dict[str, PlanWindow] = field(default_factory=dict)
+
+
+class ClaudeCodeAssistant:
+    def __init__(
+        self,
+        source_root: Path,
+        models: Mapping[str, str],
+        settings: ClaudeCodeSettings,
+        limits: GenerationSettings,
+        retries: int = 2,
+        answer_limits: tuple[int, float] = (20, 1.0),
+        grade_budget_usd: float = 0.25,
+        environ: Mapping[str, str] = os.environ,
+    ) -> None:
+        self.root = source_root.resolve()
+        self.models = dict(models)
+        self.settings = settings
+        self.limits = limits
+        self.retries = retries
+        self.answer_limits = answer_limits  # max turns and budget of one bridge answer
+        self.grade_budget_usd = grade_budget_usd
+        self.environment = child_environment(PROVIDER, settings.auth, environ)
+        self.program = resolve_program(settings.command, self.environment.get("PATH", ""))
+
+    async def plan(self, request: PlanRequest) -> PlanDraft:
+        data, files, usage = await self._run("plan", plan_prompt(request), PLAN_SCHEMA, GROUND_RULES)
+        return PlanDraft(list(data.get("pages", [])), list(data.get("paths", [])), files, _cost(usage), usage)
+
+    async def write_page(self, request: PageRequest) -> PageDraft:
+        prompt, schema = page_task(request)  # a new page, or a revision's sections
+        data, files, usage = await self._run("write", prompt, schema, GROUND_RULES + "\n" + PAGE_SYNTAX)
+        return PageDraft(str(data.get("body", "")), list(data.get("checks", [])), files, _cost(usage), usage,
+                         list(data.get("sections", [])), str(data.get("brief", "")))  # fmt: skip
+
+    async def write_digest(self, request: DigestRequest) -> DigestDraft:
+        data, files, usage = await self._run(
+            "digest", digest_prompt(request), DIGEST_SCHEMA, GROUND_RULES + "\n" + PAGE_SYNTAX
+        )
+        return DigestDraft(str(data.get("title", "")), str(data.get("body", "")), files, _cost(usage), usage)
+
+    async def grade(self, request: GradeRequest) -> Verdict:
+        """Grades with no tools at all: only the check, the rubric, the page and the answer (design section 8.2)."""
+        data, _files, usage = await self._run(
+            "grade", grade_prompt(request), GRADE_SCHEMA, GRADE_RULES, tools=(), budget_usd=self.grade_budget_usd
+        )
+        missed = [str(item) for item in data.get("missed", [])]
+        return Verdict(str(data.get("verdict", "")), missed, str(data.get("feedback", "")), _cost(usage), usage)
+
+    async def answer(self, request: QuestionRequest) -> AsyncIterator[AnswerChunk]:
+        """Streams the answer's text as Claude writes it, then a final chunk with the files read and the usage."""
+        model = self.models["answer"]
+        outcome = _Outcome()
+        with self._call_files() as (settings_file, read_log):
+            command = self._command(
+                model,
+                None,
+                GROUND_RULES + "\n" + PAGE_SYNTAX + "\n" + ANSWER_RULES,
+                ALLOWED_TOOLS,
+                self.answer_limits[0],
+                self.answer_limits[1],
+                settings_file,
+                partial=True,
+            )
+            lines = runner.run_program(
+                command, neutralize(answer_prompt(request)), self.root, self.environment, self.settings.timeout_seconds
+            )
+            async with aclosing(lines):
+                async for event in _events(lines):
+                    text = _text_delta(event)
+                    if text:
+                        yield AnswerChunk(text=text)
+                    _note(event, outcome)
+            result = _finished(outcome)
+            usage = _usage(result, model, outcome)
+            yield AnswerChunk(done=True, files_read=_read(read_log), cost_usd=_cost(usage), usage=usage)
+
+    async def _run(
+        self,
+        kind: str,
+        prompt: str,
+        schema: dict[str, Any],
+        system_prompt: str,
+        tools: tuple[str, ...] = ALLOWED_TOOLS,
+        budget_usd: float | None = None,
+    ) -> tuple[dict[str, Any], list[str], Usage]:
+        model = self.models[kind]
+        budget = self.limits.max_budget_usd_per_call if budget_usd is None else budget_usd
+        last_error: Exception | None = None
+        for attempt in range(self.retries + 1):
+            if attempt:
+                await anyio.sleep(2)
+            outcome = _Outcome()
+            with self._call_files() as (settings_file, read_log):
+                command = self._command(
+                    model, schema, system_prompt, tools, self.limits.max_turns, budget, settings_file
+                )
+                try:
+                    lines = runner.run_program(
+                        command, neutralize(prompt), self.root, self.environment, self.settings.timeout_seconds
+                    )
+                    async with aclosing(lines):
+                        async for event in _events(lines):
+                            _note(event, outcome)
+                except AssistantError as error:
+                    if outcome.result is not None:
+                        raise
+                    last_error = _ProgramFailed(str(error))
+                    continue
+                result = _finished(outcome)
+                data = result.get("structured_output")
+                if not isinstance(data, dict):
+                    raise AssistantError("Claude Code finished without a structured answer.")
+                return data, _read(read_log), _usage(result, model, outcome)
+        raise last_error or AssistantError("Claude Code couldn't be run.")
+
+    def _command(
+        self,
+        model: str,
+        schema: dict[str, Any] | None,
+        system_prompt: str,
+        tools: tuple[str, ...],
+        max_turns: int,
+        budget_usd: float,
+        settings_file: Path,
+        partial: bool = False,
+    ) -> list[str]:
+        command = [
+            self.program,
+            "-p",
+            "--output-format",
+            "stream-json",
+            "--verbose",
+            "--tools",
+            ",".join(tools),
+            "--permission-mode",
+            "dontAsk",
+            "--setting-sources",
+            "",
+            "--strict-mcp-config",
+            "--disable-slash-commands",
+            "--no-session-persistence",
+            "--settings",
+            str(settings_file),
+            "--max-turns",
+            str(max_turns),
+            "--max-budget-usd",
+            f"{budget_usd:g}",
+            "--model",
+            model,
+            "--system-prompt",
+            system_prompt,
+        ]
+        if tools:
+            # Reads are allowed only under the working folder; dontAsk refuses everything else, hook or not.
+            command += ["--allowedTools", *(f"{tool}(./**)" for tool in tools)]
+        if schema is not None:
+            command += ["--json-schema", json.dumps(schema)]
+        if partial:
+            command.append("--include-partial-messages")
+        return command
+
+    @contextmanager
+    def _call_files(self) -> Iterator[tuple[Path, Path]]:
+        """The settings file with the guard hook, and the hook's read log: private, outside `source/`, removed after."""
+        with tempfile.TemporaryDirectory(prefix="codetrail-call-") as folder:
+            read_log = Path(folder) / "reads.log"
+            # -I: the hook must import Codetrail's guard, never a `codetrail` folder in `source/` (the working folder).
+            parts = (sys.executable, "-I", "-m", "codetrail.assistant.guard_hook", str(self.root), str(read_log))
+            hook = " ".join(shlex.quote(part) for part in parts)
+            settings = {
+                "hooks": {
+                    "PreToolUse": [
+                        {
+                            "matcher": "*",
+                            "hooks": [
+                                {"type": "command", "command": hook, "timeout": self.settings.hook_timeout_seconds}
+                            ],
+                        }
+                    ]
+                }
+            }
+            settings_file = Path(folder) / "settings.json"
+            descriptor = os.open(settings_file, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+            with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+                json.dump(settings, handle)
+            yield settings_file, read_log
+
+
+async def _events(lines: AsyncIterator[str]) -> AsyncIterator[dict[str, Any]]:
+    """The stream's JSON events; a line that isn't a JSON object is skipped."""
+    async for line in lines:
+        try:
+            event = json.loads(line)
+        except ValueError:
+            continue
+        if isinstance(event, dict):
+            yield event
+
+
+def _note(event: dict[str, Any], outcome: _Outcome) -> None:
+    if event.get("type") == "result":
+        outcome.result = event
+    elif event.get("type") == "rate_limit_event":
+        windows = (event.get("rate_limit_info") or {}).get("unifiedWindows") or {}
+        for name, window in windows.items():
+            if isinstance(window, dict):
+                try:
+                    outcome.windows[str(name)] = PlanWindow(
+                        str(name), float(window["utilization"]), int(window["resetsAt"])
+                    )
+                except KeyError, TypeError, ValueError:
+                    continue
+
+
+def _text_delta(event: dict[str, Any]) -> str:
+    if event.get("type") != "stream_event":
+        return ""
+    inner = event.get("event") or {}
+    delta = inner.get("delta") or {}
+    if inner.get("type") == "content_block_delta" and delta.get("type") == "text_delta":
+        return str(delta.get("text", ""))
+    return ""
+
+
+def _finished(outcome: _Outcome) -> dict[str, Any]:
+    result = outcome.result
+    if result is None:
+        raise AssistantError("Claude Code ended without a result.")
+    if result.get("is_error"):
+        raise AssistantError(f"Claude Code didn't finish the task ({result.get('subtype', 'error')}).")
+    return result
+
+
+def _usage(result: dict[str, Any], model: str, outcome: _Outcome) -> Usage:
+    usage = result.get("usage") or {}
+
+    def count(key: str) -> int:
+        value = usage.get(key, 0)
+        return int(value) if isinstance(value, int | float) else 0
+
+    cost = result.get("total_cost_usd")
+    return Usage(
+        PROVIDER,
+        model,
+        input_tokens=count("input_tokens") + count("cache_creation_input_tokens"),
+        cached_input_tokens=count("cache_read_input_tokens"),
+        output_tokens=count("output_tokens"),
+        cost_usd=float(cost) if isinstance(cost, int | float) else None,
+        plan_windows=tuple(outcome.windows.values()),
+    )
+
+
+def _cost(usage: Usage) -> float:
+    return usage.cost_usd or 0.0
+
+
+def _read(read_log: Path) -> list[str]:
+    if not read_log.exists():
+        return []
+    return list(dict.fromkeys(line for line in read_log.read_text(encoding="utf-8").splitlines() if line))