coder-eval 0.8.2__py3-none-any.whl

coder_eval/models/enums.py

@@ -0,0 +1,121 @@
+"""Enumeration types for coder_eval."""
+
+from enum import StrEnum
+from typing import Literal
+
+
+class FinalStatus(StrEnum):
+    """Final evaluation status for a task."""
+
+    SUCCESS = "SUCCESS"
+    FAILURE = "FAILURE"
+    ERROR = "ERROR"
+    BUILD_FAILED = "BUILD_FAILED"
+    TIMEOUT = "TIMEOUT"
+    MAX_TURNS_EXHAUSTED = "MAX_TURNS_EXHAUSTED"
+    TOKEN_BUDGET_EXCEEDED = "TOKEN_BUDGET_EXCEEDED"
+    COST_BUDGET_EXCEEDED = "COST_BUDGET_EXCEEDED"
+
+    @property
+    def category(self) -> Literal["succeeded", "failed", "error"]:
+        """Classify this status into a reporting category (the SSOT for failed/succeeded/error)."""
+        return _STATUS_CATEGORIES[self]
+
+    @property
+    def icon(self) -> str:
+        """Single-character icon for reports and CLI output."""
+        return _STATUS_ICONS[self]
+
+
+# Every FinalStatus maps to exactly one reporting category, listed EXPLICITLY (no
+# catch-all default) so a newly-added status fails the assert below until it is
+# classified — rather than silently collapsing into "failed" (which would skew
+# reports AND the telemetry Category dimension). Mirrors the _STATUS_ICONS guard.
+_STATUS_CATEGORIES: dict[FinalStatus, Literal["succeeded", "failed", "error"]] = {
+    FinalStatus.SUCCESS: "succeeded",
+    FinalStatus.FAILURE: "failed",
+    FinalStatus.ERROR: "error",
+    # A failed image build is an environment/setup error, not a task outcome —
+    # group it with ERROR so reports/telemetry don't read it as a legitimate
+    # task failure the agent could have avoided.
+    FinalStatus.BUILD_FAILED: "error",
+    FinalStatus.TIMEOUT: "failed",
+    FinalStatus.MAX_TURNS_EXHAUSTED: "failed",
+    FinalStatus.TOKEN_BUDGET_EXCEEDED: "failed",
+    FinalStatus.COST_BUDGET_EXCEEDED: "failed",
+}
+
+assert set(_STATUS_CATEGORIES) == set(FinalStatus), "Missing category for FinalStatus member"
+
+
+_STATUS_ICONS: dict[FinalStatus, str] = {
+    FinalStatus.SUCCESS: "+",
+    FinalStatus.FAILURE: "-",
+    FinalStatus.ERROR: "!",
+    FinalStatus.BUILD_FAILED: "B",
+    FinalStatus.TIMEOUT: "T",
+    FinalStatus.MAX_TURNS_EXHAUSTED: "M",
+    FinalStatus.TOKEN_BUDGET_EXCEEDED: "#",
+    FinalStatus.COST_BUDGET_EXCEEDED: "$",
+}
+
+assert set(_STATUS_ICONS) == set(FinalStatus), "Missing icon for FinalStatus member"
+
+
+class ApiBackend(StrEnum):
+    """API backend for LLM calls."""
+
+    DIRECT = "direct"  # Anthropic API directly (ANTHROPIC_API_KEY)
+    BEDROCK = "bedrock"  # AWS Bedrock (bearer token auth)
+
+
+class PermissionMode(StrEnum):
+    """Permission modes for agent tool access."""
+
+    DEFAULT = "default"
+    ACCEPT_EDITS = "acceptEdits"
+    PLAN = "plan"
+    BYPASS_PERMISSIONS = "bypassPermissions"
+
+
+class PreservationMode(StrEnum):
+    """How a task's sandbox is persisted (or not) after execution.
+
+    The run-level CLI default is *driver-derived* (resolved at the dispatch
+    seam in ``orchestration.batch``): ``docker`` → ``DIRECT_WRITE`` (the
+    container is isolated, and writing straight to the bind-mounted artifacts
+    dir avoids a cross-mount copy), every other driver → ``MOVE_ON_WRITE``
+    (running under ``run_dir/artifacts`` on a shared host would let parent-dir
+    ``node_modules`` contaminate Node tool resolution — see MST-9795/PR #257).
+    An explicit ``--preservation-mode`` always wins over that default.
+    """
+
+    NONE = "NONE"  # Run in a tempdir, delete it on cleanup (no artifacts kept).
+    MOVE_ON_WRITE = "MOVE_ON_WRITE"  # Run in a tempdir, shutil.move into run_dir/artifacts at the end.
+    DIRECT_WRITE = "DIRECT_WRITE"  # Run directly in run_dir/artifacts; nothing to move (left in place).
+
+
+class AgentKind(StrEnum):
+    """Named constants for the built-in agent kinds.
+
+    These are NOT the closed set of valid agent types: ``agent.type`` is an open
+    string validated against the ``AgentRegistry`` (which plugins extend via the
+    ``coder_eval.plugins`` entry point). This enum just gives the framework's own
+    code stable references to the built-ins; the registry is authoritative.
+    """
+
+    CLAUDE_CODE = "claude-code"
+    CODEX = "codex"
+    ANTIGRAVITY = "antigravity"
+    NONE = "none"  # Agentless / system task — no coding agent runs; success criteria do all the work.
+    UNKNOWN = "unknown"  # Used when agent type cannot be determined (e.g., task loading failure)
+
+
+class AgentState(StrEnum):
+    """Possible states of the agent during execution."""
+
+    WORKING = "working"
+    WAITING_FOR_USER = "waiting_for_user"
+    CODE_PROPOSAL = "code_proposal"
+    FINISHED = "finished"
+    ERROR = "error"

coder_eval/models/experiment.py

@@ -0,0 +1,314 @@
+"""Experiment definition models for multi-run configurations."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, Literal, Self
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from coder_eval.models.enums import FinalStatus
+from coder_eval.models.limits import RunLimits
+from coder_eval.models.mutations import PromptMutation
+from coder_eval.models.results import ConfigLineageEntry, EvaluationResult
+from coder_eval.models.sandbox import SandboxConfig
+from coder_eval.models.tasks import PostRunCommand, PreRunCommand, TaskDefinition
+from coder_eval.models.templates import TemplateSource
+
+
+class ExperimentVariant(BaseModel):
+    """A named configuration variant within an experiment."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    variant_id: str = Field(description="Unique identifier for this variant (e.g., 'sonnet', 'opus')")
+    description: str = Field(default="", description="Human-readable description of what this variant tests")
+    agent: dict[str, Any] | None = Field(default=None, description="Partial agent config overrides")
+    simulation: dict[str, Any] | None = Field(
+        default=None,
+        description=(
+            "Partial SimulationConfig overrides for this variant. Shallow-merged onto the task's "
+            "simulation block (and/or experiment defaults) — common use cases are overriding the "
+            "simulator persona/model/temperature per variant."
+        ),
+    )
+    repeats: int | None = Field(
+        default=None,
+        ge=1,
+        description="Number of replicates for each task under this variant. None = inherit.",
+    )
+    template_sources: list[TemplateSource] | None = Field(
+        default=None, description="Additional template sources appended after task's base templates"
+    )
+    prompt_mutations: list[PromptMutation] | None = Field(
+        default=None, description="Ordered list of mutations to apply to the task's initial_prompt"
+    )
+    initial_prompt: str | None = Field(
+        default=None,
+        description="Full replacement for the task's initial_prompt. Mutually exclusive with prompt_mutations.",
+    )
+    initial_prompt_file: str | None = Field(
+        default=None,
+        description=(
+            "Path to a file containing a full replacement initial_prompt (relative to experiment YAML). "
+            "Mutually exclusive with initial_prompt and prompt_mutations."
+        ),
+    )
+    run_limits: RunLimits | None = Field(
+        default=None,
+        description=(
+            "Per-variant overrides for the task's run_limits block. Field-merge — "
+            "per-key precedence inside the block; keys absent here leave the task-level "
+            "value intact."
+        ),
+    )
+    driver: Literal["tempdir", "docker"] | None = Field(
+        default=None,
+        description=(
+            "Override the sandbox driver for this variant. Slots into layer 4 of the "
+            "5-layer config merge; None inherits from task/experiment-defaults. "
+            "Enables variant-A=tempdir vs variant-B=docker comparisons."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def check_prompt_exclusivity(self) -> Self:
+        """Ensure prompt_mutations, initial_prompt, and initial_prompt_file are mutually exclusive."""
+        set_fields = []
+        if self.prompt_mutations is not None:
+            set_fields.append("prompt_mutations")
+        if self.initial_prompt is not None:
+            set_fields.append("initial_prompt")
+        if self.initial_prompt_file is not None:
+            set_fields.append("initial_prompt_file")
+        if len(set_fields) > 1:
+            raise ValueError(f"Only one of {', '.join(set_fields)} can be provided, not multiple")
+        return self
+
+
+class ExperimentDefaults(BaseModel):
+    """Default settings applied to all variants (overridable per-variant and per-task)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    repeats: int | None = Field(
+        default=None,
+        ge=1,
+        description="Default number of replicates across all variants. None = 1 (no repetition).",
+    )
+    agent: dict[str, Any] | None = Field(default=None, description="Partial agent config defaults")
+    simulation: dict[str, Any] | None = Field(
+        default=None,
+        description=(
+            "Default simulation config applied to tasks that do not set one explicitly. "
+            "Fields map to SimulationConfig (enabled, persona, goal, model, max_turns, n_trials, ...)."
+        ),
+    )
+    template_sources: list[TemplateSource] | None = Field(
+        default=None, description="Additional template sources appended after task's base templates (for all variants)"
+    )
+    prompt_mutations: list[PromptMutation] | None = Field(
+        default=None, description="Default prompt mutations applied to all variants (before variant-specific mutations)"
+    )
+    post_run: list[PostRunCommand] | None = Field(
+        default=None,
+        description="Default post-run commands appended after each task's own post_run (run for every task).",
+    )
+    pre_run: list[PreRunCommand] | None = Field(
+        default=None,
+        description="Default pre-run commands prepended before each task's own pre_run (run for every task).",
+    )
+    run_limits: RunLimits | None = Field(
+        default=None,
+        description=(
+            "Default run-time caps (turns, wall-clock, tokens, USD). "
+            "Field-merge — task and variant layers override individual keys without replacing the block."
+        ),
+    )
+    driver: Literal["tempdir", "docker"] | None = Field(
+        default=None,
+        description=(
+            "Default sandbox driver applied to all tasks under this experiment. Slots into "
+            "layer 2 of the 5-layer merge; variant- and task-level driver fields override it."
+        ),
+    )
+    sandbox: SandboxConfig | None = Field(
+        default=None,
+        description=(
+            "Default sandbox config applied to all tasks under this experiment. "
+            "Field-merge — task and variant layers override individual keys without replacing the block."
+        ),
+    )
+
+
+class ExperimentDefinition(BaseModel):
+    """Complete experiment definition with base settings and variants."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    experiment_id: str = Field(description="Kebab-case identifier for this experiment")
+    description: str = Field(default="", description="Human-readable description")
+    defaults: ExperimentDefaults | None = Field(default=None, description="Default settings applied to all variants")
+    variants: list[ExperimentVariant] = Field(description="Configuration variants (at least 1)")
+
+    @field_validator("experiment_id")
+    @classmethod
+    def validate_experiment_id(cls, v: str) -> str:
+        if not re.match(r"^[a-z0-9]+(-[a-z0-9]+)*$", v):
+            raise ValueError(f"experiment_id '{v}' must be kebab-case (e.g., 'model-comparison')")
+        return v
+
+    @model_validator(mode="after")
+    def validate_variants(self) -> ExperimentDefinition:
+        if len(self.variants) < 1:
+            raise ValueError("Experiment must have at least 1 variant")
+        ids = [v.variant_id for v in self.variants]
+        if len(ids) != len(set(ids)):
+            raise ValueError(f"Variant IDs must be unique, got duplicates in: {ids}")
+        return self
+
+
+class VariantResult(BaseModel):  # noqa: CE009 -- persisted result model; round-trip leniency like models/results.py
+    """Result for a single variant on a single task."""
+
+    variant_id: str
+    task_id: str
+    weighted_score: float
+    final_status: FinalStatus
+    duration_seconds: float
+    total_tokens: int | None = None
+    iteration_count: int | None = None
+    total_assistant_turns: int | None = None
+    reference_similarity: float | None = None
+    replicate_index: int = Field(
+        default=0,
+        ge=0,
+        description="Replicate index for this per-task result (0 when no replicates).",
+    )
+    replicate_count: int = Field(
+        default=1,
+        ge=1,
+        description="Number of replicates aggregated into this VariantResult (1 when repeats disabled).",
+    )
+
+
+class VariantAggregate(BaseModel):  # noqa: CE009 -- persisted result model; round-trip leniency like models/results.py
+    """Aggregated statistics for a single variant across all tasks."""
+
+    variant_id: str
+    tasks_run: int
+    tasks_succeeded: int
+    tasks_failed: int
+    tasks_error: int
+    average_score: float
+    average_duration: float
+    total_tokens: int | None = None
+    replicate_count: int = Field(
+        default=1,
+        ge=1,
+        description="Replicate multiplicity (modal value across tasks).",
+    )
+    # Sub-counters of tasks_failed (NOT part of the task_count invariant).
+    tasks_token_budget_exceeded: int = Field(
+        default=0,
+        ge=0,
+        description="Subset of tasks_failed where run_limits token caps tripped.",
+    )
+    tasks_cost_budget_exceeded: int = Field(
+        default=0,
+        ge=0,
+        description="Subset of tasks_failed where run_limits cost cap tripped.",
+    )
+
+    @model_validator(mode="after")
+    def _check_task_count_invariant(self) -> VariantAggregate:
+        if self.tasks_succeeded + self.tasks_failed + self.tasks_error != self.tasks_run:
+            total = f"{self.tasks_succeeded} + {self.tasks_failed} + {self.tasks_error}"
+            raise ValueError(f"Task count invariant violated: {total} != {self.tasks_run}")
+        return self
+
+
+class TaskExperimentSummary(BaseModel):  # noqa: CE009 -- persisted result model; round-trip leniency like models/results.py
+    """Cross-variant summary for a single task."""
+
+    task_id: str
+    variant_results: list[VariantResult]
+    best_variant: str
+    is_tie: bool = Field(default=False, description="True when multiple variants share the highest score")
+    score_spread: float
+    replicate_count: int = Field(
+        default=1,
+        ge=1,
+        description="Replicate count per variant on this task. Drives Replicate Statistics rendering.",
+    )
+
+
+class ExperimentResult(BaseModel):  # noqa: CE009 -- persisted result model; round-trip leniency like models/results.py
+    """Top-level experiment result with per-task summaries and variant aggregates."""
+
+    experiment_id: str
+    description: str
+    variant_ids: list[str]
+    task_summaries: list[TaskExperimentSummary]
+    variant_aggregates: dict[str, VariantAggregate]
+    total_duration_seconds: float
+    per_replicate_scores: dict[str, dict[str, list[float]]] = Field(
+        default_factory=dict,
+        description=(
+            "Raw weighted_score per replicate, keyed variant_id → task_id → [scores]. "
+            "Always populated by aggregate_results; list length equals the replicate count. "
+            "Empty dict only on deserialized results from before this field existed."
+        ),
+    )
+
+
+class ResolvedTask(BaseModel):  # noqa: CE009 -- programmatic resolution model, not YAML input
+    """A fully-resolved task ready for batch execution.
+
+    Created by the resolution phase after applying all 5 config layers
+    (default → experiment defaults → task YAML → variant → CLI).
+    Consumed by run_batch() as the sole input type.
+    """
+
+    task: TaskDefinition
+    task_file: Path
+    run_dir: Path
+    variant_id: str
+    source_yaml: str = ""
+    config_lineage: dict[str, ConfigLineageEntry] = Field(default_factory=dict)
+    replicate_index: int = Field(
+        default=0,
+        ge=0,
+        description=(
+            "0-based replicate index within the (task, variant) group. Set by resolve_all_tasks. "
+            "Always 0 for single-shot tasks and for simulation tasks with n_trials=1. "
+            "Simulation tasks with n_trials > 1 are expanded into replicate_index=0..n_trials-1."
+        ),
+    )
+
+
+class TaskResult(BaseModel):  # noqa: CE009 -- persisted result model; round-trip leniency like models/results.py
+    """Result from executing a single resolved task.
+
+    Replaces the untyped dict[str, Any] with keys {task_id, result, duration}
+    that previously flowed between run_batch and aggregate_results.
+    """
+
+    task_id: str
+    result: EvaluationResult
+    duration: float
+    variant_id: str
+    suite_id: str | None = Field(
+        default=None,
+        description="Parent suite id when this task came from dataset fan-out. Signal for suite rollup reporting.",
+    )
+    row_id: str | None = Field(
+        default=None,
+        description="Row id within the suite (from Dataset.id_field) when this task came from dataset fan-out.",
+    )
+    replicate_index: int = Field(
+        default=0,
+        ge=0,
+        description="0-based replicate index from ResolvedTask. Populated by batch.py.",
+    )

coder_eval/models/judge.py

@@ -0,0 +1,90 @@
+"""Typed verdict contract for judge-style criteria (llm_judge, agent_judge)."""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class JudgeVerdict(BaseModel):
+    """Typed contract for a judge's verdict.
+
+    Used both as the tool-input schema for the ``submit_verdict`` call (across
+    SDK MCP and Anthropic-native ``tools``) and as the validation target for the
+    extractors in ``coder_eval.evaluation.verdict_tool``.
+
+    Score is clamped to [0.0, 1.0] by a validator (not a Field constraint) so
+    out-of-range values from the model become 0.0/1.0 rather than tool-input
+    validation errors. Non-finite values (NaN, +/-Infinity) are rejected
+    explicitly because ``max(0.0, min(1.0, nan))`` silently yields 1.0.
+    Booleans are rejected because Python treats them as ints.
+
+    ``findings`` carries the audit trail — the system prompt always asks
+    the judge to emit it. The field stays optional on the wire so a model
+    that drops it still parses (the parser never falls back to score=0.0
+    for missing findings), but the empty-findings case should be rare.
+    """
+
+    model_config = {"extra": "ignore"}
+
+    score: float = Field(description="Verdict score, clamped to [0.0, 1.0]")
+    rationale: str = Field(default="", description="1-2 sentence headline summary")
+    findings: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Concrete observations the judge cited from the artifacts (e.g. 'main.py:12 missing return'). "
+            "Each entry is a short bullet. Empty when the judge omitted them."
+        ),
+    )
+
+    @field_validator("score", mode="before")
+    @classmethod
+    def _clamp_score(cls, v: Any) -> float:
+        if isinstance(v, bool):
+            raise ValueError(f"score is not a number: {v!r}")
+        try:
+            f = float(v)
+        except (TypeError, ValueError) as e:
+            raise ValueError(f"score is not a number: {v!r}") from e
+        if not math.isfinite(f):
+            raise ValueError(f"score is not finite: {v!r}")
+        return max(0.0, min(1.0, f))
+
+    @field_validator("rationale", mode="before")
+    @classmethod
+    def _coerce_rationale(cls, v: Any) -> str:
+        if v is None:
+            return ""
+        if not isinstance(v, str):
+            raise ValueError(f"rationale must be a string, got {type(v).__name__}")
+        # Collapse internal whitespace (newlines, tabs, runs of spaces) to single
+        # spaces. Two reasons:
+        #   1. ``format_details`` writes "rationale: <text>" on one line; a multi-line
+        #      rationale would break that single-line invariant.
+        #   2. ``reports_html._extract_rationale`` parses by line and grabs only the
+        #      first one starting with "rationale: " — multi-line content would be
+        #      silently truncated in the Judge Verdicts card.
+        # The schema asks for "1-2 sentence headline summary"; collapsing whitespace
+        # makes that contract explicit.
+        collapsed = " ".join(v.split())
+        if not collapsed:
+            # Whitespace-only / empty input surfaces as a validation error so the
+            # judge result records the error string instead of silently emitting
+            # a blank ``rationale: `` line in ``format_details``. The
+            # ``extract_verdict_from_*`` extractors translate the
+            # ``ValidationError`` into a JudgeCriterionResult(score=0.0, error=...)
+            # — uniform shape across all three backends.
+            raise ValueError("rationale is empty after whitespace collapse")
+        return collapsed
+
+    @field_validator("findings", mode="before")
+    @classmethod
+    def _coerce_findings(cls, v: Any) -> list[str]:
+        # Same leniency: drop anything that doesn't look like a list of strings.
+        if v is None:
+            return []
+        if not isinstance(v, list):
+            return []
+        return [str(x).strip() for x in v if x is not None and str(x).strip()]

coder_eval/models/judge_defaults.py

@@ -0,0 +1,11 @@
+"""Shared judge default constants.
+
+Split out of ``models/tasks.py`` so that both ``models/tasks.py`` and
+``models/criteria.py`` can import ``DEFAULT_JUDGE_MODEL`` without
+introducing an import cycle (``tasks.py`` already imports from
+``criteria.py``). Keep this a leaf module — it must NOT import from
+``criteria.py`` / ``tasks.py``.
+"""
+
+DEFAULT_JUDGE_MODEL = "anthropic.claude-sonnet-4-6"
+"""Default model used by the LLM judge (``LLMJudgeCriterion.model``)."""

coder_eval/models/limits.py

@@ -0,0 +1,89 @@
+"""Run-time budget limits for task execution."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class RunLimits(BaseModel):
+    """Run-time caps that abort a task when exceeded.
+
+    Unifies structural caps (max_turns, task_timeout, turn_timeout) and
+    budget caps (tokens, USD). Budget caps are checked after each completed
+    agent turn and are cumulative across all turns of a single task; they
+    apply to the subject agent only — judge and simulator token spend are
+    not counted.
+
+    Any subset of fields is valid; an empty block is legal.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    max_turns: int | None = Field(
+        default=None,
+        gt=0,
+        description="Max agent inner-loop turns per iteration. None = SDK default.",
+    )
+    expected_turns: int | None = Field(
+        default=None,
+        ge=1,
+        description=(
+            "Soft target for cumulative visible turns across a task. A 'turn' is one "
+            "entry in the Turn timeline: each tool call contributes 1, plus 1 for the "
+            "final reply when present. "
+            "When the running total exceeds this, the orchestrator logs a one-shot "
+            "warning and the report renders a badge — the run is NOT aborted "
+            "(use max_turns for a hard cap). None disables the check."
+        ),
+    )
+    task_timeout: int | None = Field(
+        default=None,
+        ge=30,
+        description="Max seconds for the entire evaluation loop (all iterations). None = no limit.",
+    )
+    turn_timeout: int | None = Field(
+        default=None,
+        ge=10,
+        description="Max seconds per agent communicate() call. None = no limit.",
+    )
+    max_input_tokens: int | None = Field(
+        default=None,
+        ge=1,
+        description="Max cumulative input (prompt) tokens. None = unlimited.",
+    )
+    max_output_tokens: int | None = Field(
+        default=None,
+        ge=1,
+        description="Max cumulative output (completion) tokens. None = unlimited.",
+    )
+    max_total_tokens: int | None = Field(
+        default=None,
+        ge=1,
+        description="Max cumulative input+output tokens. None = unlimited.",
+    )
+    max_usd: float | None = Field(
+        default=None,
+        gt=0.0,
+        description=(
+            "Max cumulative cost in USD. Requires per-turn cost reporting "
+            "(SDK-provided cost). Silently skipped if cost "
+            "is None for every turn."
+        ),
+    )
+    count_cached_input: bool = Field(
+        default=False,
+        description=(
+            "When True, cache_read_input_tokens count toward input/total "
+            "budgets. Default False — cached reads are typically free."
+        ),
+    )
+    count_cache_creation: bool = Field(
+        default=False,
+        description=(
+            "When True, cache_creation_input_tokens count toward input/total "
+            "budgets. Needed to budget Codex prompt input: the Codex agent buckets "
+            "the fresh (full-price) prompt slice into cache_creation, so with this "
+            "False a Codex token budget caps only output. Default False preserves "
+            "existing behavior (Claude reports real cache-creation writes here)."
+        ),
+    )